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