| blob | d8968193b54ac98204dcec7d6d58ee8a5507a494 |
1 .\" $NetBSD: fts.3,v 1.31 2013/06/30 19:19:12 wiz Exp $
2 .\"
3 .\" Copyright (c) 1989, 1991, 1993, 1994
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)fts.3 8.5 (Berkeley) 4/16/94
31 .\"
32 .Dd March 30, 2011
33 .Dt FTS 3
34 .Os
35 .Sh NAME
36 .Nm fts ,
37 .Nm fts_open ,
38 .Nm fts_read ,
39 .Nm fts_children ,
40 .Nm fts_set ,
41 .Nm fts_close
42 .Nd traverse a file hierarchy
43 .Sh LIBRARY
44 .Lb libc
45 .Sh SYNOPSIS
46 .In sys/types.h
47 .In sys/stat.h
48 .In fts.h
49 .Ft FTS *
50 .Fo fts_open
51 .Fa "char * const *path_argv"
52 .Fa "int options"
53 .Fa "int (*compar)(const FTSENT **, const FTSENT **)"
54 .Fc
55 .Ft FTSENT *
56 .Fn fts_read "FTS *ftsp"
57 .Ft FTSENT *
58 .Fn fts_children "FTS *ftsp" "int options"
59 .Ft int
60 .Fn fts_set "FTS *ftsp" "FTSENT *f" "int options"
61 .Ft int
62 .Fn fts_close "FTS *ftsp"
63 .Sh DESCRIPTION
64 The
65 .Nm
66 functions are provided for traversing
67 .Ux
68 file hierarchies.
69 A simple overview is that the
70 .Fn fts_open
71 function returns a
72 .Dq handle
73 on a file hierarchy, which is then supplied to
74 the other
75 .Nm
76 functions.
77 The function
78 .Fn fts_read
79 returns a pointer to a structure describing one of the files in the file
80 hierarchy.
81 The function
82 .Fn fts_children
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
90 .Dq logically
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.
94 .Pp
95 Two structures are defined (and typedef'd) in the include file
96 .In fts.h .
97 The first is
98 .Fa FTS ,
99 the structure that represents the file hierarchy itself.
100 The second is
101 .Fa FTSENT ,
102 the structure that represents a file in the file
103 hierarchy.
104 Normally, an
105 .Fa FTSENT
106 structure is returned for every file in the file
107 hierarchy.
108 In this manual page,
109 .Dq file
110 and
111 .Dq Fa FTSENT No structure
112 are generally
113 interchangeable.
114 The
115 .Fa FTSENT
116 structure contains at least the following fields, which are
117 described in greater detail below:
118 .Bd -literal -offset 2n
119 typedef struct _ftsent {
120 u_short fts_info; /* flags for FTSENT structure */
121 char *fts_accpath; /* access path */
122 char *fts_path; /* root path */
123 short fts_pathlen; /* strlen(fts_path) */
124 char *fts_name; /* file name */
125 short fts_namelen; /* strlen(fts_name) */
126 short fts_level; /* depth (\-1 to N) */
127 int fts_errno; /* file errno */
128 long fts_number; /* local numeric value */
129 void *fts_pointer; /* local address value */
130 struct ftsent *fts_parent; /* parent directory */
131 struct ftsent *fts_link; /* next file structure */
132 struct ftsent *fts_cycle; /* cycle structure */
133 struct stat *fts_statp; /* stat(2) information */
134 } FTSENT;
135 .Ed
136 .Pp
137 These fields are defined as follows:
138 .Bl -tag -width "fts_namelen"
139 .It Fa fts_info
140 One of the following flags describing the returned
141 .Fa FTSENT
142 structure and
143 the file it represents.
144 With the exception of directories without errors
145 .Pq Dv FTS_D ,
146 all of these
147 entries are terminal, that is, they will not be revisited, nor will any
148 of their descendants be visited.
149 .Bl -tag -width FTS_DEFAULT
150 .It Dv FTS_D
151 A directory being visited in pre-order.
152 .It Dv FTS_DC
153 A directory that causes a cycle in the tree.
154 (The
155 .Fa fts_cycle
156 field of the
157 .Fa FTSENT
158 structure will be filled in as well).
159 .It Dv FTS_DEFAULT
160 Any
161 .Fa FTSENT
162 structure that represents a file type not explicitly described
163 by one of the other
164 .Fa fts_info
165 values.
166 .It Dv FTS_DNR
167 A directory which cannot be read.
168 This is an error return, and the
169 .Fa fts_errno
170 field will be set to indicate what caused the error.
171 .It Dv FTS_DOT
172 A file named
173 .Ql \&.
174 or
175 .Ql ..
176 which was not specified as a file name to
177 .Fn fts_open
178 (see
179 .Dv FTS_SEEDOT ) .
180 .It Dv FTS_DP
181 A directory being visited in post-order.
182 The contents of the
183 .Fa FTSENT
184 structure will be unchanged from when
185 it was returned in pre-order, i.e., with the
186 .Fa fts_info
187 field set to
188 .Dv FTS_D .
189 .It Dv FTS_ERR
190 This is an error return, and the
191 .Fa fts_errno
192 field will be set to indicate what caused the error.
193 .It Dv FTS_F
194 A regular file.
195 .It Dv FTS_NS
196 A file for which no
197 .Xr stat 2
198 information was available.
199 The contents of the
200 .Fa fts_statp
201 field are undefined.
202 This is an error return, and the
203 .Fa fts_errno
204 field will be set to indicate what caused the error.
205 .It Dv FTS_NSOK
206 A file for which no
207 .Xr stat 2
208 information was requested.
209 The contents of the
210 .Fa fts_statp
211 field are undefined.
212 .It Dv FTS_SL
213 A symbolic link.
214 .It Dv FTS_SLNONE
215 A symbolic link with a non-existent target.
216 The contents of the
217 .Fa fts_statp
218 field reference the file characteristic information for the symbolic link
219 itself.
220 .It Dv FTS_W
221 A whiteout object.
222 .El
223 .It Fa fts_accpath
224 A path for accessing the file from the current directory.
225 .It Fa fts_path
226 The path for the file relative to the root of the traversal.
227 This path contains the path specified to
228 .Fn fts_open
229 as a prefix.
230 .It Fa fts_pathlen
231 The length of the string referenced by
232 .Fa fts_path .
233 .It Fa fts_name
234 The name of the file.
235 .It Fa fts_namelen
236 The length of the string referenced by
237 .Fa fts_name .
238 .It Fa fts_level
239 The depth of the traversal, numbered from \-1 to N, where this file
240 was found.
241 The
242 .Fa FTSENT
243 structure representing the parent of the starting point (or root)
244 of the traversal is numbered \-1, and the
245 .Fa FTSENT
246 structure for the root
247 itself is numbered 0.
248 .It Fa fts_errno
249 Upon return of a
250 .Fa FTSENT
251 structure from the
252 .Fn fts_children
253 or
254 .Fn fts_read
255 functions, with its
256 .Fa fts_info
257 field set to
258 .Dv FTS_DNR ,
259 .Dv FTS_ERR
260 or
261 .Dv FTS_NS ,
262 the
263 .Fa fts_errno
264 field contains the value of the external variable
265 .Va errno
266 specifying the cause of the error.
267 Otherwise, the contents of the
268 .Fa fts_errno
269 field are undefined.
270 .It Fa fts_number
271 This field is provided for the use of the application program and is
272 not modified by the
273 .Nm
274 functions.
275 It is initialized to 0.
276 .It Fa fts_pointer
277 This field is provided for the use of the application program and is
278 not modified by the
279 .Nm
280 functions.
281 It is initialized to
282 .Dv NULL .
283 .It Fa fts_parent
284 A pointer to the
285 .Fa FTSENT
286 structure referencing the file in the hierarchy
287 immediately above the current file, i.e., the directory of which this
288 file is a member.
289 A parent structure for the initial entry point is provided as well,
290 however, only the
291 .Fa fts_level ,
292 .Fa fts_number
293 and
294 .Fa fts_pointer
295 fields are guaranteed to be initialized.
296 .It Fa fts_link
297 Upon return from the
298 .Fn fts_children
299 function, the
300 .Fa fts_link
301 field points to the next structure in the
302 .Dv NULL Ns -terminated
303 linked list of directory members.
304 Otherwise, the contents of the
305 .Fa fts_link
306 field are undefined.
307 .It Fa fts_cycle
308 If a directory causes a cycle in the hierarchy (see
309 .Dv FTS_DC ) ,
310 either because
311 of a hard link between two directories, or a symbolic link pointing to a
312 directory, the
313 .Fa fts_cycle
314 field of the structure will point to the
315 .Fa FTSENT
316 structure in the hierarchy that references the same file as the current
317 .Fa FTSENT
318 structure.
319 Otherwise, the contents of the
320 .Fa fts_cycle
321 field are undefined.
322 .It Fa fts_statp
323 A pointer to
324 .Xr stat 2
325 information for the file.
326 .El
327 .Pp
328 A single buffer is used for all of the paths of all of the files in the
329 file hierarchy.
330 Therefore, the
331 .Fa fts_path
332 and
333 .Fa fts_accpath
334 fields are guaranteed to be
335 .Dv NUL Ns -terminated
336 .Em only
337 for the file most recently returned by
338 .Fn fts_read .
339 To use these fields to reference any files represented by other
340 .Fa FTSENT
341 structures will require that the path buffer be modified using the
342 information contained in that
343 .Fa FTSENT
344 structure's
345 .Fa fts_pathlen
346 field.
347 Any such modifications should be undone before further calls to
348 .Fn fts_read
349 are attempted.
350 The
351 .Fa fts_name
352 field is always
353 .Dv NUL Ns -terminated .
354 .Sh FTS_OPEN
355 The
356 .Fn fts_open
357 function takes a pointer to an array of character pointers naming one
358 or more paths which make up a logical file hierarchy to be traversed.
359 The array must be terminated by a
360 .Dv NULL
361 pointer.
362 .Pp
363 There are
364 a number of options, at least one of which (either
365 .Dv FTS_LOGICAL
366 or
367 .Dv FTS_PHYSICAL )
368 must be specified.
369 The options are selected by
370 .Em or Ns 'ing
371 the following values:
372 .Bl -tag -width "FTS_COMFOLLOW "
373 .It Dv FTS_COMFOLLOW
374 This option causes any symbolic link specified as a root path to be
375 followed immediately whether or not
376 .Dv FTS_LOGICAL
377 is also specified.
378 .It Dv FTS_LOGICAL
379 This option causes the
380 .Nm
381 routines to return
382 .Fa FTSENT
383 structures for the targets of symbolic links
384 instead of the symbolic links themselves.
385 If this option is set, the only symbolic links for which
386 .Fa FTSENT
387 structures
388 are returned to the application are those referencing non-existent files.
389 Either
390 .Dv FTS_LOGICAL
391 or
392 .Dv FTS_PHYSICAL
393 .Em must
394 be provided to the
395 .Fn fts_open
396 function.
397 .It Dv FTS_NOCHDIR
398 As a performance optimization, the
399 .Nm
400 functions change directories as they walk the file hierarchy.
401 This has the side-effect that an application cannot rely on being
402 in any particular directory during the traversal.
403 The
404 .Dv FTS_NOCHDIR
405 option turns off this optimization, and the
406 .Nm
407 functions will not change the current directory.
408 Note that applications should not themselves change their current directory
409 and try to access files unless
410 .Dv FTS_NOCHDIR
411 is specified and absolute
412 pathnames were provided as arguments to
413 .Fn fts_open .
414 .It Dv FTS_NOSTAT
415 By default, returned
416 .Fa FTSENT
417 structures reference file characteristic information (the
418 .Fa statp
419 field) for each file visited.
420 This option relaxes that requirement as a performance optimization,
421 allowing the
422 .Nm
423 functions to set the
424 .Fa fts_info
425 field to
426 .Dv FTS_NSOK
427 and leave the contents of the
428 .Fa statp
429 field undefined.
430 .It Dv FTS_PHYSICAL
431 This option causes the
432 .Nm
433 routines to return
434 .Fa FTSENT
435 structures for symbolic links themselves instead
436 of the target files they point to.
437 If this option is set,
438 .Fa FTSENT
439 structures for all symbolic links in the
440 hierarchy are returned to the application.
441 Either
442 .Dv FTS_LOGICAL
443 or
444 .Dv FTS_PHYSICAL
445 .Em must
446 be provided to the
447 .Fn fts_open
448 function.
449 .It Dv FTS_SEEDOT
450 By default, unless they are specified as path arguments to
451 .Fn fts_open ,
452 any files named
453 .Ql \&.
454 or
455 .Ql ..
456 encountered in the file hierarchy are ignored.
457 This option causes the
458 .Nm
459 routines to return
460 .Fa FTSENT
461 structures for them.
462 .It Dv FTS_WHITEOUT
463 Return whiteout entries, which are normally hidden.
464 .It Dv FTS_XDEV
465 This option prevents
466 .Nm
467 from descending into directories that have a different device number
468 than the file from which the descent began.
469 .El
470 .Pp
471 The argument
472 .Fn compar
473 specifies a user-defined function which may be used to order the traversal
474 of the hierarchy.
475 It
476 takes two pointers to pointers to
477 .Fa FTSENT
478 structures as arguments and
479 should return a negative value, zero, or a positive value to indicate
480 if the file referenced by its first argument comes before, in any order
481 with respect to, or after, the file referenced by its second argument.
482 The
483 .Fa fts_accpath ,
484 .Fa fts_path
485 and
486 .Fa fts_pathlen
487 fields of the
488 .Fa FTSENT
489 structures may
490 .Em never
491 be used in this comparison.
492 If the
493 .Fa fts_info
494 field is set to
495 .Dv FTS_NS
496 or
497 .Dv FTS_NSOK ,
498 the
499 .Fa fts_statp
500 field may not either.
501 If the
502 .Fn compar
503 argument is
504 .Dv NULL ,
505 the directory traversal order is in the order listed in
506 .Fa path_argv
507 for the root paths, and in the order listed in the directory for
508 everything else.
509 .Sh FTS_READ
510 The
511 .Fn fts_read
512 function returns a pointer to an
513 .Fa FTSENT
514 structure describing a file in
515 the hierarchy.
516 Directories (that are readable and do not cause cycles) are visited at
517 least twice, once in pre-order and once in post-order.
518 All other files are visited at least once.
519 (Hard links between directories that do not cause cycles or symbolic
520 links to symbolic links may cause files to be visited more than once,
521 or directories more than twice.)
522 .Pp
523 If all the members of the hierarchy have been returned,
524 .Fn fts_read
525 returns
526 .Dv NULL
527 and sets the external variable
528 .Va errno
529 to 0.
530 If an error unrelated to a file in the hierarchy occurs,
531 .Fn fts_read
532 returns
533 .Dv NULL
534 and sets
535 .Va errno
536 appropriately.
537 If an error related to a returned file occurs, a pointer to an
538 .Fa FTSENT
539 structure is returned, and
540 .Va errno
541 may or may not have been set (see
542 .Fa fts_info ) .
543 .Pp
544 The
545 .Fa FTSENT
546 structures returned by
547 .Fn fts_read
548 may be overwritten after a call to
549 .Fn fts_close
550 on the same file hierarchy stream, or, after a call to
551 .Fn fts_read
552 on the same file hierarchy stream unless they represent a file of type
553 directory, in which case they will not be overwritten until after a call to
554 .Fn fts_read
555 after the
556 .Fa FTSENT
557 structure has been returned by the function
558 .Fn fts_read
559 in post-order.
560 .Sh FTS_CHILDREN
561 The
562 .Fn fts_children
563 function returns a pointer to an
564 .Fa FTSENT
565 structure describing the first entry in a
566 .Dv NULL Ns -terminated
567 linked list of the files in the directory represented by the
568 .Fa FTSENT
569 structure most recently returned by
570 .Fn fts_read .
571 The list is linked through the
572 .Fa fts_link
573 field of the
574 .Fa FTSENT
575 structure, and is ordered by the user-specified comparison function, if any.
576 Repeated calls to
577 .Fn fts_children
578 will recreate this linked list.
579 .Pp
580 As a special case, if
581 .Fn fts_read
582 has not yet been called for a hierarchy,
583 .Fn fts_children
584 will return a pointer to the files in the logical directory specified to
585 .Fn fts_open ,
586 i.e., the arguments specified to
587 .Fn fts_open .
588 Otherwise, if the
589 .Fa FTSENT
590 structure most recently returned by
591 .Fn fts_read
592 is not a directory being visited in pre-order,
593 or the directory does not contain any files,
594 .Fn fts_children
595 returns
596 .Dv NULL
597 and sets
598 .Va errno
599 to zero.
600 If an error occurs,
601 .Fn fts_children
602 returns
603 .Dv NULL
604 and sets
605 .Va errno
606 appropriately.
607 .Pp
608 The
609 .Fa FTSENT
610 structures returned by
611 .Fn fts_children
612 may be overwritten after a call to
613 .Fn fts_children ,
614 .Fn fts_close
615 or
616 .Fn fts_read
617 on the same file hierarchy stream.
618 .Pp
619 .Em Option
620 may be set to the following value:
621 .Bl -tag -width "FTS_COMFOLLOW "
622 .It Dv 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 .Fa fts_name
627 and
628 .Fa fts_namelen
629 fields.
630 .El
631 .Sh FTS_SET
632 The function
633 .Fn fts_set
634 allows the user application to determine further processing for the
635 file
636 .Fa f
637 of the stream
638 .Fa ftsp .
639 The
640 .Fn fts_set
641 function
642 returns 0 on success, and \-1 if an error occurs.
643 .Em Option
644 must be set to one of the following values:
645 .Bl -tag -width "FTS_COMFOLLOW "
646 .It Dv FTS_AGAIN
647 Re-visit the file; any file type may be re-visited.
648 The next call to
649 .Fn fts_read
650 will return the referenced file.
651 The
652 .Fa fts_stat
653 and
654 .Fa fts_info
655 fields of the structure will be reinitialized at that time,
656 but no other fields will have been changed.
657 This option is meaningful only for the most recently returned
658 file from
659 .Fn fts_read .
660 Normal use is for post-order directory visits, where it causes the
661 directory to be re-visited (in both pre and post-order) as well as all
662 of its descendants.
663 .It Dv FTS_FOLLOW
664 The referenced file must be a symbolic link.
665 If the referenced file is the one most recently returned by
666 .Fn fts_read ,
667 the next call to
668 .Fn fts_read
669 returns the file with the
670 .Fa fts_info
671 and
672 .Fa fts_statp
673 fields reinitialized to reflect the target of the symbolic link instead
674 of the symbolic link itself.
675 If the file is one of those most recently returned by
676 .Fn fts_children ,
677 the
678 .Fa fts_info
679 and
680 .Fa fts_statp
681 fields of the structure, when returned by
682 .Fn fts_read ,
683 will reflect the target of the symbolic link instead of the symbolic link
684 itself.
685 In either case, if the target of the symbolic link does not exist the
686 fields of the returned structure will be unchanged and the
687 .Fa fts_info
688 field will be set to
689 .Dv FTS_SLNONE .
690 .Pp
691 If the target of the link is a directory, the pre-order return, followed
692 by the return of all of its descendants, followed by a post-order return,
693 is done.
694 .It Dv FTS_SKIP
695 No descendants of this file are visited.
696 The file may be one of those most recently returned by either
697 .Fn fts_children
698 or
699 .Fn fts_read .
700 .El
701 .Sh FTS_CLOSE
702 The
703 .Fn fts_close
704 function closes a file hierarchy stream
705 .Fa ftsp
706 and restores the current directory to the directory from which
707 .Fn fts_open
708 was called to open
709 .Fa ftsp .
710 The
711 .Fn fts_close
712 function
713 returns 0 on success, and \-1 if an error occurs.
714 .Sh ERRORS
715 The function
716 .Fn fts_open
717 may fail and set
718 .Va errno
719 for any of the errors specified for the library functions
720 .Xr open 2
721 and
722 .Xr malloc 3 .
723 .Pp
724 The function
725 .Fn fts_close
726 may fail and set
727 .Va errno
728 for any of the errors specified for the library functions
729 .Xr chdir 2
730 and
731 .Xr close 2 .
732 .Pp
733 The functions
734 .Fn fts_read
735 and
736 .Fn fts_children
737 may fail and set
738 .Va errno
739 for any of the errors specified for the library functions
740 .Xr chdir 2 ,
741 .Xr malloc 3 ,
742 .Xr opendir 3 ,
743 .Xr readdir 3
744 and
745 .Xr stat 2 .
746 .Pp
747 In addition,
748 .Fn fts_children ,
749 .Fn fts_open
750 and
751 .Fn fts_set
752 may fail and set
753 .Va errno
754 as follows:
755 .Bl -tag -width Er
756 .It Bq Er EINVAL
757 The options were invalid.
758 .El
759 .Sh SEE ALSO
760 .Xr find 1 ,
761 .Xr chdir 2 ,
762 .Xr stat 2 ,
763 .Xr qsort 3 ,
764 .Xr symlink 7
765 .Sh STANDARDS
766 The
767 .Nm
768 utility was expected to be included in the
769 .St -p1003.1-88
770 revision.
771 But twenty years later, it still was not included in the
772 .St -p1003.1-2008
773 revision.