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