1 .\" Copyright (c) 1989, 1991, 1993, 1994
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)fts.3 8.5 (Berkeley) 4/16/94
40 .Nd traverse a file hierarchy
48 .Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT * const *, const FTSENT * const *)"
50 .Fn fts_read "FTS *ftsp"
52 .Fn fts_children "FTS *ftsp" "int options"
54 .Fn fts_set "FTS *ftsp" "FTSENT *f" "int options"
56 .Fn fts_set_clientptr "FTS *ftsp" "void *clientdata"
58 .Fn fts_get_clientptr "FTS *ftsp"
60 .Fn fts_get_stream "FTSENT *f"
62 .Fn fts_close "FTS *ftsp"
66 functions are provided for traversing
69 A simple overview is that the
73 on a file hierarchy, which is then supplied to
79 returns a pointer to a structure describing one of the files in the file
83 returns a pointer to a linked list of structures, each of which describes
84 one of the files contained in a directory in the hierarchy.
85 In general, directories are visited two distinguishable times; in pre-order
86 (before any of their descendants are visited) and in post-order (after all
87 of their descendants have been visited).
88 Files are visited once.
89 It is possible to walk the hierarchy
91 (ignoring symbolic links)
92 or physically (visiting symbolic links), order the walk of the hierarchy or
93 prune and/or re-visit portions of the hierarchy.
95 Two structures are defined (and typedef'd) in the include file
99 the structure that represents the file hierarchy itself.
102 the structure that represents a file in the file
106 structure is returned for every file in the file
111 .Dq Vt FTSENT No structure
117 structure contains space for a single pointer, which may be used to
118 store application data or per-hierarchy state.
120 .Fn fts_set_clientptr
122 .Fn fts_get_clientptr
123 functions may be used to set and retrieve this pointer.
124 This is likely to be useful only when accessed from the sort
125 comparison function, which can determine the original
127 stream of its arguments using the
132 functions are also available as macros of the same name.
136 structure contains at least the following fields, which are
137 described in greater detail below:
139 typedef struct _ftsent {
140 u_short fts_info; /* flags for FTSENT structure */
141 char *fts_accpath; /* access path */
142 char *fts_path; /* root path */
143 u_short fts_pathlen; /* strlen(fts_path) */
144 char *fts_name; /* file name */
145 u_short fts_namelen; /* strlen(fts_name) */
146 short fts_level; /* depth (\-1 to N) */
147 int fts_errno; /* file errno */
148 long fts_number; /* local numeric value */
149 void *fts_pointer; /* local address value */
150 int64_t fts_bignum; /* local 64-bit numeric value */
151 struct ftsent *fts_parent; /* parent directory */
152 struct ftsent *fts_link; /* next file structure */
153 struct ftsent *fts_cycle; /* cycle structure */
154 struct stat *fts_statp; /* stat(2) information */
158 These fields are defined as follows:
159 .Bl -tag -width "fts_namelen"
161 One of the following values describing the returned
164 the file it represents.
165 With the exception of directories without errors
168 entries are terminal, that is, they will not be revisited, nor will any
169 of their descendants be visited.
170 .Bl -tag -width FTS_DEFAULT
172 A directory being visited in pre-order.
174 A directory that causes a cycle in the tree.
179 structure will be filled in as well.)
183 structure that represents a file type not explicitly described
188 A directory which cannot be read.
189 This is an error return, and the
191 field will be set to indicate what caused the error.
197 which was not specified as a file name to
202 A directory being visited in post-order.
205 structure will be unchanged from when
206 it was returned in pre-order, i.e., with the
211 This is an error return, and the
213 field will be set to indicate what caused the error.
219 information was available.
223 This is an error return, and the
225 field will be set to indicate what caused the error.
229 information was requested.
236 A symbolic link with a non-existent target.
239 field reference the file characteristic information for the symbolic link
243 A path for accessing the file from the current directory.
245 The path for the file relative to the root of the traversal.
246 This path contains the path specified to
250 The length of the string referenced by
253 The name of the file.
255 The length of the string referenced by
258 The depth of the traversal, numbered from \-1 to N, where this file
262 structure representing the parent of the starting point (or root)
263 of the traversal is numbered
264 .Dv FTS_ROOTPARENTLEVEL
267 structure for the root
287 field contains the value of the external variable
289 specifying the cause of the error.
290 Otherwise, the contents of the
294 This field is provided for the use of the application program and is
298 It is initialized to 0.
299 Note that this field is overlaid by
302 This field is provided for the use of the application program and is
308 Note that this field is overlaid by
311 This field is provided for the use of the application program and is
315 It is initialized to 0.
316 Note that this field overlays
323 structure referencing the file in the hierarchy
324 immediately above the current file, i.e., the directory of which this
326 A parent structure for the initial entry point is provided as well,
333 fields are guaranteed to be initialized.
339 field points to the next structure in the NULL-terminated linked list of
341 Otherwise, the contents of the
345 If a directory causes a cycle in the hierarchy (see
348 of a hard link between two directories, or a symbolic link pointing to a
351 field of the structure will point to the
353 structure in the hierarchy that references the same file as the current
356 Otherwise, the contents of the
362 information for the file.
365 A single buffer is used for all of the paths of all of the files in the
371 fields are guaranteed to be
372 .Dv NUL Ns -terminated
374 for the file most recently returned by
376 To use these fields to reference any files represented by other
378 structures will require that the path buffer be modified using the
379 information contained in that
384 Any such modifications should be undone before further calls to
390 .Dv NUL Ns -terminated .
394 is mutually exclusive with the use of
401 function takes a pointer to an array of character pointers naming one
402 or more paths which make up a logical file hierarchy to be traversed.
403 The array must be terminated by a
408 a number of options, at least one of which (either
413 The options are selected by
415 the following values:
416 .Bl -tag -width "FTS_PHYSICAL"
418 This option causes any symbolic link specified as a root path to be
419 followed immediately whether or not
423 This option causes the
427 structures for the targets of symbolic links
428 instead of the symbolic links themselves.
429 If this option is set, the only symbolic links for which
432 are returned to the application are those referencing non-existent files.
442 As a performance optimization, the
444 functions change directories as they walk the file hierarchy.
445 This has the side-effect that an application cannot rely on being
446 in any particular directory during the traversal.
449 option turns off this optimization, and the
451 functions will not change the current directory.
452 Note that applications should not themselves change their current directory
453 and try to access files unless
455 is specified and absolute
456 pathnames were provided as arguments to
461 structures reference file characteristic information (the
463 field) for each file visited.
464 This option relaxes that requirement as a performance optimization,
471 and leave the contents of the
475 This option causes the
479 structures for symbolic links themselves instead
480 of the target files they point to.
481 If this option is set,
483 structures for all symbolic links in the
484 hierarchy are returned to the application.
494 By default, unless they are specified as path arguments to
500 encountered in the file hierarchy are ignored.
501 This option causes the
509 from descending into directories that have a different device number
510 than the file from which the descent began.
515 specifies a user-defined function which may be used to order the traversal
518 takes two pointers to pointers to
520 structures as arguments and
521 should return a negative value, zero, or a positive value to indicate
522 if the file referenced by its first argument comes before, in any order
523 with respect to, or after, the file referenced by its second argument.
533 be used in this comparison.
542 field may not either.
547 the directory traversal order is in the order listed in
549 for the root paths, and in the order listed in the directory for
554 function returns a pointer to an
556 structure describing a file in
558 Directories (that are readable and do not cause cycles) are visited at
559 least twice, once in pre-order and once in post-order.
560 All other files are visited at least once.
561 (Hard links between directories that do not cause cycles or symbolic
562 links to symbolic links may cause files to be visited more than once,
563 or directories more than twice.)
565 If all the members of the hierarchy have been returned,
569 and sets the external variable
572 If an error unrelated to a file in the hierarchy occurs,
579 If an error related to a returned file occurs, a pointer to an
581 structure is returned, and
583 may or may not have been set (see
588 structures returned by
590 may be overwritten after a call to
592 on the same file hierarchy stream, or, after a call to
594 on the same file hierarchy stream unless they represent a file of type
595 directory, in which case they will not be overwritten until after a call to
599 structure has been returned by the function
605 function returns a pointer to an
607 structure describing the first entry in a NULL-terminated linked list of
608 the files in the directory represented by the
610 structure most recently returned by
612 The list is linked through the
616 structure, and is ordered by the user-specified comparison function, if any.
619 will recreate this linked list.
621 As a special case, if
623 has not yet been called for a hierarchy,
625 will return a pointer to the files in the logical directory specified to
627 i.e., the arguments specified to
631 structure most recently returned by
633 is not a directory being visited in pre-order,
634 or the directory does not contain any files,
651 structures returned by
653 may be overwritten after a call to
658 on the same file hierarchy stream.
661 may be set to the following value:
662 .Bl -tag -width FTS_NAMEONLY
664 Only the names of the files are needed.
665 The contents of all the fields in the returned linked list of structures
666 are undefined with the exception of the
675 allows the user application to determine further processing for the
683 returns 0 on success, and \-1 if an error occurs.
685 must be set to one of the following values:
686 .Bl -tag -width FTS_PHYSICAL
688 Re-visit the file; any file type may be re-visited.
691 will return the referenced file.
696 fields of the structure will be reinitialized at that time,
697 but no other fields will have been changed.
698 This option is meaningful only for the most recently returned
701 Normal use is for post-order directory visits, where it causes the
702 directory to be re-visited (in both pre and post-order) as well as all
705 The referenced file must be a symbolic link.
706 If the referenced file is the one most recently returned by
710 returns the file with the
714 fields reinitialized to reflect the target of the symbolic link instead
715 of the symbolic link itself.
716 If the file is one of those most recently returned by
722 fields of the structure, when returned by
724 will reflect the target of the symbolic link instead of the symbolic link
726 In either case, if the target of the symbolic link does not exist the
727 fields of the returned structure will be unchanged and the
732 If the target of the link is a directory, the pre-order return, followed
733 by the return of all of its descendants, followed by a post-order return,
736 No descendants of this file are visited.
737 The file may be one of those most recently returned by either
745 function closes a file hierarchy stream
747 and restores the current directory to the directory from which
754 returns 0 on success, and \-1 if an error occurs.
760 for any of the errors specified for the library functions
769 for any of the errors specified for the library functions
780 for any of the errors specified for the library functions
798 The options were invalid.
809 interface was first introduced in
812 .Fn fts_get_clientptr ,
815 .Fn fts_set_clientptr
816 functions were introduced in
818 principally to provide for alternative interfaces to the
820 functionality using different data structures.