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