Debian Codegraph @

upstream/fedora-44/man3/fts.3

raw
1 '\" t
2 .\" $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $
3 .\"
4 .\" Copyright (c) 1989, 1991, 1993, 1994
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" SPDX-License-Identifier: BSD-4-Clause-UC
8 .\"
9 .\" @(#)fts.3 8.5 (Berkeley) 4/16/94
10 .\"
11 .\" 2007-12-08, mtk, Converted from mdoc to man macros
12 .\"
13 .TH fts 3 2024-12-13 "Linux man-pages 6.13"
14 .SH NAME
15 fts, fts_open, fts_read, fts_children, fts_set, fts_close \- \
16 traverse a file hierarchy
17 .SH LIBRARY
18 Standard C library
19 .RI ( libc ,\~ \-lc )
20 .SH SYNOPSIS
21 .nf
22 .B #include <sys/types.h>
23 .B #include <sys/stat.h>
24 .B #include <fts.h>
25 .P
26 .BI "FTS *fts_open(char *const *" path_argv ", int " options ,
27 .B " typeof(int (const FTSENT **, const FTSENT **))"
28 .BI " *_Nullable " compar );
29 .P
30 .BI "FTSENT *fts_read(FTS *" ftsp );
31 .P
32 .BI "FTSENT *fts_children(FTS *" ftsp ", int " instr );
33 .P
34 .BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr );
35 .P
36 .BI "int fts_close(FTS *" ftsp );
37 .fi
38 .SH DESCRIPTION
39 The
40 fts functions are provided for traversing
41 file hierarchies.
42 A simple overview is that the
43 .BR fts_open ()
44 function returns a "handle" (of type
45 .IR "FTS\ *" )
46 that refers to a file hierarchy "stream".
47 This handle is then supplied to the other
48 fts functions.
49 The function
50 .BR fts_read ()
51 returns a pointer to a structure describing one of the files in the file
52 hierarchy.
53 The function
54 .BR fts_children ()
55 returns a pointer to a linked list of structures, each of which describes
56 one of the files contained in a directory in the hierarchy.
57 .P
58 In general, directories are visited two distinguishable times; in preorder
59 (before any of their descendants are visited) and in postorder (after all
60 of their descendants have been visited).
61 Files are visited once.
62 It is possible to walk the hierarchy "logically" (visiting the files that
63 symbolic links point to)
64 or physically (visiting the symbolic links themselves),
65 order the walk of the hierarchy or
66 prune and/or revisit portions of the hierarchy.
67 .P
68 Two structures (and associated types) are defined in the include file
69 .IR <fts.h> .
70 The first type is
71 .IR FTS ,
72 the structure that represents the file hierarchy itself.
73 The second type is
74 .IR FTSENT ,
75 the structure that represents a file in the file
76 hierarchy.
77 Normally, an
78 .I FTSENT
79 structure is returned for every file in the file
80 hierarchy.
81 In this manual page, "file" and
82 "FTSENT structure"
83 are generally interchangeable.
84 .P
85 The
86 .I FTSENT
87 structure contains fields describing a file.
88 The structure contains at least the following fields
89 (there are additional fields that
90 should be considered private to the implementation):
91 .P
92 .in +4n
93 .EX
94 typedef struct _ftsent {
95 unsigned short fts_info; /* flags for FTSENT structure */
96 char *fts_accpath; /* access path */
97 char *fts_path; /* root path */
98 short fts_pathlen; /* strlen(fts_path) +
99 strlen(fts_name) */
100 char *fts_name; /* filename */
101 short fts_namelen; /* strlen(fts_name) */
102 short fts_level; /* depth (\-1 to N) */
103 int fts_errno; /* file errno */
104 long fts_number; /* local numeric value */
105 void *fts_pointer; /* local address value */
106 struct _ftsent *fts_parent; /* parent directory */
107 struct _ftsent *fts_link; /* next file structure */
108 struct _ftsent *fts_cycle; /* cycle structure */
109 struct stat *fts_statp; /* [l]stat(2) information */
110 .\" Also:
111 .\" ino_t fts_ino; /* inode (only for directories)*/
112 .\" dev_t fts_dev; /* device (only for directories)*/
113 .\" nlink_t fts_nlink; /* link count (only for directories)*/
114 .\" u_short fts_flags; /* private flags for FTSENT structure */
115 .\" u_short fts_instr; /* fts_set() instructions */
116 } FTSENT;
117 .EE
118 .in
119 .P
120 These fields are defined as follows:
121 .\" .Bl -tag -width "fts_namelen"
122 .TP
123 .I fts_info
124 One of the following values describing the returned
125 .I FTSENT
126 structure and
127 the file it represents.
128 With the exception of directories without errors
129 .RB ( FTS_D ),
130 all of these
131 entries are terminal, that is, they will not be revisited, nor will any
132 of their descendants be visited.
133 .\" .Bl -tag -width FTS_DEFAULT
134 .RS
135 .TP
136 .B FTS_D
137 A directory being visited in preorder.
138 .TP
139 .B FTS_DC
140 A directory that causes a cycle in the tree.
141 (The
142 .I fts_cycle
143 field of the
144 .I FTSENT
145 structure will be filled in as well.)
146 .TP
147 .B FTS_DEFAULT
148 Any
149 .I FTSENT
150 structure that represents a file type not explicitly described
151 by one of the other
152 .I fts_info
153 values.
154 .TP
155 .B FTS_DNR
156 A directory which cannot be read.
157 This is an error return, and the
158 .I fts_errno
159 field will be set to indicate what caused the error.
160 .TP
161 .B FTS_DOT
162 A file named
163 "."
164 or
165 ".."
166 which was not specified as a filename to
167 .BR fts_open ()
168 (see
169 .BR FTS_SEEDOT ).
170 .TP
171 .B FTS_DP
172 A directory being visited in postorder.
173 The contents of the
174 .I FTSENT
175 structure will be unchanged from when
176 it was returned in preorder, that is, with the
177 .I fts_info
178 field set to
179 .BR FTS_D .
180 .TP
181 .B FTS_ERR
182 This is an error return, and the
183 .I fts_errno
184 field will be set to indicate what caused the error.
185 .TP
186 .B FTS_F
187 A regular file.
188 .TP
189 .B FTS_NS
190 A file for which no
191 .RB [ l ]\c
192 .BR stat (2)
193 information was available.
194 The contents of the
195 .I fts_statp
196 field are undefined.
197 This is an error return, and the
198 .I fts_errno
199 field will be set to indicate what caused the error.
200 .TP
201 .B FTS_NSOK
202 A file for which no
203 .RB [ l ]\c
204 .BR stat (2)
205 information was requested.
206 The contents of the
207 .I fts_statp
208 field are undefined.
209 .TP
210 .B FTS_SL
211 A symbolic link.
212 .TP
213 .B FTS_SLNONE
214 A symbolic link with a nonexistent target.
215 The contents of the
216 .I fts_statp
217 field reference the file characteristic information for the symbolic link
218 itself.
219 .\" .El
220 .RE
221 .TP
222 .I fts_accpath
223 A path for accessing the file from the current directory.
224 .TP
225 .I fts_path
226 The path for the file relative to the root of the traversal.
227 This path contains the path specified to
228 .BR fts_open ()
229 as a prefix.
230 .TP
231 .I fts_pathlen
232 The sum of the lengths of the strings referenced by
233 .I fts_path
234 and
235 .IR fts_name .
236 .TP
237 .I fts_name
238 The name of the file.
239 .TP
240 .I fts_namelen
241 The length of the string referenced by
242 .IR fts_name .
243 .TP
244 .I fts_level
245 The depth of the traversal, numbered from \-1 to N, where this file
246 was found.
247 The
248 .I FTSENT
249 structure representing the parent of the starting point (or root)
250 of the traversal is numbered \-1, and the
251 .I FTSENT
252 structure for the root
253 itself is numbered 0.
254 .TP
255 .I fts_errno
256 If
257 .BR fts_children ()
258 or
259 .BR fts_read ()
260 returns an
261 .I FTSENT
262 structure whose
263 .I fts_info
264 field is set to
265 .BR FTS_DNR ,
266 .BR FTS_ERR ,
267 or
268 .BR FTS_NS ,
269 the
270 .I fts_errno
271 field contains the error number (i.e., the
272 .I errno
273 value)
274 specifying the error.
275 Otherwise, the contents of the
276 .I fts_errno
277 field are undefined.
278 .TP
279 .I fts_number
280 This field is provided for the use of the application program and is
281 not modified by the
282 fts functions.
283 It is initialized to 0.
284 .TP
285 .I fts_pointer
286 This field is provided for the use of the application program and is
287 not modified by the
288 fts functions.
289 It is initialized to
290 NULL.
291 .TP
292 .I fts_parent
293 A pointer to the
294 .I FTSENT
295 structure referencing the file in the hierarchy
296 immediately above the current file, that is, the directory of which this
297 file is a member.
298 A parent structure for the initial entry point is provided as well,
299 however, only the
300 .IR fts_level ,
301 .IR fts_number ,
302 and
303 .I fts_pointer
304 fields are guaranteed to be initialized.
305 .TP
306 .I fts_link
307 Upon return from the
308 .BR fts_children ()
309 function, the
310 .I fts_link
311 field points to the next structure in the NULL-terminated linked list of
312 directory members.
313 Otherwise, the contents of the
314 .I fts_link
315 field are undefined.
316 .TP
317 .I fts_cycle
318 If a directory causes a cycle in the hierarchy (see
319 .BR FTS_DC ),
320 either because
321 of a hard link between two directories, or a symbolic link pointing to a
322 directory, the
323 .I fts_cycle
324 field of the structure will point to the
325 .I FTSENT
326 structure in the hierarchy that references the same file as the current
327 .I FTSENT
328 structure.
329 Otherwise, the contents of the
330 .I fts_cycle
331 field are undefined.
332 .TP
333 .I fts_statp
334 A pointer to
335 .RB [ l ]\c
336 .BR stat (2)
337 information for the file.
338 .\" .El
339 .P
340 A single buffer is used for all of the paths of all of the files in the
341 file hierarchy.
342 Therefore, the
343 .I fts_path
344 and
345 .I fts_accpath
346 fields are guaranteed to be
347 null-terminated
348 .I only
349 for the file most recently returned by
350 .BR fts_read ().
351 To use these fields to reference any files represented by other
352 .I FTSENT
353 structures will require that the path buffer be modified using the
354 information contained in that
355 .I FTSENT
356 structure's
357 .I fts_pathlen
358 field.
359 Any such modifications should be undone before further calls to
360 .BR fts_read ()
361 are attempted.
362 The
363 .I fts_name
364 field is always
365 null-terminated.
366 .SS fts_open()
367 The
368 .BR fts_open ()
369 function takes a pointer to an array of character pointers naming one
370 or more paths which make up a logical file hierarchy to be traversed.
371 The array must be terminated by a
372 null pointer.
373 .P
374 There are
375 a number of options, at least one of which (either
376 .B FTS_LOGICAL
377 or
378 .BR FTS_PHYSICAL )
379 must be specified.
380 The options are selected by ORing
381 the following values:
382 .\" .Bl -tag -width "FTS_PHYSICAL"
383 .TP
384 .B FTS_LOGICAL
385 This option causes the
386 fts routines to return
387 .I FTSENT
388 structures for the targets of symbolic links
389 instead of the symbolic links themselves.
390 If this option is set, the only symbolic links for which
391 .I FTSENT
392 structures
393 are returned to the application are those referencing nonexistent files:
394 the
395 .I fts_statp
396 field is obtained via
397 .BR stat (2)
398 with a fallback to
399 .BR lstat (2).
400 .TP
401 .B FTS_PHYSICAL
402 This option causes the
403 fts routines to return
404 .I FTSENT
405 structures for symbolic links themselves instead
406 of the target files they point to.
407 If this option is set,
408 .I FTSENT
409 structures for all symbolic links in the
410 hierarchy are returned to the application:
411 the
412 .I fts_statp
413 field is obtained via
414 .BR lstat (2).
415 .TP
416 .B FTS_COMFOLLOW
417 This option causes any symbolic link specified as a root path to be
418 followed immediately, as if via
419 .BR FTS_LOGICAL ,
420 regardless of the primary mode.
421 .TP
422 .B FTS_NOCHDIR
423 As a performance optimization, the
424 fts functions change directories as they walk the file hierarchy.
425 This has the side-effect that an application cannot rely on being
426 in any particular directory during the traversal.
427 This
428 option turns off this optimization, and the
429 fts functions will not change the current directory.
430 Note that applications should not themselves change their current directory
431 and try to access files unless
432 .B FTS_NOCHDIR
433 is specified and absolute
434 pathnames were provided as arguments to
435 .BR fts_open ().
436 .TP
437 .B FTS_NOSTAT
438 By default, returned
439 .I FTSENT
440 structures reference file characteristic information (the
441 .I fts_statp
442 field) for each file visited.
443 This option relaxes that requirement as a performance optimization,
444 allowing the
445 fts functions to set the
446 .I fts_info
447 field to
448 .B FTS_NSOK
449 and leave the contents of the
450 .I fts_statp
451 field undefined.
452 .TP
453 .B FTS_SEEDOT
454 By default, unless they are specified as path arguments to
455 .BR fts_open (),
456 any files named
457 "."
458 or
459 ".."
460 encountered in the file hierarchy are ignored.
461 This option causes the
462 fts routines to return
463 .I FTSENT
464 structures for them.
465 .TP
466 .B FTS_XDEV
467 This option prevents
468 fts from descending into directories that have a different device number
469 than the file from which the descent began.
470 .\" .El
471 .P
472 The argument
473 .BR compar ()
474 specifies a user-defined function which may be used to order the traversal
475 of the hierarchy.
476 It
477 takes two pointers to pointers to
478 .I FTSENT
479 structures as arguments and
480 should return a negative value, zero, or a positive value to indicate
481 if the file referenced by its first argument comes before, in any order
482 with respect to, or after, the file referenced by its second argument.
483 The
484 .IR fts_accpath ,
485 .IR fts_path ,
486 and
487 .I fts_pathlen
488 fields of the
489 .I FTSENT
490 structures may
491 .I never
492 be used in this comparison.
493 If the
494 .I fts_info
495 field is set to
496 .B FTS_NS
497 or
498 .BR FTS_NSOK ,
499 the
500 .I fts_statp
501 field may not either.
502 If the
503 .BR compar ()
504 argument is
505 NULL,
506 the directory traversal order is in the order listed in
507 .I path_argv
508 for the root paths, and in the order listed in the directory for
509 everything else.
510 .SS fts_read()
511 The
512 .BR fts_read ()
513 function returns a pointer to an
514 .I FTSENT
515 structure describing a file in
516 the hierarchy.
517 Directories (that are readable and do not cause cycles) are visited at
518 least twice, once in preorder and once in postorder.
519 All other files are visited at least once.
520 (Hard links between directories that do not cause cycles or symbolic
521 links to symbolic links may cause files to be visited more than once,
522 or directories more than twice.)
523 .P
524 If all the members of the hierarchy have been returned,
525 .BR fts_read ()
526 returns NULL and sets
527 .I errno
528 to 0.
529 If an error unrelated to a file in the hierarchy occurs,
530 .BR fts_read ()
531 returns
532 NULL
533 and sets
534 .I errno
535 to indicate the error.
536 If an error related to a returned file occurs, a pointer to an
537 .I FTSENT
538 structure is returned, and
539 .I errno
540 may or may not have been set (see
541 .IR fts_info ).
542 .P
543 The
544 .I FTSENT
545 structures returned by
546 .BR fts_read ()
547 may be overwritten after a call to
548 .BR fts_close ()
549 on the same file hierarchy stream, or, after a call to
550 .BR fts_read ()
551 on the same file hierarchy stream unless they represent a file of type
552 directory, in which case they will not be overwritten until after a call to
553 .BR fts_read ()
554 after the
555 .I FTSENT
556 structure has been returned by the function
557 .BR fts_read ()
558 in postorder.
559 .SS fts_children()
560 The
561 .BR fts_children ()
562 function returns a pointer to an
563 .I FTSENT
564 structure describing the first entry in a NULL-terminated linked list of
565 the files in the directory represented by the
566 .I FTSENT
567 structure most recently returned by
568 .BR fts_read ().
569 The list is linked through the
570 .I fts_link
571 field of the
572 .I FTSENT
573 structure, and is ordered by the user-specified comparison function, if any.
574 Repeated calls to
575 .BR fts_children ()
576 will re-create this linked list.
577 .P
578 As a special case, if
579 .BR fts_read ()
580 has not yet been called for a hierarchy,
581 .BR fts_children ()
582 will return a pointer to the files in the logical directory specified to
583 .BR fts_open (),
584 that is, the arguments specified to
585 .BR fts_open ().
586 Otherwise, if the
587 .I FTSENT
588 structure most recently returned by
589 .BR fts_read ()
590 is not a directory being visited in preorder,
591 or the directory does not contain any files,
592 .BR fts_children ()
593 returns
594 NULL
595 and sets
596 .I errno
597 to zero.
598 If an error occurs,
599 .BR fts_children ()
600 returns
601 NULL
602 and sets
603 .I errno
604 to indicate the error.
605 .P
606 The
607 .I FTSENT
608 structures returned by
609 .BR fts_children ()
610 may be overwritten after a call to
611 .BR fts_children (),
612 .BR fts_close (),
613 or
614 .BR fts_read ()
615 on the same file hierarchy stream.
616 .P
617 The
618 .I instr
619 argument is either zero or the following value:
620 .\" .Bl -tag -width FTS_NAMEONLY
621 .TP
622 .B FTS_NAMEONLY
623 Only the names of the files are needed.
624 The contents of all the fields in the returned linked list of structures
625 are undefined with the exception of the
626 .I fts_name
627 and
628 .I fts_namelen
629 fields.
630 .\" .El
631 .SS fts_set()
632 The function
633 .BR fts_set ()
634 allows the user application to determine further processing for the
635 file
636 .I f
637 of the stream
638 .IR ftsp .
639 The
640 .BR fts_set ()
641 function
642 returns 0 on success, and \-1 if an error occurs.
643 .P
644 The
645 .I instr
646 argument is either 0 (meaning "do nothing") or one of the following values:
647 .\" .Bl -tag -width FTS_PHYSICAL
648 .TP
649 .B FTS_AGAIN
650 Revisit the file; any file type may be revisited.
651 The next call to
652 .BR fts_read ()
653 will return the referenced file.
654 The
655 .I fts_stat
656 and
657 .I fts_info
658 fields of the structure will be reinitialized at that time,
659 but no other fields will have been changed.
660 This option is meaningful only for the most recently returned
661 file from
662 .BR fts_read ().
663 Normal use is for postorder directory visits, where it causes the
664 directory to be revisited (in both preorder and postorder) as well as all
665 of its descendants.
666 .TP
667 .B FTS_FOLLOW
668 The referenced file must be a symbolic link.
669 If the referenced file is the one most recently returned by
670 .BR fts_read (),
671 the next call to
672 .BR fts_read ()
673 returns the file with the
674 .I fts_info
675 and
676 .I fts_statp
677 fields reinitialized to reflect the target of the symbolic link instead
678 of the symbolic link itself.
679 If the file is one of those most recently returned by
680 .BR fts_children (),
681 the
682 .I fts_info
683 and
684 .I fts_statp
685 fields of the structure, when returned by
686 .BR fts_read (),
687 will reflect the target of the symbolic link instead of the symbolic link
688 itself.
689 In either case, if the target of the symbolic link does not exist, the
690 fields of the returned structure will be unchanged and the
691 .I fts_info
692 field will be set to
693 .BR FTS_SLNONE .
694 .IP
695 If the target of the link is a directory, the preorder return, followed
696 by the return of all of its descendants, followed by a postorder return,
697 is done.
698 .TP
699 .B FTS_SKIP
700 No descendants of this file are visited.
701 The file may be one of those most recently returned by either
702 .BR fts_children ()
703 or
704 .BR fts_read ().
705 .\" .El
706 .SS fts_close()
707 The
708 .BR fts_close ()
709 function closes the file hierarchy stream referred to by
710 .I ftsp
711 and restores the current directory to the directory from which
712 .BR fts_open ()
713 was called to open
714 .IR ftsp .
715 The
716 .BR fts_close ()
717 function
718 returns 0 on success, and \-1 if an error occurs.
719 .SH ERRORS
720 The function
721 .BR fts_open ()
722 may fail and set
723 .I errno
724 for any of the errors specified for
725 .BR open (2)
726 and
727 .BR malloc (3).
728 .P
729 In addition,
730 .BR fts_open ()
731 may fail and set
732 .I errno
733 as follows:
734 .TP
735 .B ENOENT
736 Any element of
737 .I path_argv
738 was an empty string.
739 .P
740 The function
741 .BR fts_close ()
742 may fail and set
743 .I errno
744 for any of the errors specified for
745 .BR chdir (2)
746 and
747 .BR close (2).
748 .P
749 The functions
750 .BR fts_read ()
751 and
752 .BR fts_children ()
753 may fail and set
754 .I errno
755 for any of the errors specified for
756 .BR chdir (2),
757 .BR malloc (3),
758 .BR opendir (3),
759 .BR readdir (3),
760 and
761 .RB [ l ]\c
762 .BR stat (2).
763 .P
764 In addition,
765 .BR fts_children (),
766 .BR fts_open (),
767 and
768 .BR fts_set ()
769 may fail and set
770 .I errno
771 as follows:
772 .TP
773 .B EINVAL
774 .I options
775 or
776 .I instr
777 was invalid.
778 .SH ATTRIBUTES
779 For an explanation of the terms used in this section, see
780 .BR attributes (7).
781 .TS
782 allbox;
783 lbx lb lb
784 l l l.
785 Interface Attribute Value
786 T{
787 .na
788 .nh
789 .BR fts_open (),
790 .BR fts_set (),
791 .BR fts_close ()
792 T} Thread safety MT-Safe
793 T{
794 .na
795 .nh
796 .BR fts_read (),
797 .BR fts_children ()
798 T} Thread safety MT-Unsafe
799 .TE
800 .SH STANDARDS
801 None.
802 .SH HISTORY
803 glibc 2.
804 4.4BSD.
805 .SH BUGS
806 Before glibc 2.23,
807 .\" Fixed by commit 8b7b7f75d91f7bac323dd6a370aeb3e9c5c4a7d5
808 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838
809 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460
810 all of the APIs described in this man page are not safe when compiling
811 a program using the LFS APIs (e.g., when compiling with
812 .IR \-D_FILE_OFFSET_BITS=64 ).
813 .\"
814 .\" The following statement is years old, and seems no closer to
815 .\" being true -- mtk
816 .\" The
817 .\" .I fts
818 .\" utility is expected to be included in a future
819 .\" POSIX.1
820 .\" revision.
821 .SH SEE ALSO
822 .BR find (1),
823 .BR chdir (2),
824 .BR lstat (2),
825 .BR stat (2),
826 .BR ftw (3),
827 .BR qsort (3)