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