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@gmail.com>
   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@gmail.com>
  31 .\"     reorganized and rewrote much of the page
  32 .\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
  33 .\"     Added an example program.
  34 .TH FTW 3 2007-07-26 "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 .BI "        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 .BR ftw ()
  56 walks through the directory tree that is
  57 located under the directory \fIdirpath\fP,
  58 and calls \fIfn\fP() once for each entry in the tree.
  59 By default, directories are handled before the files and
  60 subdirectories they contain (pre-order traversal).
  61
  62 To avoid using up all of the calling process's file descriptors,
  63 \fInopenfd\fP specifies the maximum number of directories that
  64 .BR ftw ()
  65 will hold open simultaneously.
  66 When
  67 the search depth exceeds this,
  68 .BR ftw ()
  69 will become slower because
  70 directories have to be closed and reopened.
  71 .BR ftw ()
  72 uses at most
  73 one file descriptor for each level in the directory tree.
  74
  75 For each entry found in the tree,
  76 .BR ftw ()
  77 calls
  78 \fIfn\fP() with three arguments:
  79 .IR fpath ,
  80 .IR sb ,
  81 and
  82 .IR typeflag .
  83 .I fpath
  84 is the pathname of the entry relative to
  85 .IR dirpath .
  86 .I sb
  87 is a pointer to the
  88 .I stat
  89 structure returned by a call to
  90 .BR stat (2)
  91 for
  92 .IR fpath .
  93 .I typeflag
  94 is an integer that has one of the following values:
  95 .TP
  96 .B FTW_F
  97 .I fpath
  98 is a regular file.
  99 .TP
 100 .B FTW_D
 101 .I fpath
 102 is a directory.
 103 .TP
 104 .B FTW_DNR
 105 .I fpath
 106 is a directory which can't be read.
 107 .TP
 108 .B FTW_NS
 109 The
 110 .BR stat (2)
 111 call failed on
 112 .IR fpath ,
 113 which is not a symbolic link.
 114 .sp
 115 If
 116 .I fpath
 117 is a symbolic link and
 118 .BR stat (2)
 119 failed, POSIX.1-2001 states
 120 that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below)
 121 is passed in
 122 .IR typeflag .
 123 .PP
 124 To stop the tree walk, \fIfn\fP() returns a non-zero value; this
 125 value will become the return value of
 126 .BR ftw ().
 127 As long as \fIfn\fP() returns 0,
 128 .BR ftw ()
 129 will continue either until it has traversed the entire tree,
 130 in which case it will return zero,
 131 or until it encounters an error (such as a
 132 .BR malloc (3)
 133 failure), in which case it will return \-1.
 134 .PP
 135 Because
 136 .BR ftw ()
 137 uses dynamic data structures, the only safe way to
 138 exit out of a tree walk is to return a non-zero value from \fIfn\fP().
 139 To allow a signal to terminate the walk without causing a memory leak,
 140 have the handler set a global flag that is checked by \fIfn\fP().
 141 \fIDon't\fP use
 142 .BR longjmp (3)
 143 unless the program is going to terminate.
 144 .SS nftw()
 145 The function
 146 .BR nftw ()
 147 is the same as
 148 .BR ftw (),
 149 except that it has one additional argument, \fIflags\fP,
 150 and calls \fIfn\fP() with one more argument, \fIftwbuf\fP.
 151
 152 This \fIflags\fP argument is formed by ORing zero or more of the
 153 following flags:
 154 .TP
 155 .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
 156 If this glibc-specific flag is set, then
 157 .BR nftw ()
 158 handles the return value from
 159 .IR fn ()
 160 differently.
 161 .IR fn ()
 162 should return one of the following values:
 163 .RS
 164 .TP
 165 .B FTW_CONTINUE
 166 Instructs
 167 .BR nftw ()
 168 to continue normally.
 169 .TP
 170 .B FTW_SKIP_SIBLINGS
 171 If \fIfn\fP() returns this value, then
 172 siblings of the current entry will be skipped,
 173 and processing continues in the parent.
 174 .\" If \fBFTW_DEPTH\fP
 175 .\" is set, the entry's parent directory is processed next (with
 176 .\" \fIflag\fP set to \fBFTW_DP\fP).
 177 .TP
 178 .B FTW_SKIP_SUBTREE
 179 If \fIfn\fP() is called with an entry that is a directory
 180 (\fItypeflag\fP is \fBFTW_D\fP), this return
 181 value will prevent objects within that directory from being passed as
 182 arguments to \fIfn\fP().
 183 .BR nftw ()
 184 continues processing with the next sibling of the directory.
 185 .TP
 186 .B FTW_STOP
 187 Causes
 188 .BR nftw ()
 189 to return immediately with the return value
 190 \fBFTW_STOP\fP.
 191 .PP
 192 Other return values could be associated with new actions in the future;
 193 \fIfn\fP() should not return values other than those listed above.
 194
 195 The feature test macro
 196 .B _GNU_SOURCE
 197 must be defined in order to
 198 obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
 199 .RE
 200 .TP
 201 .B FTW_CHDIR
 202 If set, do a
 203 .BR chdir (2)
 204 to each directory before handling its contents.
 205 This is useful if the program needs to perform some action
 206 in the directory in which \fIfpath\fP resides.
 207 .TP
 208 .B FTW_DEPTH
 209 If set, do a post-order traversal, that is, call \fIfn\fP() for
 210 the directory itself \fIafter\fP handling the contents of the directory
 211 and its subdirectories.
 212 (By default, each directory is handled \fIbefore\fP its contents.)
 213 .TP
 214 .B FTW_MOUNT
 215 If set, stay within the same file system
 216 (i.e., do not cross mount points).
 217 .TP
 218 .B FTW_PHYS
 219 If set, do not follow symbolic links.
 220 (This is what you want.)
 221 If not set, symbolic links are followed, but no file is reported twice.
 222 .sp
 223 If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
 224 then the function
 225 .IR fn ()
 226 is never called for a directory that would be a descendant of itself.
 227 .LP
 228 For each entry in the directory tree,
 229 .BR nftw ()
 230 calls
 231 .IR fn ()
 232 with four arguments.
 233 .I fpath
 234 and
 235 .I sb
 236 are as for
 237 .BR ftw ().
 238 .I typeflag
 239 may receive any of the same values as with
 240 .BR ftw (),
 241 or any of the following values:
 242 .TP
 243 .B FTW_DP
 244 .I fpath
 245 is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
 246 All of the files
 247 and subdirectories within \fIfpath\fP have been processed.
 248 .TP
 249 .B FTW_SL
 250 .I fpath
 251 is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
 252 .\" To obtain the definition of this constant from
 253 .\" .IR <ftw.h> ,
 254 .\" either
 255 .\" .B _BSD_SOURCE
 256 .\" must be defined, or
 257 .\" .BR _XOPEN_SOURCE
 258 .\" must be defined with a value of 500 or more.
 259 .TP
 260 .B FTW_SLN
 261 .I fpath
 262 is a symbolic link pointing to a nonexistent file.
 263 (This occurs only if \fBFTW_PHYS\fP is not set.)
 264 .LP
 265 The fourth argument that
 266 .BR nftw ()
 267 supplies when calling
 268 \fIfn\fP()
 269 is a structure of type \fIFTW\fP:
 270 .in +4n
 271 .nf
 272
 273 struct FTW {
 274     int base;
 275     int level;
 276 };
 277
 278 .fi
 279 .in
 280 .I base
 281 is the offset of the filename (i.e., basename component)
 282 in the pathname given in
 283 .IR fpath .
 284 .I level
 285 is the depth of
 286 .I fpath
 287 in the directory tree, relative to the root of the tree
 288 .RI ( dirpath ,
 289 which has depth 0).
 290 .SH "RETURN VALUE"
 291 These functions return 0 on success, and \-1 if an error occurs.
 292
 293 If \fIfn\fP() returns non-zero,
 294 then the tree walk is terminated and the value returned by \fIfn\fP()
 295 is returned as the result of
 296 .BR ftw ()
 297 or
 298 .BR nftw ().
 299
 300 If
 301 .BR nftw ()
 302 is called with the \fBFTW_ACTIONRETVAL\fP flag,
 303 then the only non-zero value that should be used by \fIfn\fP()
 304 to terminate the tree walk is \fBFTW_STOP\fP,
 305 and that value is returned as the result of
 306 .BR nftw ().
 307 .SH "CONFORMING TO"
 308 POSIX.1-2001, SVr4, SUSv1.
 309 .SH NOTES
 310 The function
 311 .BR nftw ()
 312 and the use of \fBFTW_SL\fP with
 313 .BR ftw ()
 314 were introduced in SUSv1.
 315 .LP
 316 On some systems
 317 .BR ftw ()
 318 will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
 319 for symbolic links that do not point to an existing file,
 320 and again on other systems
 321 .BR ftw ()
 322 will use \fBFTW_SL\fP for each symbolic link.
 323 For predictable control, use
 324 .BR nftw ().
 325 .LP
 326 Under Linux, libc4 and libc5 and glibc 2.0.6 will
 327 use \fBFTW_F\fP for all objects (files, symbolic links, FIFOs, etc.)
 328 that can be stat'ed but are not a directory.
 329
 330 The function
 331 .BR nftw ()
 332 is available since glibc 2.1.
 333
 334 \fBFTW_ACTIONRETVAL\fP is glibc-specific.
 335 .SH EXAMPLE
 336 The following program traverses the directory tree under the path named
 337 in its first command-line argument, or under the current directory
 338 if no argument is supplied.
 339 It displays various information about each file.
 340 The second command-line argument can be used to specify characters that
 341 control the value assigned to the \fIflags\fP
 342 argument when calling
 343 .BR nftw ().
 344 .nf
 345
 346 #define _XOPEN_SOURCE 500
 347 #include <ftw.h>
 348 #include <stdio.h>
 349 #include <stdlib.h>
 350 #include <string.h>
 351 #include <stdint.h>
 352
 353 static int
 354 display_info(const char *fpath, const struct stat *sb,
 355              int tflag, struct FTW *ftwbuf)
 356 {
 357     printf("%\-3s %2d %7jd   %\-40s %d %s\\n",
 358         (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
 359         (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
 360         (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
 361         (tflag == FTW_SLN) ? "sln" : "???",
 362         ftwbuf\->level, (intmax_t) sb\->st_size,
 363         fpath, ftwbuf\->base, fpath + ftwbuf\->base);
 364     return 0;           /* To tell nftw() to continue */
 365 }
 366
 367 int
 368 main(int argc, char *argv[])
 369 {
 370     int flags = 0;
 371
 372     if (argc > 2 && strchr(argv[2], 'd') != NULL)
 373         flags |= FTW_DEPTH;
 374     if (argc > 2 && strchr(argv[2], 'p') != NULL)
 375         flags |= FTW_PHYS;
 376
 377     if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
 378             == \-1) {
 379         perror("nftw");
 380         exit(EXIT_FAILURE);
 381     }
 382     exit(EXIT_SUCCESS);
 383 }
 384 .fi
 385 .SH "SEE ALSO"
 386 .BR stat (2),
 387 .BR fts (3),
 388 .BR readdir (3),
 389 .BR feature_test_macros (7)