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 | .\" |
974f7ae8 | 6 | .\" @(#)fts.3 5.8 (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 | ||
19 | FTS * | |
1caff52e | 20 | fts_open(path_argv, options, compar) |
c4e1185d KB |
21 | char *path_argv[]; |
22 | int options, (*compar)(); | |
23 | ||
24 | FTSENT * | |
1caff52e | 25 | fts_read(ftsp); |
c4e1185d KB |
26 | FTS *ftsp; |
27 | ||
28 | FTSENT * | |
1caff52e | 29 | fts_children(ftsp) |
c4e1185d KB |
30 | FTS *ftsp; |
31 | ||
1caff52e | 32 | fts_set(ftsp, f, options) |
c4e1185d KB |
33 | FTS *ftsp; |
34 | FTSENT *f; | |
35 | int options; | |
36 | ||
1caff52e | 37 | fts_close(ftsp) |
c4e1185d KB |
38 | FTS *ftsp; |
39 | .ft R | |
40 | .fi | |
41 | .SH DESCRIPTION | |
42 | The | |
43 | .IR fts (3) | |
1caff52e | 44 | functions are provided for traversing UNIX file hierarchies. |
9a0aa1ee | 45 | .PP |
1caff52e KB |
46 | The simple overview is that the function |
47 | .I fts_open | |
48 | returns a ``handle'' on a file hierarchy, which is supplied to the other | |
97bb157b | 49 | .I fts |
1caff52e KB |
50 | functions to determine which hierarchy they operate on. |
51 | The function | |
52 | .I fts_read | |
53 | returns a pointer to a structure describing one of the files in the file | |
54 | hierarchy. | |
55 | The function | |
56 | .I fts_children | |
57 | returns a pointer to a linked list of structures, each of which describes | |
58 | one of the files contained in a directory in the hierarchy. | |
59 | In general, directories are visited two distinguishable times; in pre-order | |
60 | (before any of their descendants are visited) and in post-order (after all | |
61 | of their descendants have been visited). | |
62 | Files are visited once. | |
63 | It is possible to walk the hierarchy ``logically'' (ignoring symbolic links) | |
64 | or physically (visiting symbolic links), order the walk of the hierarchy or | |
65 | prune and/or re-visit portions of the hierarchy. | |
c4e1185d | 66 | .PP |
1caff52e KB |
67 | Two structures are defined (and typedef'd) in the include file <fts.h>. |
68 | The first is FTS, the structure that represents the file hierarchy stream. | |
69 | The second is FTSENT, the structure that represents a file in the file | |
70 | hierarchy. | |
71 | Normally, an FTSENT structure is returned for every file in the file | |
72 | hierarchy. | |
73 | In this manual page, ``file'' and ``FTSENT structure'' are generally | |
74 | interchangeable. | |
75 | The FTSENT structure contains at least the following fields, which are | |
76 | described in greater detail below: | |
c4e1185d | 77 | .sp |
c4e1185d KB |
78 | .nf |
79 | .ta .5i +.5i +\w'struct ftsent *parent;\0\0\0'u | |
1caff52e KB |
80 | typedef struct _ftsent { |
81 | u_short fts_info; /* flags for FTSENT structure */ | |
82 | char *fts_accpath; /* access path */ | |
83 | char *fts_path; /* root path */ | |
84 | short fts_pathlen; /* strlen(fts_path) */ | |
df589a0d | 85 | char *fts_name; /* file name */ |
1caff52e | 86 | short fts_namelen; /* strlen(fts_name) */ |
df589a0d | 87 | short fts_level; /* depth (\-1 to N) */ |
974f7ae8 | 88 | long fts_number; /* local numeric value */ |
1caff52e KB |
89 | void *fts_pointer; /* local address value */ |
90 | struct ftsent *fts_parent; /* parent directory */ | |
91 | struct ftsent *fts_link; /* cycle or next file structure */ | |
df589a0d | 92 | struct stat fts_statb; /* stat(2) information */ |
c4e1185d KB |
93 | } FTSENT; |
94 | .fi | |
c4e1185d | 95 | .PP |
1caff52e | 96 | These fields are defined as follows: |
c4e1185d | 97 | .TP |
df589a0d | 98 | fts_info |
1caff52e KB |
99 | One of the following flags describing the returned FTSENT structure and |
100 | the file it represents. | |
101 | With the exception of directories without errors (FTS_D), all of these | |
102 | entries are terminal, that is, they will not be revisited, nor will any | |
103 | of their descendants be visited. | |
c4e1185d KB |
104 | .RS |
105 | .TP | |
106 | FTS_D | |
107 | A directory being visited in pre-order. | |
108 | .TP | |
109 | FTS_DC | |
1caff52e KB |
110 | A directory that causes a cycle in the tree. |
111 | (The | |
df589a0d | 112 | .I fts_link |
1caff52e | 113 | field of the FTSENT structure will be filled in as well.) |
c4e1185d KB |
114 | .TP |
115 | FTS_DEFAULT | |
1caff52e KB |
116 | Any FTSENT structure that represents a file type not explicitly described |
117 | by one of the other | |
118 | .I fts_info | |
119 | values. | |
c4e1185d KB |
120 | .TP |
121 | FTS_DNR | |
1caff52e KB |
122 | A directory which cannot be read. |
123 | Directory readability is checked before directory searchability | |
124 | (see FTS_DNX). | |
c4e1185d KB |
125 | .TP |
126 | FTS_DNX | |
1caff52e KB |
127 | A directory which cannot be searched. |
128 | Directory readability is checked before directory searchability | |
129 | (see FTS_DNR). | |
c4e1185d KB |
130 | .TP |
131 | FTS_DOT | |
1caff52e KB |
132 | A file named ``.'' or ``..'' which was not specified as a file name to |
133 | .I fts_open | |
134 | (see FTS_SEEDOT). | |
c4e1185d KB |
135 | .TP |
136 | FTS_DP | |
1caff52e KB |
137 | A directory being visited in post-order. |
138 | The contents of the FTSENT structure will be unchanged from when | |
139 | it was returned in pre-order, i.e. with the | |
140 | .I fts_info | |
141 | field set to FTS_D. | |
c4e1185d KB |
142 | .TP |
143 | FTS_ERR | |
1caff52e | 144 | An error return; the external variable |
c4e1185d | 145 | .I errno |
1caff52e | 146 | will be set to indicate the error. |
c4e1185d KB |
147 | .TP |
148 | FTS_F | |
149 | A regular file. | |
150 | .TP | |
151 | FTS_NS | |
1caff52e | 152 | A file for which no |
c4e1185d | 153 | .IR stat (2) |
1caff52e KB |
154 | information was available (see FTS_NOSTAT). |
155 | In this case the contents of the | |
df589a0d | 156 | .I fts_statb |
c4e1185d KB |
157 | field are undefined. |
158 | .TP | |
159 | FTS_SL | |
160 | A symbolic link. | |
161 | .TP | |
162 | FTS_SLNONE | |
163 | A symbolic link with a non-existent target. | |
164 | .RE | |
165 | .TP | |
1caff52e KB |
166 | fts_accpath |
167 | A path for accessing the file. | |
168 | This will be the same as | |
169 | .I fts_path | |
170 | or | |
171 | .IR fts_name , | |
172 | depending on whether the | |
173 | .I fts | |
174 | functions are changing the current working directory or not (see FTS_NOCHDIR). | |
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 | |
309 | field to FTS_NS and leave the contents of the | |
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. | |
358 | If the option FTS_NOSTAT was specified, or the | |
359 | .I fts_info | |
360 | field was set to FTS_NS, the | |
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. | |
373 | Directories (that are readable, searchable and do not cause cycles) are | |
374 | visited at least twice, once in pre-order and once in post-order. | |
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. | |
390 | If an error related to the returned file occurs, a pointer to an FTSENT | |
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 | |
423 | If the directory returned by | |
424 | .I fts_read | |
425 | is readable but not searchable (see FTS_DNR and FTS_DNX) the contents | |
426 | of the directory may be retrieved using the | |
427 | .I fts_children | |
428 | function. | |
429 | Pathnames to the files may be built as well, as there is guaranteed | |
430 | to be sufficient space in the path buffer to construct them as follows: | |
431 | .sp | |
432 | .nf | |
433 | .RS | |
434 | char *p; | |
435 | for (p = ftsent->fts_path; *p; ++p); | |
436 | *p++ = '/'; | |
437 | bcopy(ftsent->fts_name, p, ftsent->fts_namelen + 1); | |
438 | .RE | |
439 | .fi | |
440 | .PP | |
441 | If the FTSENT structure most recently returned by | |
442 | .I fts_read | |
443 | is not a directory being visited in pre-order, | |
444 | or the directory does not contain any files, | |
445 | .I fts_children | |
446 | returns NULL and sets | |
447 | .I errno | |
448 | to zero. | |
c4e1185d | 449 | If an error occurs, |
1caff52e KB |
450 | .I fts_children |
451 | returns NULL and sets | |
452 | .I errno | |
453 | appropriately. | |
c4e1185d | 454 | .PP |
1caff52e KB |
455 | The FTSENT structures returned by |
456 | .I fts_children | |
c4e1185d | 457 | may be overwritten after a call to |
1caff52e KB |
458 | .I fts_close |
459 | on the same file hierarchy stream, or after a call to | |
460 | .I fts_children | |
c4e1185d | 461 | or |
1caff52e KB |
462 | .I fts_read |
463 | on the same file hierarchy stream. | |
c4e1185d | 464 | .PP |
1caff52e KB |
465 | A single buffer is used for all of the paths of all of the files in the |
466 | file hierarchy. | |
467 | Therefore, the | |
468 | .I fts_path | |
469 | and | |
470 | .I fts_accpath | |
471 | fields are guaranteed to be NULL-terminated | |
472 | .B only | |
473 | for the file most recently returned by | |
474 | .IR fts_read . | |
475 | To use these fields to reference any files represented by other FTSENT | |
476 | structures will require that the path buffer be modified using the | |
477 | information contained in that FTSENT structure's | |
478 | .I fts_pathlen | |
479 | field. | |
480 | Any such modifications should be undone before further calls to | |
481 | .I fts_read | |
482 | are attempted. | |
483 | The | |
484 | .I fts_name | |
485 | field is always NULL-terminated. | |
486 | .SH FTS_SET | |
487 | The function | |
488 | .I fts_set | |
c4e1185d KB |
489 | allows the user application to determine further processing for the |
490 | file | |
491 | .I f | |
492 | of the stream | |
493 | .IR ftsp . | |
1caff52e | 494 | .I Fts_set |
c4e1185d KB |
495 | returns 0 on success, and -1 if an error occurs. |
496 | .I Option | |
1caff52e | 497 | must be set to one of the following values: |
c4e1185d KB |
498 | .TP |
499 | FTS_AGAIN | |
500 | Re-visit the file; any file type may be re-visited. | |
501 | The next call to | |
1caff52e | 502 | .I fts_read |
c4e1185d | 503 | will return the referenced file. |
1caff52e | 504 | The |
df589a0d | 505 | .I fts_stat |
c4e1185d | 506 | and |
df589a0d | 507 | .I fts_info |
c4e1185d | 508 | fields of the structure will be reinitialized at that time, |
1caff52e | 509 | but no other fields will have been changed. |
c4e1185d KB |
510 | This option is meaningful only for the most recently returned |
511 | file from | |
1caff52e | 512 | .IR fts_read . |
c4e1185d KB |
513 | Normal use is for post-order directory visits, where it causes the |
514 | directory to be re-visited (in both pre and post-order) as well as all | |
515 | of its descendants. | |
516 | .TP | |
517 | FTS_FOLLOW | |
518 | The referenced file must be a symbolic link. | |
519 | If the referenced file is the one most recently returned by | |
1caff52e | 520 | .IR fts_read , |
c4e1185d | 521 | the next call to |
1caff52e | 522 | .I fts_read |
c4e1185d | 523 | returns the file with the |
df589a0d | 524 | .I fts_info |
c4e1185d | 525 | and |
df589a0d | 526 | .I fts_statb |
c4e1185d KB |
527 | fields reinitialized to reflect the target of the symbolic link instead |
528 | of the symbolic link itself. | |
529 | If the file is one of those most recently returned by | |
1caff52e | 530 | .IR fts_children , |
c4e1185d | 531 | the |
df589a0d | 532 | .I fts_info |
c4e1185d | 533 | and |
df589a0d | 534 | .I fts_statb |
c4e1185d | 535 | fields of the structure, when returned by |
1caff52e | 536 | .IR fts_read , |
c4e1185d KB |
537 | will reflect the target of the symbolic link instead of the symbolic link |
538 | itself. | |
539 | In either case, if the target of the link is a directory, the pre-order | |
540 | return, followed by the return of all of its descendants, followed by a | |
541 | post-order return, is done. | |
542 | .TP | |
543 | FTS_SKIP | |
544 | No descendants of this file are visited. | |
1caff52e KB |
545 | The file may be one of those most recently returned by either |
546 | .I fts_children | |
547 | or | |
548 | .IR fts_read . | |
549 | .SH FTS_CLOSE | |
550 | The | |
551 | .I fts_close | |
552 | function closes a file hierarchy stream | |
553 | .I ftsp | |
554 | and restores the current directory to the directory from which | |
555 | .I fts_open | |
556 | was called to open | |
557 | .IR ftsp . | |
558 | .I Fts_close | |
559 | returns 0 on success, and -1 if an error occurs. | |
c4e1185d | 560 | .SH ERRORS |
1caff52e | 561 | .I Fts_open |
c4e1185d | 562 | may fail and set errno for any of the errors specified for the library |
974f7ae8 KB |
563 | functions |
564 | .IR open (2) | |
565 | and | |
c4e1185d KB |
566 | .IR malloc (3). |
567 | .PP | |
1caff52e | 568 | .I Fts_close |
c4e1185d | 569 | may fail and set errno for any of the errors specified for the library |
974f7ae8 KB |
570 | functions |
571 | .IR chdir (2) | |
572 | and | |
573 | .IR close (2). | |
c4e1185d | 574 | .PP |
1caff52e | 575 | .I Fts_read |
c4e1185d | 576 | and |
1caff52e | 577 | .I fts_children |
c4e1185d | 578 | may fail and set errno for any of the errors specified for the library |
1caff52e | 579 | functions |
c4e1185d | 580 | .IR chdir (2), |
c4e1185d KB |
581 | .IR malloc (3), |
582 | .IR opendir (3), | |
583 | .IR readdir (3) | |
584 | and | |
585 | .IR stat (2). | |
586 | .SH SEE ALSO | |
587 | find(1), chdir(2), stat(2), qsort(3) | |
588 | .SH STANDARDS | |
589 | The | |
590 | .I fts | |
df589a0d | 591 | utility is expected to be a superset of the POSIX 1003.1 specification. |