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