1FTS(3)                     Linux Programmer's Manual                    FTS(3)
2
3
4

NAME

6       fts,  fts_open, fts_read, fts_children, fts_set, fts_close - traverse a
7       file hierarchy
8

SYNOPSIS

10       #include <sys/types.h>
11       #include <sys/stat.h>
12       #include <fts.h>
13
14       FTS *fts_open(char * const *path_argv, int options,
15                     int (*compar)(const FTSENT **, const FTSENT **));
16
17       FTSENT *fts_read(FTS *ftsp);
18
19       FTSENT *fts_children(FTS *ftsp, int options);
20
21       int fts_set(FTS *ftsp, FTSENT *f, int options);
22
23       int fts_close(FTS *ftsp);
24

DESCRIPTION

26       The fts functions are provided for traversing file hierarchies.  A sim‐
27       ple  overview  is  that the fts_open() function returns a "handle" on a
28       file hierarchy, which is then supplied to the other fts functions.  The
29       function  fts_read() returns a pointer to a structure describing one of
30       the files in the file hierarchy.  The function fts_children() returns a
31       pointer  to a linked list of structures, each of which describes one of
32       the files contained in a  directory  in  the  hierarchy.   In  general,
33       directories are visited two distinguishable times; in pre-order (before
34       any of their descendants are visited) and in post-order (after  all  of
35       their  descendants  have been visited).  Files are visited once.  It is
36       possible to walk the hierarchy "logically" (ignoring symbolic links) or
37       physically  (visiting  symbolic links), order the walk of the hierarchy
38       or prune and/or re-visit portions of the hierarchy.
39
40       Two structures are defined (and typedef'd) in the include file <fts.h>.
41       The  first  is  FTS,  the  structure that represents the file hierarchy
42       itself.  The second is FTSENT, the structure that represents a file  in
43       the  file  hierarchy.   Normally,  an  FTSENT structure is returned for
44       every file in the file hierarchy.  In  this  manual  page,  "file"  and
45       "FTSENT structure" are generally interchangeable.  The FTSENT structure
46       contains at least the following fields, which are described in  greater
47       detail below:
48
49           typedef struct _ftsent {
50               unsigned short fts_info;     /* flags for FTSENT structure */
51               char          *fts_accpath;  /* access path */
52               char          *fts_path;     /* root path */
53               short          fts_pathlen;  /* strlen(fts_path) */
54               char          *fts_name;     /* filename */
55               short          fts_namelen;  /* strlen(fts_name) */
56               short          fts_level;    /* depth (-1 to N) */
57               int            fts_errno;    /* file errno */
58               long           fts_number;   /* local numeric value */
59               void          *fts_pointer;  /* local address value */
60               struct ftsent *fts_parent;   /* parent directory */
61               struct ftsent *fts_link;     /* next file structure */
62               struct ftsent *fts_cycle;    /* cycle structure */
63               struct stat   *fts_statp;    /* stat(2) information */
64           } FTSENT;
65
66       These fields are defined as follows:
67
68       fts_info    One  of  the following flags describing the returned FTSENT
69                   structure and the file it represents.  With  the  exception
70                   of directories without errors (FTS_D), all of these entries
71                   are terminal, that is, they will not be revisited, nor will
72                   any of their descendants be visited.
73
74                   FTS_D       A directory being visited in pre-order.
75
76                   FTS_DC      A  directory  that  causes a cycle in the tree.
77                               (The fts_cycle field of  the  FTSENT  structure
78                               will be filled in as well.)
79
80                   FTS_DEFAULT Any  FTSENT  structure  that  represents a file
81                               type not explicitly described  by  one  of  the
82                               other fts_info values.
83
84                   FTS_DNR     A  directory  which cannot be read.  This is an
85                               error return, and the fts_errno field  will  be
86                               set to indicate what caused the error.
87
88                   FTS_DOT     A file named "."  or ".."  which was not speci‐
89                               fied as a filename to fts_open() (see  FTS_SEE‐
90                               DOT).
91
92                   FTS_DP      A  directory  being visited in post-order.  The
93                               contents  of  the  FTSENT  structure  will   be
94                               unchanged  from  when  it  was returned in pre-
95                               order, that is, with the fts_info field set  to
96                               FTS_D.
97
98                   FTS_ERR     This  is  an  error  return,  and the fts_errno
99                               field will be set to indicate what  caused  the
100                               error.
101
102                   FTS_F       A regular file.
103
104                   FTS_NS      A  file  for  which  no stat(2) information was
105                               available.  The contents of the fts_statp field
106                               are  undefined.   This  is an error return, and
107                               the fts_errno field will  be  set  to  indicate
108                               what caused the error.
109
110                   FTS_NSOK    A  file  for  which  no stat(2) information was
111                               requested.  The contents of the fts_statp field
112                               are undefined.
113
114                   FTS_SL      A symbolic link.
115
116                   FTS_SLNONE  A symbolic link with a nonexistent target.  The
117                               contents of the fts_statp field  reference  the
118                               file  characteristic  information  for the sym‐
119                               bolic link itself.
120
121       fts_accpath A path for accessing the file from the current directory.
122
123       fts_path    The path for the file relative to the root of  the  traver‐
124                   sal.   This  path contains the path specified to fts_open()
125                   as a prefix.
126
127       fts_pathlen The length of the string referenced by fts_path.
128
129       fts_name    The name of the file.
130
131       fts_namelen The length of the string referenced by fts_name.
132
133       fts_level   The depth of the traversal, numbered from -1  to  N,  where
134                   this file was found.  The FTSENT structure representing the
135                   parent of the starting point (or root) of the traversal  is
136                   numbered  -1,  and the FTSENT structure for the root itself
137                   is numbered 0.
138
139       fts_errno   Upon return of a FTSENT structure from  the  fts_children()
140                   or  fts_read()  functions,  with  its fts_info field set to
141                   FTS_DNR, FTS_ERR or FTS_NS, the  fts_errno  field  contains
142                   the  value  of  the  external variable errno specifying the
143                   cause  of  the  error.   Otherwise,  the  contents  of  the
144                   fts_errno field are undefined.
145
146       fts_number  This  field is provided for the use of the application pro‐
147                   gram and is not modified by the fts functions.  It is  ini‐
148                   tialized to 0.
149
150       fts_pointer This  field is provided for the use of the application pro‐
151                   gram and is not modified by the fts functions.  It is  ini‐
152                   tialized to NULL.
153
154       fts_parent  A  pointer  to the FTSENT structure referencing the file in
155                   the hierarchy immediately above the current file, that  is,
156                   the  directory  of  which  this file is a member.  A parent
157                   structure for the initial entry point is provided as  well,
158                   however,  only  the  fts_level,  fts_number and fts_pointer
159                   fields are guaranteed to be initialized.
160
161       fts_link    Upon return from the fts_children() function, the  fts_link
162                   field  points  to the next structure in the NULL-terminated
163                   linked list of directory members.  Otherwise, the  contents
164                   of the fts_link field are undefined.
165
166       fts_cycle   If  a  directory  causes  a  cycle  in  the  hierarchy (see
167                   FTS_DC), either because of a hard link between two directo‐
168                   ries,  or  a  symbolic  link  pointing  to a directory, the
169                   fts_cycle field of the structure will point to  the  FTSENT
170                   structure in the hierarchy that references the same file as
171                   the current FTSENT structure.  Otherwise, the  contents  of
172                   the fts_cycle field are undefined.
173
174       fts_statp   A pointer to stat(2) information for the file.
175
176       A single buffer is used for all of the paths of all of the files in the
177       file hierarchy.  Therefore, the fts_path  and  fts_accpath  fields  are
178       guaranteed  to  be  NULL-terminated  only  for  the  file most recently
179       returned by fts_read().  To use these fields  to  reference  any  files
180       represented  by other FTSENT structures will require that the path buf‐
181       fer be modified using the information contained in that  FTSENT  struc‐
182       ture's  fts_pathlen  field.   Any  such  modifications should be undone
183       before further calls to fts_read() are attempted.  The  fts_name  field
184       is always NULL-terminated.
185
186   fts_open()
187       The fts_open() function takes a pointer to an array of character point‐
188       ers naming one or more paths which make up a logical file hierarchy  to
189       be traversed.  The array must be terminated by a NULL pointer.
190
191       There  are a number of options, at least one of which (either FTS_LOGI‐
192       CAL or FTS_PHYSICAL) must be specified.  The options  are  selected  by
193       oring the following values:
194
195       FTS_COMFOLLOW
196                    This  option  causes any symbolic link specified as a root
197                    path to be followed immediately whether or not FTS_LOGICAL
198                    is also specified.
199
200       FTS_LOGICAL  This  option  causes  the  fts  routines  to return FTSENT
201                    structures for the targets of symbolic  links  instead  of
202                    the symbolic links themselves.  If this option is set, the
203                    only  symbolic  links  for  which  FTSENT  structures  are
204                    returned to the application are those referencing nonexis‐
205                    tent files.  Either FTS_LOGICAL or  FTS_PHYSICAL  must  be
206                    provided to the fts_open() function.
207
208       FTS_NOCHDIR  As  a  performance  optimization, the fts functions change
209                    directories as they walk the file hierarchy.  This has the
210                    side-effect  that  an  application cannot rely on being in
211                    any  particular  directory  during  the  traversal.    The
212                    FTS_NOCHDIR  option  turns  off this optimization, and the
213                    fts functions will not change the current directory.  Note
214                    that  applications should not themselves change their cur‐
215                    rent directory and try to access files unless  FTS_NOCHDIR
216                    is specified and absolute pathnames were provided as argu‐
217                    ments to fts_open().
218
219       FTS_NOSTAT   By default,  returned  FTSENT  structures  reference  file
220                    characteristic information (the statp field) for each file
221                    visited.  This option relaxes that requirement as  a  per‐
222                    formance  optimization,  allowing the fts functions to set
223                    the fts_info field to FTS_NSOK and leave the  contents  of
224                    the statp field undefined.
225
226       FTS_PHYSICAL This  option  causes  the  fts  routines  to return FTSENT
227                    structures for symbolic links themselves  instead  of  the
228                    target files they point to.  If this option is set, FTSENT
229                    structures for all symbolic links  in  the  hierarchy  are
230                    returned   to  the  application.   Either  FTS_LOGICAL  or
231                    FTS_PHYSICAL must be provided to the fts_open() function.
232
233       FTS_SEEDOT   By default, unless they are specified as path arguments to
234                    fts_open(),  any  files named "."  or ".."  encountered in
235                    the file hierarchy are ignored.  This  option  causes  the
236                    fts routines to return FTSENT structures for them.
237
238       FTS_XDEV     This  option prevents fts from descending into directories
239                    that have a different device number  than  the  file  from
240                    which the descent began.
241
242       The  argument  compar()  specifies a user-defined function which may be
243       used to order the traversal of the hierarchy.  It takes two pointers to
244       pointers to FTSENT structures as arguments and should return a negative
245       value, zero, or a positive value to indicate if the file referenced  by
246       its  first  argument  comes  before,  in  any order with respect to, or
247       after, the file referenced by its second  argument.   The  fts_accpath,
248       fts_path  and  fts_pathlen fields of the FTSENT structures may never be
249       used in this comparison.  If the fts_info field is  set  to  FTS_NS  or
250       FTS_NSOK, the fts_statp field may not either.  If the compar() argument
251       is NULL, the directory traversal  order  is  in  the  order  listed  in
252       path_argv  for the root paths, and in the order listed in the directory
253       for everything else.
254
255   fts_read()
256       The fts_read() function  returns  a  pointer  to  an  FTSENT  structure
257       describing a file in the hierarchy.  Directories (that are readable and
258       do not cause cycles) are visited at least twice, once in pre-order  and
259       once  in post-order.  All other files are visited at least once.  (Hard
260       links between directories that do not cause cycles or symbolic links to
261       symbolic  links may cause files to be visited more than once, or direc‐
262       tories more than twice.)
263
264       If all the members of the  hierarchy  have  been  returned,  fts_read()
265       returns  NULL  and  sets the external variable errno to 0.  If an error
266       unrelated to a file in the hierarchy occurs,  fts_read()  returns  NULL
267       and  sets  errno appropriately.  If an error related to a returned file
268       occurs, a pointer to an FTSENT structure is returned, and errno may  or
269       may not have been set (see fts_info).
270
271       The FTSENT structures returned by fts_read() may be overwritten after a
272       call to fts_close() on the same file hierarchy stream, or, after a call
273       to fts_read() on the same file hierarchy stream unless they represent a
274       file of type directory, in which case  they  will  not  be  overwritten
275       until  after  a  call to fts_read() after the FTSENT structure has been
276       returned by the function fts_read() in post-order.
277
278   fts_children()
279       The fts_children() function returns a pointer to  an  FTSENT  structure
280       describing  the  first  entry  in  a NULL-terminated linked list of the
281       files in  the  directory  represented  by  the  FTSENT  structure  most
282       recently  returned  by  fts_read().   The  list  is  linked through the
283       fts_link field of the FTSENT structure, and is  ordered  by  the  user-
284       specified  comparison  function,  if  any.  Repeated calls to fts_chil‐
285       dren() will recreate this linked list.
286
287       As a special case, if fts_read() has not yet been called for a  hierar‐
288       chy,  fts_children()  will return a pointer to the files in the logical
289       directory specified to fts_open(), that is, the arguments specified  to
290       fts_open().   Otherwise, if the FTSENT structure most recently returned
291       by fts_read() is not a directory being visited  in  pre-order,  or  the
292       directory  does  not contain any files, fts_children() returns NULL and
293       sets errno to zero.  If an error occurs,  fts_children()  returns  NULL
294       and sets errno appropriately.
295
296       The  FTSENT  structures  returned  by fts_children() may be overwritten
297       after a call to fts_children(), fts_close() or fts_read() on  the  same
298       file hierarchy stream.
299
300       Option may be set to the following value:
301
302       FTS_NAMEONLY Only  the  names of the files are needed.  The contents of
303                    all the fields in the returned linked list  of  structures
304                    are  undefined  with  the  exception  of  the fts_name and
305                    fts_namelen fields.
306
307   fts_set()
308       The function fts_set() allows the user application to determine further
309       processing  for  the file f of the stream ftsp.  The fts_set() function
310       returns 0 on success, and -1 if an error occurs.  Option must be set to
311       one of the following values:
312
313       FTS_AGAIN    Re-visit  the  file; any file type may be re-visited.  The
314                    next call to fts_read() will return the  referenced  file.
315                    The  fts_stat and fts_info fields of the structure will be
316                    reinitialized at that time, but no other fields will  have
317                    been changed.  This option is meaningful only for the most
318                    recently returned file from fts_read().  Normal use is for
319                    post-order directory visits, where it causes the directory
320                    to be re-visited (in both pre and post-order) as  well  as
321                    all of its descendants.
322
323       FTS_FOLLOW   The  referenced file must be a symbolic link.  If the ref‐
324                    erenced  file  is  the  one  most  recently  returned   by
325                    fts_read(),  the  next call to fts_read() returns the file
326                    with the fts_info and fts_statp  fields  reinitialized  to
327                    reflect  the  target  of  the symbolic link instead of the
328                    symbolic link itself.  If the file is one  of  those  most
329                    recently  returned  by  fts_children(),  the  fts_info and
330                    fts_statp  fields  of  the  structure,  when  returned  by
331                    fts_read(),  will  reflect the target of the symbolic link
332                    instead of the symbolic link itself.  In either  case,  if
333                    the  target of the symbolic link does not exist the fields
334                    of the  returned  structure  will  be  unchanged  and  the
335                    fts_info field will be set to FTS_SLNONE.
336
337                    If  the  target  of the link is a directory, the pre-order
338                    return, followed by the return of all of its  descendants,
339                    followed by a post-order return, is done.
340
341       FTS_SKIP     No  descendants of this file are visited.  The file may be
342                    one of those most recently returned  by  either  fts_chil‐
343                    dren() or fts_read().
344
345   fts_close()
346       The  fts_close()  function  closes  a  file  hierarchy  stream ftsp and
347       restores the current directory to the directory from  which  fts_open()
348       was  called  to  open ftsp.  The fts_close() function returns 0 on suc‐
349       cess, and -1 if an error occurs.
350

ERRORS

352       The function fts_open() may fail and set errno for any  of  the  errors
353       specified for open(2) and malloc(3).
354
355       The  function  fts_close() may fail and set errno for any of the errors
356       specified for chdir(2) and close(2).
357
358       The functions fts_read() and fts_children() may fail and set errno  for
359       any  of the errors specified for chdir(2), malloc(3), opendir(3), read‐
360       dir(3) and stat(2).
361
362       In addition, fts_children(), fts_open() and fts_set() may fail and  set
363       errno as follows:
364
365       EINVAL The options were invalid.
366

VERSIONS

368       These functions are available in Linux since glibc2.
369

CONFORMING TO

371       4.4BSD.
372

SEE ALSO

374       find(1), chdir(2), stat(2), ftw(3), qsort(3)
375

COLOPHON

377       This  page  is  part of release 3.22 of the Linux man-pages project.  A
378       description of the project, and information about reporting  bugs,  can
379       be found at http://www.kernel.org/doc/man-pages/.
380
381
382
383Linux                             2007-12-28                            FTS(3)
Impressum