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

ERRORS

374       The  function  fts_open()  may fail and set errno for any of the errors
375       specified for open(2) and malloc(3).
376
377       The function fts_close() may fail and set errno for any of  the  errors
378       specified for chdir(2) and close(2).
379
380       The  functions fts_read() and fts_children() may fail and set errno for
381       any of the errors specified for chdir(2), malloc(3), opendir(3),  read‐
382       dir(3), and stat(2).
383
384       In addition, fts_children(), fts_open(), and fts_set() may fail and set
385       errno as follows:
386
387       EINVAL options or instr was invalid.
388

VERSIONS

390       These functions are available in Linux since glibc2.
391

ATTRIBUTES

393       For  an  explanation  of  the  terms  used   in   this   section,   see
394       attributes(7).
395
396       ┌───────────────────────────────────┬───────────────┬───────────┐
397Interface                          Attribute     Value     
398       ├───────────────────────────────────┼───────────────┼───────────┤
399fts_open(), fts_set(), fts_close() │ Thread safety │ MT-Safe   │
400       ├───────────────────────────────────┼───────────────┼───────────┤
401fts_read(), fts_children()         │ Thread safety │ MT-Unsafe │
402       └───────────────────────────────────┴───────────────┴───────────┘
403

CONFORMING TO

405       4.4BSD.
406

BUGS

408       In versions of glibc before 2.23, all of the APIs described in this man
409       page are not safe when compiling a program using the  LFS  APIs  (e.g.,
410       when compiling with -D_FILE_OFFSET_BITS=64).
411

SEE ALSO

413       find(1), chdir(2), stat(2), ftw(3), qsort(3)
414

COLOPHON

416       This  page  is  part of release 5.07 of the Linux man-pages project.  A
417       description of the project, information about reporting bugs,  and  the
418       latest     version     of     this    page,    can    be    found    at
419       https://www.kernel.org/doc/man-pages/.
420
421
422
423Linux                             2020-04-11                            FTS(3)
Impressum