man3/ftw.3

   1 .\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
   2 .\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   3 .\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net>
   4 .\" and copyright (c) 2006 Michael Kerrisk <mtk-manpages@gmx.net>
   5 .\"
   6 .\" This is free documentation; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public License as
   8 .\" published by the Free Software Foundation; either version 2 of
   9 .\" the License, or (at your option) any later version.
  10 .\"
  11 .\" The GNU General Public License's references to "object code"
  12 .\" and "executables" are to be interpreted as the output of any
  13 .\" document formatting or typesetting system, including
  14 .\" intermediate and printed output.
  15 .\"
  16 .\" This manual is distributed in the hope that it will be useful,
  17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 .\" GNU General Public License for more details.
  20 .\"
  21 .\" You should have received a copy of the GNU General Public
  22 .\" License along with this manual; if not, write to the Free
  23 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  24 .\" USA.
  25 .\"
  26 .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
  27 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net>
  28 .\"     document FTW_ACTIONRETVAL; include .SH "RETURN VALUE";
  29 .\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and
  30 .\"     Michael Kerrisk <mtk-manpages@gmx.net>
  31 .\"     reorganized and rewrote much of the page
  32 .\" 2006-05-24, Michael Kerrisk <mtk-manpages@gmx.net>
  33 .\"     Added an example program.
  34 .TH FTW 3 2006-05-24 "Linux" "Linux Programmer's Manual"
  35 .SH NAME
  36 ftw, nftw \- file tree walk
  37 .SH SYNOPSIS
  38 .nf
  39 .B #include <ftw.h>
  40 .sp
  41 .BI "int ftw(const char *" dirpath ,
  42 .BR "        int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
  43 .BI "                   int " typeflag ),
  44 .BI "        int " nopenfd );
  45 .sp
  46 .B #define _XOPEN_SOURCE 500
  47 .B #include <ftw.h>
  48 .sp
  49 .BI "int nftw(const char *" dirpath ,
  50 .BI "        int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
  51 .BI "                   int " typeflag ", struct FTW *" ftwbuf ),
  52 .BI "        int " nopenfd ", int " flags );
  53 .fi
  54 .SH DESCRIPTION
  55 \fBftw\fP() walks through the directory tree that is
  56 located under the directory \fIdirpath\fP,
  57 and calls \fIfn\fP() once for each entry in the tree.
  58 By default, directories are handled before the files and
  59 subdirectories they contain (pre-order traversal).
  60
  61 To avoid using up all of the calling process's file descriptors,
  62 \fInopenfd\fP specifies the maximum number of directories that
  63 \fBftw\fP() will hold open simultaneously.
  64 When
  65 the search depth exceeds this, \fBftw\fP() will become slower because
  66 directories have to be closed and reopened. \fBftw\fP() uses at most
  67 one file descriptor for each level in the directory tree.
  68
  69 For each entry found in the tree,
  70 .BR ftw ()
  71 calls
  72 \fIfn\fP() with three arguments:
  73 .IR fpath ,
  74 .IR sb ,
  75 and
  76 .IR typeflag .
  77 .IR fpath
  78 is the pathname of the entry relative to
  79 .IR dirpath .
  80 .IR sb
  81 is a pointer to the
  82 .IR stat
  83 structure returned by a call to
  84 .BR stat (2)
  85 for
  86 .IR fpath .
  87 .IR typeflag
  88 is an integer that has one of the following values:
  89 .TP
  90 .B FTW_F
  91 .I fpath
  92 is a normal file.
  93 .TP
  94 .B FTW_D
  95 .I fpath
  96 is a directory.
  97 .TP
  98 .B FTW_DNR
  99 .I fpath
 100 is a directory which can't be read.
 101 .TP
 102 .B FTW_NS
 103 The
 104 .BR stat (2)
 105 call failed on
 106 .IR fpath ,
 107 which is not a symbolic link.
 108 .sp
 109 If
 110 .I fpath
 111 is a symbolic link and
 112 .BR stat (2)
 113 failed, POSIX.1-2001 states
 114 that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below)
 115 is passed in
 116 .IR typeflag .
 117 .PP
 118 To stop the tree walk, \fIfn\fP() returns a non-zero value; this
 119 value will become the return value of \fBftw\fP().
 120 As long as \fIfn\fP() returns 0,
 121 \fBftw\fP() will continue either until it has traversed the entire tree,
 122 in which case it will return zero,
 123 or until it encounters an error (such as a
 124 .BR malloc (3)
 125 failure), in which case it will return \-1.
 126 .PP
 127 Because \fBftw\fP() uses dynamic data structures, the only safe way to
 128 exit out of a tree walk is to return a non-zero value from \fIfn\fP().
 129 To allow a signal to terminate the walk without causing a memory leak,
 130 have the handler set a global flag that is checked by \fIfn\fP().
 131 \fIDon't\fP use \fBlongjmp\fP(3) unless the program is going to terminate.
 132 .SS nftw()
 133 The function \fBnftw\fP() is the same as \fBftw\fP(),
 134 except that it has one additional argument, \fIflags\fP,
 135 and calls \fIfn\fP() with one more argument, \fIftwbuf\fP.
 136
 137 This \fIflags\fP argument is formed by ORing zero or more of the
 138 following flags:
 139 .TP
 140 .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
 141 If this glibc-specific flag is set, then
 142 .BR nftw ()
 143 handles the return value from
 144 .IR fn ()
 145 differently.
 146 .IR fn ()
 147 should return one of the following values:
 148 .RS
 149 .TP
 150 .B FTW_CONTINUE
 151 Instructs \fBnftw\fP() to continue normally.
 152 .TP
 153 .B FTW_SKIP_SIBLINGS
 154 If \fIfn\fP() returns this value, then
 155 siblings of the current entry will be skipped,
 156 and processing continues in the parent.
 157 .\" If \fBFTW_DEPTH\fP
 158 .\" is set, the entry's parent directory is processed next (with
 159 .\" \fIflag\fP set to \fBFTW_DP\fP).
 160 .TP
 161 .B FTW_SKIP_SUBTREE
 162 If \fIfn\fP() is called with an entry that is a directory
 163 (\fItypeflag\fP is \fBFTW_D\fP), this return
 164 value will prevent objects within that directory from being passed as
 165 arguments to \fIfn\fP().
 166 .BR nftw ()
 167 continues processing with the next sibling of the directory.
 168 .TP
 169 .B FTW_STOP
 170 Causes \fBnftw\fP() to return immediately with the return value
 171 \fBFTW_STOP\fP.
 172 .PP
 173 Other return values could be associated with new actions in the future;
 174 \fIfn\fP() should not return values other than those listed above.
 175
 176 The feature test macro _GNU_SOURCE must be defined in order to
 177 obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
 178 .RE
 179 .TP
 180 .B FTW_CHDIR
 181 If set, do a
 182 .BR chdir (2)
 183 to each directory before handling its contents.
 184 This is useful if the program needs to perform some action
 185 in the directory in which \fIfpath\fP resides.
 186 .TP
 187 .B FTW_DEPTH
 188 If set, do a post-order traversal, that is, call \fIfn\fP() for
 189 the directory itself \fIafter\fP handling the contents of the directory
 190 and its subdirectories.
 191 (By default, each directory is handled \fIbefore\fP its contents.)
 192 .TP
 193 .B FTW_MOUNT
 194 If set, stay within the same file system
 195 (i.e., do not cross mount points).
 196 .TP
 197 .B FTW_PHYS
 198 If set, do not follow symbolic links.
 199 (This is what you want.)
 200 If not set, symbolic links are followed, but no file is reported twice.
 201 .sp
 202 If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
 203 then the function
 204 .IR fn ()
 205 is never called for a directory that would be a descendant of itself.
 206 .LP
 207 For each entry in the directory tree,
 208 .BR nftw ()
 209 calls
 210 .IR fn ()
 211 with four arguments.
 212 .I fpath
 213 and
 214 .I sb
 215 are as for
 216 .BR ftw ().
 217 .I typeflag
 218 may receive any of the same values as with
 219 .BR ftw (),
 220 or any of the following values:
 221 .TP
 222 .B FTW_DP
 223 .I fpath
 224 is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
 225 All of the files
 226 and subdirectories within \fIfpath\fP have been processed.
 227 .TP
 228 .B FTW_SL
 229 .I fpath
 230 is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
 231 .TP
 232 .B FTW_SLN
 233 .I fpath
 234 is a symbolic link pointing to a nonexistent file.
 235 (This occurs only if \fBFTW_PHYS\fP is not set.)
 236 .LP
 237 The fourth argument that
 238 .BR nftw ()
 239 supplies when calling
 240 \fIfn\fP()
 241 is a structure of type \fIFTW\fP:
 242 .in +0.25i
 243 .nf
 244
 245 struct FTW {
 246     int base;
 247     int level;
 248 };
 249
 250 .fi
 251 .in -0.25i
 252 .I base
 253 is the offset of the filename (i.e., basename component)
 254 in the pathname given in
 255 .IR fpath .
 256 .IR level
 257 is the depth of
 258 .I fpath
 259 in the directory tree, relative to the root of the tree
 260 .RI ( dirpath ,
 261 which has depth 0).
 262 .SH "RETURN VALUE"
 263 These functions return 0 on success, and \-1 if an error occurs.
 264
 265 If \fIfn\fP() returns non-zero,
 266 then the tree walk is terminated and the value returned by \fIfn\fP()
 267 is returned as the result of \fBftw\fP() or \fBnftw\fP().
 268
 269 If \fBnftw\fP() is called with the \fBFTW_ACTIONRETVAL\fP flag,
 270 then the only non-zero value that should be used by \fIfn\fP()
 271 to terminate the tree walk is \fBFTW_STOP\fP,
 272 and that value is returned as the result of \fBnftw\fP().
 273 .SH NOTES
 274 The function
 275 .BR nftw ()
 276 and the use of \fBFTW_SL\fP with
 277 .BR ftw ()
 278 were introduced in SUSv1.
 279 .LP
 280 On some systems
 281 .BR ftw ()
 282 will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
 283 for symbolic links that do not point to an existing file,
 284 and again on other systems
 285 .BR ftw ()
 286 will use \fBFTW_SL\fP for each symbolic link. For predictable control, use
 287 .BR nftw ().
 288 .LP
 289 Under Linux, libc4 and libc5 and glibc 2.0.6 will
 290 use \fBFTW_F\fP for all objects (files, symbolic links, fifos, etc)
 291 that can be stat'ed but are not a directory.
 292
 293 The function
 294 .BR nftw ()
 295 is available since glibc 2.1.
 296
 297 \fBFTW_ACTIONRETVAL\fP is glibc specific.
 298 .SH "CONFORMING TO"
 299 POSIX.1-2001, SVr4, SUSv1.
 300 .SH EXAMPLE
 301 The following program traverses the directory tree under the path named
 302 in its first command-line argument, or under the current directory
 303 if no argument is supplied.
 304 It displays various information about each file.
 305 The second-command line argument can be used to specify characters that
 306 control the value assigned to the \fIflags\fP
 307 argument when calling \fBnftw\fP().
 308 .nf
 309
 310 #define _XOPEN_SOURCE 500
 311 #include <ftw.h>
 312 #include <stdio.h>
 313 #include <stdlib.h>
 314 #include <string.h>
 315
 316 static int
 317 display_info(const char *fpath, const struct stat *sb,
 318              int tflag, struct FTW *ftwbuf)
 319 {
 320     printf("%-3s %2d %7lld   %-40s %d %s\\n",
 321         (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
 322         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
 323         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_SL) ?  "sl" :
 324         (tflag == FTW_SLN) ? "sln" : "???",
 325         ftwbuf->level, (long long) sb->st_size,
 326         fpath, ftwbuf->base, fpath + ftwbuf->base);
 327     return 0;           /* To tell nftw() to continue */
 328 }
 329
 330 int
 331 main(int argc, char *argv[])
 332 {
 333     int flags = 0;
 334
 335     if (argc > 2 && strchr(argv[2], 'd') != NULL)
 336         flags |= FTW_DEPTH;
 337     if (argc > 2 && strchr(argv[2], 'p') != NULL)
 338         flags |= FTW_PHYS;
 339
 340     nftw((argc < 2) ? "." : argv[1], display_info, 20, flags);
 341     exit(EXIT_SUCCESS);
 342 }
 343 .fi
 344 .SH "SEE ALSO"
 345 .BR stat (2),
 346 .BR fts (3),
 347 .BR readdir (3)