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