1 .\" $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $
3 .\" Copyright (c) 1989, 1991, 1993, 1994
4 .\" The Regents of the University of California. All rights reserved.
6 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .\" @(#)fts.3 8.5 (Berkeley) 4/16/94
38 .\" 2007-12-08, mtk, Converted from mdoc to man macros
40 .TH FTS 3 2021-03-22 "Linux" "Linux Programmer's Manual"
42 fts, fts_open, fts_read, fts_children, fts_set, fts_close \- \
43 traverse a file hierarchy
46 .B #include <sys/types.h>
47 .B #include <sys/stat.h>
50 .BI "FTS *fts_open(char * const *" path_argv ", int " options ,
51 .BI " int (*" compar ")(const FTSENT **, const FTSENT **));"
53 .BI "FTSENT *fts_read(FTS *" ftsp );
55 .BI "FTSENT *fts_children(FTS *" ftsp ", int " instr );
57 .BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr );
59 .BI "int fts_close(FTS *" ftsp );
63 fts functions are provided for traversing
65 A simple overview is that the
67 function returns a "handle" (of type
69 that refers to a file hierarchy "stream".
70 This handle is then supplied to the other
74 returns a pointer to a structure describing one of the files in the file
78 returns a pointer to a linked list of structures, each of which describes
79 one of the files contained in a directory in the hierarchy.
81 In general, directories are visited two distinguishable times; in preorder
82 (before any of their descendants are visited) and in postorder (after all
83 of their descendants have been visited).
84 Files are visited once.
85 It is possible to walk the hierarchy "logically" (visiting the files that
86 symbolic links point to)
87 or physically (visiting the symbolic links themselves),
88 order the walk of the hierarchy or
89 prune and/or revisit portions of the hierarchy.
91 Two structures (and associated types) are defined in the include file
95 the structure that represents the file hierarchy itself.
98 the structure that represents a file in the file
102 structure is returned for every file in the file
104 In this manual page, "file" and
106 are generally interchangeable.
110 structure contains fields describing a file.
111 The structure contains at least the following fields
112 (there are additional fields that
113 should be considered private to the implementation):
117 typedef struct _ftsent {
118 unsigned short fts_info; /* flags for FTSENT structure */
119 char *fts_accpath; /* access path */
120 char *fts_path; /* root path */
121 short fts_pathlen; /* strlen(fts_path) +
123 char *fts_name; /* filename */
124 short fts_namelen; /* strlen(fts_name) */
125 short fts_level; /* depth (\-1 to N) */
126 int fts_errno; /* file errno */
127 long fts_number; /* local numeric value */
128 void *fts_pointer; /* local address value */
129 struct _ftsent *fts_parent; /* parent directory */
130 struct _ftsent *fts_link; /* next file structure */
131 struct _ftsent *fts_cycle; /* cycle structure */
132 struct stat *fts_statp; /* stat(2) information */
134 .\" ino_t fts_ino; /* inode (only for directories)*/
135 .\" dev_t fts_dev; /* device (only for directories)*/
136 .\" nlink_t fts_nlink; /* link count (only for directories)*/
137 .\" u_short fts_flags; /* private flags for FTSENT structure */
138 .\" u_short fts_instr; /* fts_set() instructions */
143 These fields are defined as follows:
144 .\" .Bl -tag -width "fts_namelen"
147 One of the following values describing the returned
150 the file it represents.
151 With the exception of directories without errors
154 entries are terminal, that is, they will not be revisited, nor will any
155 of their descendants be visited.
156 .\" .Bl -tag -width FTS_DEFAULT
160 A directory being visited in preorder.
163 A directory that causes a cycle in the tree.
168 structure will be filled in as well.)
173 structure that represents a file type not explicitly described
179 A directory which cannot be read.
180 This is an error return, and the
182 field will be set to indicate what caused the error.
189 which was not specified as a filename to
195 A directory being visited in postorder.
198 structure will be unchanged from when
199 it was returned in preorder, that is, with the
205 This is an error return, and the
207 field will be set to indicate what caused the error.
215 information was available.
219 This is an error return, and the
221 field will be set to indicate what caused the error.
226 information was requested.
235 A symbolic link with a nonexistent target.
238 field reference the file characteristic information for the symbolic link
244 A path for accessing the file from the current directory.
247 The path for the file relative to the root of the traversal.
248 This path contains the path specified to
253 The sum of the lengths of the strings referenced by
259 The name of the file.
262 The length of the string referenced by
266 The depth of the traversal, numbered from \-1 to N, where this file
270 structure representing the parent of the starting point (or root)
271 of the traversal is numbered \-1, and the
273 structure for the root
274 itself is numbered 0.
292 field contains the error number (i.e., the
295 specifying the cause of the error.
296 Otherwise, the contents of the
301 This field is provided for the use of the application program and is
304 It is initialized to 0.
307 This field is provided for the use of the application program and is
316 structure referencing the file in the hierarchy
317 immediately above the current file, that is, the directory of which this
319 A parent structure for the initial entry point is provided as well,
325 fields are guaranteed to be initialized.
332 field points to the next structure in the NULL-terminated linked list of
334 Otherwise, the contents of the
339 If a directory causes a cycle in the hierarchy (see
342 of a hard link between two directories, or a symbolic link pointing to a
345 field of the structure will point to the
347 structure in the hierarchy that references the same file as the current
350 Otherwise, the contents of the
357 information for the file.
360 A single buffer is used for all of the paths of all of the files in the
366 fields are guaranteed to be
369 for the file most recently returned by
371 To use these fields to reference any files represented by other
373 structures will require that the path buffer be modified using the
374 information contained in that
379 Any such modifications should be undone before further calls to
389 function takes a pointer to an array of character pointers naming one
390 or more paths which make up a logical file hierarchy to be traversed.
391 The array must be terminated by a
395 a number of options, at least one of which (either
400 The options are selected by ORing
401 the following values:
402 .\" .Bl -tag -width "FTS_PHYSICAL"
405 This option causes any symbolic link specified as a root path to be
406 followed immediately whether or not
411 This option causes the
412 fts routines to return
414 structures for the targets of symbolic links
415 instead of the symbolic links themselves.
416 If this option is set, the only symbolic links for which
419 are returned to the application are those referencing nonexistent files.
430 As a performance optimization, the
431 fts functions change directories as they walk the file hierarchy.
432 This has the side-effect that an application cannot rely on being
433 in any particular directory during the traversal.
436 option turns off this optimization, and the
437 fts functions will not change the current directory.
438 Note that applications should not themselves change their current directory
439 and try to access files unless
441 is specified and absolute
442 pathnames were provided as arguments to
448 structures reference file characteristic information (the
450 field) for each file visited.
451 This option relaxes that requirement as a performance optimization,
453 fts functions to set the
457 and leave the contents of the
462 This option causes the
463 fts routines to return
465 structures for symbolic links themselves instead
466 of the target files they point to.
467 If this option is set,
469 structures for all symbolic links in the
470 hierarchy are returned to the application.
481 By default, unless they are specified as path arguments to
487 encountered in the file hierarchy are ignored.
488 This option causes the
489 fts routines to return
495 fts from descending into directories that have a different device number
496 than the file from which the descent began.
501 specifies a user-defined function which may be used to order the traversal
504 takes two pointers to pointers to
506 structures as arguments and
507 should return a negative value, zero, or a positive value to indicate
508 if the file referenced by its first argument comes before, in any order
509 with respect to, or after, the file referenced by its second argument.
519 be used in this comparison.
528 field may not either.
533 the directory traversal order is in the order listed in
535 for the root paths, and in the order listed in the directory for
540 function returns a pointer to an
542 structure describing a file in
544 Directories (that are readable and do not cause cycles) are visited at
545 least twice, once in preorder and once in postorder.
546 All other files are visited at least once.
547 (Hard links between directories that do not cause cycles or symbolic
548 links to symbolic links may cause files to be visited more than once,
549 or directories more than twice.)
551 If all the members of the hierarchy have been returned,
553 returns NULL and sets
556 If an error unrelated to a file in the hierarchy occurs,
562 to indicate the error.
563 If an error related to a returned file occurs, a pointer to an
565 structure is returned, and
567 may or may not have been set (see
572 structures returned by
574 may be overwritten after a call to
576 on the same file hierarchy stream, or, after a call to
578 on the same file hierarchy stream unless they represent a file of type
579 directory, in which case they will not be overwritten until after a call to
583 structure has been returned by the function
589 function returns a pointer to an
591 structure describing the first entry in a NULL-terminated linked list of
592 the files in the directory represented by the
594 structure most recently returned by
596 The list is linked through the
600 structure, and is ordered by the user-specified comparison function, if any.
603 will re-create this linked list.
605 As a special case, if
607 has not yet been called for a hierarchy,
609 will return a pointer to the files in the logical directory specified to
611 that is, the arguments specified to
615 structure most recently returned by
617 is not a directory being visited in preorder,
618 or the directory does not contain any files,
631 to indicate the error.
635 structures returned by
637 may be overwritten after a call to
642 on the same file hierarchy stream.
646 argument is either zero or the following value:
647 .\" .Bl -tag -width FTS_NAMEONLY
650 Only the names of the files are needed.
651 The contents of all the fields in the returned linked list of structures
652 are undefined with the exception of the
661 allows the user application to determine further processing for the
669 returns 0 on success, and \-1 if an error occurs.
673 argument is either 0 (meaning "do nothing") or one of the following values:
674 .\" .Bl -tag -width FTS_PHYSICAL
677 Revisit the file; any file type may be revisited.
680 will return the referenced file.
685 fields of the structure will be reinitialized at that time,
686 but no other fields will have been changed.
687 This option is meaningful only for the most recently returned
690 Normal use is for postorder directory visits, where it causes the
691 directory to be revisited (in both preorder and postorder) as well as all
695 The referenced file must be a symbolic link.
696 If the referenced file is the one most recently returned by
700 returns the file with the
704 fields reinitialized to reflect the target of the symbolic link instead
705 of the symbolic link itself.
706 If the file is one of those most recently returned by
712 fields of the structure, when returned by
714 will reflect the target of the symbolic link instead of the symbolic link
716 In either case, if the target of the symbolic link does not exist, the
717 fields of the returned structure will be unchanged and the
722 If the target of the link is a directory, the preorder return, followed
723 by the return of all of its descendants, followed by a postorder return,
727 No descendants of this file are visited.
728 The file may be one of those most recently returned by either
736 function closes the file hierarchy stream referred to by
738 and restores the current directory to the directory from which
745 returns 0 on success, and \-1 if an error occurs.
751 for any of the errors specified for
760 for any of the errors specified for
771 for any of the errors specified for
794 These functions are available in Linux since glibc2.
796 For an explanation of the terms used in this section, see
804 Interface Attribute Value
809 T} Thread safety MT-Safe
813 T} Thread safety MT-Unsafe
821 In versions of glibc before 2.23,
822 .\" Fixed by commit 8b7b7f75d91f7bac323dd6a370aeb3e9c5c4a7d5
823 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838
824 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460
825 all of the APIs described in this man page are not safe when compiling
826 a program using the LFS APIs (e.g., when compiling with
827 .IR \-D_FILE_OFFSET_BITS=64 ).
829 .\" The following statement is years old, and seems no closer to
830 .\" being true -- mtk
833 .\" utility is expected to be included in a future