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