man3/ftw.3

   1 .\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
   2 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   3 .\" Fri Jun 25 00:34:07 CEST 1999
   4 .\"
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, write to the Free
  22 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  23 .\" USA.
  24 .\"
  25 .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
  26 .TH FTW 3 1999-06-25 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 ftw, nftw \- file tree walk
  29 .SH SYNOPSIS
  30 .B #include <ftw.h>
  31 .sp
  32 .BI "int ftw(const char *" dir ", int (*" fn ")(const"
  33 .BI "char *" file ", const struct stat *" sb ", int " flag ),
  34 .BI "int " nopenfd );
  35 .sp
  36 .BI "int nftw(const char *" dir ", int (*" fn ")(const"
  37 .BI "char *" file ", const struct stat *" sb ", int " flag ,
  38 .BI "struct FTW *" s ),
  39 .BI "int " nopenfd ", int " flags );
  40 .SH DESCRIPTION
  41 \fBftw\fP() walks through the directory tree starting from the indicated
  42 directory \fIdir\fP.  For each found entry in the tree, it calls
  43 \fIfn\fP() with the full pathname of the entry, a pointer to the
  44 .BR stat (2)
  45 structure for the entry and an int \fIflag\fP, which value will be one of
  46 the following:
  47 .TP
  48 .B FTW_F
  49 Item is a normal file
  50 .TP
  51 .B FTW_D
  52 Item is a directory
  53 .TP
  54 .B FTW_DNR
  55 Item is a directory which can't be read
  56 .TP
  57 .B FTW_SL
  58 Item is a symbolic link
  59 .TP
  60 .B FTW_NS
  61 The stat failed on the item which is not a symbolic link
  62 .LP
  63 If the item is a symbolic link and stat failed, XPG4v2 states
  64 that it is undefined whether FTW_NS or FTW_SL is used.
  65 .PP
  66 \fBftw\fP() recursively calls itself for traversing found directories,
  67 handling a directory before its files or subdirectories.
  68 To avoid using up all a program's file descriptors, \fInopenfd\fP
  69 specifies the maximum number of simultaneous open directories.  When
  70 the search depth exceeds this, \fBftw\fP() will become slower because
  71 directories have to be closed and reopened. \fBftw\fP() uses at most
  72 one file descriptor for each level in the file hierarchy.
  73 .PP
  74 To stop the tree walk, \fIfn\fP() returns a non-zero value; this
  75 value will become the return value of \fBftw\fP().  Otherwise,
  76 \fBftw\fP() will continue until it has traversed the entire tree, in
  77 which case it will return zero, or until it hits an error other than EACCES
  78 (such as a
  79 .BR malloc (3)
  80 failure), in which case it will return \-1.
  81 .PP
  82 Because \fBftw\fP() uses dynamic data structures, the only safe way to
  83 exit out of a tree walk is to return a non-zero value.  To handle
  84 interrupts, for example, mark that the interrupt occurred and return a
  85 non-zero value\(emdon't use
  86 .BR longjmp (3)
  87 unless the program is going to terminate.
  88
  89 The function \fBnftw\fP() does precisely the same as \fBftw\fP(),
  90 except that it has one additional argument \fIflags\fP
  91 (and calls the supplied function with one more argument).
  92 This \fIflags\fP argument is an OR of zero or more of the following flags:
  93 .TP
  94 .B FTW_CHDIR
  95 If set, do a
  96 .IR chdir ()
  97 to each directory before handling its contents.
  98 .TP
  99 .B FTW_DEPTH
 100 If set, do a depth-first search, that is, call the function for
 101 the directory itself only after handling the contents of the directory
 102 and its subdirectories.
 103 .TP
 104 .B FTW_MOUNT
 105 If set, stay within the same file system.
 106 .TP
 107 .B FTW_PHYS
 108 If set, do not follow symbolic links.
 109 (This is what you want.)
 110 If not set, symbolic links are followed, but no file is reported twice.
 111 .LP
 112 If FTW_PHYS is not set, but FTW_DEPTH is set, then the function
 113 .IR fn ()
 114 is never called for a directory that would be a descendant of itself.
 115 .LP
 116 The function
 117 .IR fn ()
 118 is called with four arguments: the pathname of the reported entry,
 119 a pointer to a struct stat for this entry, an integer describing
 120 its type, and a pointer to a struct FTW. The type will be one
 121 of the following: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS
 122 (with meaning as above; FTW_SL occurs only with FTW_PHYS set) or
 123 .TP
 124 .B FTW_DP
 125 Item is a directory and all its descendants have been handled
 126 already. (This occurs only with FTW_DEPTH set.)
 127 .TP
 128 .B FTW_SLN
 129 Item is a symbolic link pointing to a nonexisting file.
 130 (This occurs only with FTW_PHYS unset.)
 131 .LP
 132 The struct FTW pointed to by the fourth argument to
 133 .IR fn ()
 134 has at least the fields
 135 .IR base ,
 136 the offset of the item's filename in the pathname
 137 given as first argument of
 138 .IR fn (),
 139 and
 140 .IR level ,
 141 the depth of the item relative to the starting point
 142 (which has depth 0).
 143 .SH NOTES
 144 The function
 145 .IR nftw ()
 146 and the use of FTW_SL with
 147 .IR ftw ()
 148 were introduced in XPG4v2.
 149 .LP
 150 On some systems
 151 .IR ftw ()
 152 will never use FTW_SL, on other systems FTW_SL occurs only
 153 for symbolic links that do not point to an existing file,
 154 and again on other systems
 155 .IR ftw ()
 156 will use FTW_SL for each symbolic link. For predictable control, use
 157 .IR nftw ().
 158 .LP
 159 Under Linux, libc4 and libc5 and glibc 2.0.6 will
 160 use FTW_F for all objects (files, symbolic links, fifos, etc)
 161 that can be stat'ed but are not a directory.
 162 The function
 163 .IR nftw ()
 164 is available since glibc 2.1.
 165 .SH "CONFORMING TO"
 166 AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.
 167 .SH "SEE ALSO"
 168 .BR stat (2)