Penguin
Recent Changes
Blame: fts_children(3)
EditPageHistoryDiffInfoLikePages
Annotated edit history of fts_children(3) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 ----
2 __NAME__
3
4
5 fts, fts_open, fts_read, fts_children, fts_set, fts_close -
6 traverse a file hierarchy
7 __SYNOPSIS__
8
2 KirkBaker 9 #include <sys/types.h>
10 #include <sys/stat.h>
11 #include <fts.h>
1 perry 12
13 FTS
14
15
16 fts_open(char const path_argv, int options, int
17 (compar)(const FTSENT , const FTSENT ));
18
19
20 FTSENT
21
22
23 fts_read(FTS ftsp);
24
25
26 FTSENT
27
28
29 fts_children(FTS ftsp, int options);
30
31
32 int
33
34
35 fts_set(FTS ftsp, FTSENT f, int options);
36
37
38 int
39
40
41 fts_close(FTS ftsp);
42 __DESCRIPTION__
43
44
45 The fts functions are provided for traversing
46 UNIX file hierarchies. A simple overview is
47 that the fts_open() func- tion returns a ``handle'' on a
48 file hierarchy, which is then supplied to the other fts
49 functions. The function fts_read() returns a pointer to a
50 structure describing one of the files in the file hierarchy.
51 The function fts_children() returns a pointer to a linked
52 list of struc- tures, each of which describes one of the
53 files contained in a directory in the hierarchy. In general,
54 directories are visited two distinguishable times; in
55 pre-order (before any of their descendants are visited) and
56 in post-order (after all of their descendants have been
57 visited). Files are vis- ited once. It is possible to walk
58 the hierarchy ``logi- cally'' (ignoring symbolic links) or
59 physically (visiting symbolic links), order the walk of the
60 hierarchy or prune and/or re-visit portions of the
61 hierarchy.
62
63
64 Two structures are defined (and typedef'd) in the include file fts.h. The first is FTS, the structure that repre- sents the file hierarchy itself. The second is FTSENT, the structure that represents a file in the file hierarchy. Normally, an FTSENT structure is returned for every file in the file hierarchy. In this manual page, ``file'' and ``FTSENT structure'' are generally interchangeable. The FTSENT structure contains at least the following fields, which are described in greater detail below:
65
66
67 typedef struct _ftsent {
68 u_short fts_info; / flags for FTSENT structure /
69 char fts_accpath; / access path /
70 char fts_path; / root path /
71 short fts_pathlen; / strlen(fts_path) /
72 char fts_name; / file name /
73 short fts_namelen; / strlen(fts_name) /
74 short fts_level; / depth (-1 to N) /
75 int fts_errno; / file errno /
76 long fts_number; / local numeric value /
77 void fts_pointer; / local address value /
78 struct ftsent fts_parent; / parent directory /
79 struct ftsent fts_link; / next file structure /
80 struct ftsent fts_cycle; / cycle structure /
81 struct stat fts_statp; / stat(2) information /
82 } FTSENT;
83
84
85 These fields are defined as follows:
86 fts_info One of the following flags describing thereturned FTSENT structure and the file it repre-sents. With the exception of directories with-out errors (FTS_D
87 ), all of these entries are terminal, that is, they will
88 not be revisited, nor will any of their descendants be
89 visited.
90
91
92 FTS_D
93 A directory being visited in pre-order.
94
95
96 FTS_DC
97 A directory that causes a cycle in the tree. (The fts_cycle
98 field of the FTSENT structure will be filled in as
99 well.)
100
101
102 FTS_DEFAULT
103 Any FTSENT structure that represents a file type not
104 explicitly described by one of the other fts_info
105 values.
106
107
108 FTS_DNR
109 A directory which cannot be read. This is an error return,
110 and the fts_errno field will be set to indi- cate what
111 caused the error.
112
113
114 FTS_DOT
115 A file named . or .. which was not
116 specified as a file name to fts_open() (see
117 FTS_SEEDOT).
118
119
120 FTS_DP
121 A directory being visited in post-order. The contents of the
122 FTSENT structure will be unchanged from when it was returned
123 in pre-order, i.e. with the fts_info field set to
124 FTS_D.
125
126
127 FTS_ERR
128 This is an error return, and the fts_errno field will be set
129 to indi- cate what caused the error.
130
131
132 FTS_F
133 A regular file.
134
135
136 FTS_NS
137 A file for which no stat(2) informa- tion was
138 available. The contents of the fts_statp field are
139 undefined. This is an error return, and the fts_errno field
140 will be set to indi- cate what caused the
141 error.
142
143
144 FTS_NSOK
145 A file for which no stat(2) informa- tion was
146 requested. The contents of the fts_statp field are
147 undefined.
148
149
150 FTS_SL
151 A symbolic link.
152
153
154 FTS_SLNONE
155 A symbolic link with a non-existent target. The contents of
156 the fts_statp field reference the file characteristic
157 information for the symbolic link itself.
158
159
160 fts_accpath
161 A path for accessing the file from the current
162 directory.
163
164
165 fts_path
166 The path for the file relative to the root of the traversal.
167 This path contains the path specified to fts_open() as a
168 prefix.
169
170
171 fts_pathlen
172 The length of the string referenced by
173 fts_path.
174
175
176 fts_name
177 The name of the file.
178
179
180 fts_namelen
181 The length of the string referenced by
182 fts_name.
183
184
185 fts_level
186 The depth of the traversal, numbered from -1 to N, where
187 this file was found. The FTSENT struc- ture representing the
188 parent of the starting point (or root) of the traversal is
189 numbered -1, and the FTSENT structure for the root itself is
190 numbered 0.
191
192
193 fts_errno
194 Upon return of a FTSENT structure from the fts_children() or
195 fts_read() functions, with its fts_info field set to
196 FTS_DNR, FTS_ERR or FTS_NS, the
197 fts_errno field contains the value of the external variable
198 ''errno'' specifying the cause of the error. Otherwise,
199 the contents of the fts_errno field are
200 undefined.
201
202
203 fts_number
204 This field is provided for the use of the appli- cation
205 program and is not modified by the fts functions. It is
206 initialized to 0.
207
208
209 fts_pointer
210 This field is provided for the use of the appli- cation
211 program and is not modified by the fts functions. It is
212 initialized to NULL.
213
214
215 fts_parent
216 A pointer to the FTSENT structure referencing the file in
217 the hierarchy immediately above the current file, i.e. the
218 directory of which this file is a member. A parent structure
219 for the initial entry point is provided as well, how- ever,
220 only the fts_level, fts_number and fts_pointer fields are
221 guaranteed to be initial- ized.
222
223
224 fts_link
225 Upon return from the fts_children() function, the fts_link
226 field points to the next structure in the NULL-terminated
227 linked list of directory members. Otherwise, the contents of
228 the fts_link field are undefined.
229
230
231 fts_cycle
232 If a directory causes a cycle in the hierarchy (see
233 FTS_DC), either because of a hard link between two
234 directories, or a symbolic link pointing to a directory, the
235 fts_cycle field of the structure will point to the FTSENT
236 structure in the hierarchy that references the same file as
237 the current FTSENT structure. Otherwise, the contents of the
238 fts_cycle field are undefined.
239
240
241 fts_statp
242 A pointer to stat(2) information for the
243 file.
244
245
246 A single buffer is used for all of the paths of all of the
247 files in the file hierarchy. Therefore, the fts_path and
248 fts_accpath fields are guaranteed to be
249 NULL-terminated ''only'' for the file most
250 recently returned by fts_read(). To use these fields to
251 reference any files represented by other FTSENT structures
252 will require that the path buffer be modi- fied using the
253 information contained in that FTSENT struc- ture's
254 fts_pathlen field. Any such modifications should be undone
255 before further calls to fts_read() are attempted. The
256 fts_name field is always
257 NULL-terminated.
258
259
260 __FTS_OPEN__
261
262
263 The fts_open() function takes a pointer to an array of char-
264 acter pointers naming one or more paths which make up a log-
265 ical file hierarchy to be traversed. The array must be ter-
266 minated by a NULL pointer.
267
268
269 There are a number of options, at least one of which (either
270 FTS_LOGICAL or FTS_PHYSICAL) must be
271 specified. The options are selected by ''or'''ing the
272 following values:
273 FTS_COMFOLLOW
274
275
276 This option causes any symbolic link specified as a root
277 path to be followed immediately whether or not
278 FTS_LOGICAL is also specified.
279
280
281 FTS_LOGICAL
282 This option causes the fts routines to return FTSENT
283 structures for the targets of symbolic links instead of the
284 symbolic links themselves. If this option is set, the only
285 symbolic links for which FTSENT structures are returned to
286 the application are those referencing non-existent files.
287 Either FTS_LOGICAL or FTS_PHYSICAL
288 ''must'' be provided to the fts_open()
289 function.
290
291
292 FTS_NOCHDIR
293 As a performance optimization, the fts func- tions change
294 directories as they walk the file hierarchy. This has the
295 side-effect that an application cannot rely on being in any
296 partic- ular directory during the traversal. The
297 FTS_NOCHDIR option turns off this optimization, and
298 the fts functions will not change the cur- rent directory.
299 Note that applications should not themselves change their
300 current directory and try to access files unless
301 FTS_NOCHDIR is specified and absolute pathnames
302 were provided as arguments to fts_open().
303
304
305 FTS_NOSTAT
306 By default, returned FTSENT structures refer- ence file
307 characteristic information (the statp field) for each file
308 visited. This option relaxes that requirement as a
309 performance opti- mization, allowing the fts functions to
310 set the fts_info field to FTS_NSOK and leave the
311 con- tents of the statp field undefined.
312
313
314 FTS_PHYSICAL
315 This option causes the fts routines to return FTSENT
316 structures for symbolic links themselves instead of the
317 target files they point to. If this option is set, FTSENT
318 structures for all symbolic links in the hierarchy are
319 returned to the application. Either FTS_LOGICAL or
320 FTS_PHYSICAL ''must'' be provided to the
321 fts_open() function.
322
323
324 FTS_SEEDOT
325 By default, unless they are specified as path arguments to
326 fts_open(), any files named . or ..
327 encountered in the file hierarchy are ignored. This option
328 causes the fts routines to return FTSENT structures for
329 them.
330
331
332 FTS_XDEV
333 This option prevents fts from descending into directories
334 that have a different device number than the file from which
335 the descent began.
336
337
338 The argument compar() specifies a user-defined function
339 which may be used to order the traversal of the hierarchy.
340 It takes two pointers to pointers to FTSENT structures as
341 arguments and should return a negative value, zero, or a
342 positive value to indicate if the file referenced by its
343 first argument comes before, in any order with respect to,
344 or after, the file referenced by its second argument. The
345 fts_accpath, fts_path and fts_pathlen fields of the FTSENT
346 structures may ''never'' be used in this comparison. If
347 the fts_info field is set to FTS_NS or
348 FTS_NSOK, the fts_statp field may not either. If
349 the compar() argument is NULL, the directory
350 traversal order is in the order listed in path_argv for the
351 root paths, and in the order listed in the directory for
352 everything else.
353
354
355 __FTS_READ__
356
357
358 The fts_read() function returns a pointer to an FTSENT
359 structure describing a file in the hierarchy. Directories
360 (that are readable and do not cause cycles) are visited at
361 least twice, once in pre-order and once in post-order. All
362 other files are visited at least once. (Hard links between
363 directories that do not cause cycles or symbolic links to
364 symbolic links may cause files to be visited more than once,
365 or directories more than twice.)
366
367
368 If all the members of the hierarchy have been returned,
369 fts_read() returns NULL and sets the external
370 variable ''errno'' to 0. If an error unrelated to a file
371 in the hierarchy occurs, fts_read() returns NULL
372 and sets ''errno'' appropri- ately. If an error related
373 to a returned file occurs, a pointer to an FTSENT structure
374 is returned, and ''errno'' may or may not have been set
375 (see fts_info).
376
377
378 The FTSENT structures returned by fts_read() may be over-
379 written after a call to fts_close() on the same file hierar-
380 chy stream, or, after a call to fts_read() on the same file
381 hierarchy stream unless they represent a file of type direc-
382 tory, in which case they will not be overwritten until after
383 a call to fts_read() after the FTSENT structure has been
384 returned by the function fts_read() in
385 post-order.
386 __FTS_CHILDREN__
387
388
389 The fts_children() function returns a pointer to an FTSENT
390 structure describing the first entry in a NULL-terminated
391 linked list of the files in the directory represented by the
392 FTSENT structure most recently returned by fts_read(). The
393 list is linked through the fts_link field of the FTSENT
394 structure, and is ordered by the user-specified comparison
395 function, if any. Repeated calls to fts_children() will
396 recreate this linked list.
397
398
399 As a special case, if fts_read() has not yet been called for a hierarchy, fts_children() will return a pointer to the files in the logical directory specified to fts_open(), i.e. the arguments specified to fts_open(). Otherwise, if the FTSENT structure most recently returned by fts_read() is not a directory being visited in pre-order, or the directory does not contain any files, fts_children() returns NULL and sets ''errno'' to zero. If an error occurs, fts_children() returns NULL and sets ''errno'' appropriately.
400
401
402 The FTSENT structures returned by fts_children() may be
403 overwritten after a call to fts_children(), fts_close() or
404 fts_read() on the same file hierarchy stream.
405
406
407 ''Option'' may be set to the following
408 value:
409 FTS_NAMEONLY
410
411
412 Only the names of the files are needed. The contents of all
413 the fields in the returned linked list of structures are
414 undefined with the exception of the fts_name and fts_namelen
415 fields.
416
417
418 __FTS_SET__
419
420
421 The function fts_set() allows the user application to deter-
422 mine further processing for the file f of the stream ftsp.
423 The fts_set() function returns 0 on success, and -1 if an
424 error occurs. ''Option'' must be set to one of the
425 following values:
426 FTS_AGAIN
427 Re-visit the file; any file type may be re-vis- ited.
428 The next call to fts_read() will return the referenced file.
429 The fts_stat and fts_info fields of the structure will be
430 reinitialized at that time, but no other fields will have
431 been changed. This option is meaningful only for the most
432 recently returned file from fts_read(). Normal use is for
433 post-order directory visits, where it causes the directory
434 to be re-visited (in both pre and post-order) as well as all
435 of its descendants.
436
437
438 FTS_FOLLOW
439 The referenced file must be a symbolic link. If the referenced file is the one most recently returned by fts_read(), the next call to fts_read() returns the file with the fts_info and fts_statp fields reinitialized to reflect the target of the symbolic link instead of the symbolic link itself. If the file is one of those most recently returned by fts_children(), the fts_info and fts_statp fields of the struc- ture, when returned by fts_read(), will reflect the target of the symbolic link instead of the symbolic link itself. In either case, if the target of the symbolic link does not exist the fields of the returned structure will be unchanged and the fts_info field will be set to FTS_SLNONE.
440
441
442 If the target of the link is a directory, the pre-order
443 return, followed by the return of all of its descendants,
444 followed by a post-order return, is done.
445
446
447 FTS_SKIP
448 No descendants of this file are visited. The file may be one
449 of those most recently returned by either fts_children() or
450 fts_read().
451
452
453 __FTS_CLOSE__
454
455
456 The fts_close() function closes a file hierarchy stream ftsp
457 and restores the current directory to the directory from
458 which fts_open() was called to open ftsp. The fts_close()
459 function returns 0 on success, and -1 if an error
460 occurs.
461 __ERRORS__
462
463
464 The function fts_open() may fail and set ''errno'' for
465 any of the errors specified for the library functions
466 open(2) and malloc(3).
467
468
469 The function fts_close() may fail and set ''errno'' for any of the errors specified for the library functions chdir(2) and close(2).
470
471
472 The functions fts_read() and fts_children() may fail and set
473 ''errno'' for any of the errors specified for the library
474 func- tions chdir(2), malloc(3),
475 opendir(3), readdir(3) and
476 stat(2).
477
478
479 In addition, fts_children(), fts_open() and fts_set() may
480 fail and set ''errno'' as follows:
481 [[EINVAL
482 ] The options were invalid.
483
484
485 __SEE ALSO__
486
487
488 find(1), chdir(2), stat(2),
489 qsort(3)
490 __CONFORMING TO__
491
492
493 BSD 4.4. The fts utility is expected to be included in a
494 future IEEE Std 1003.1-1988 (``
495 POSIX .1'') revision.
496 __AVAILABILITY__
497
498
499 These functions are available in Linux since
500 glibc2.
501
502
503 BSD April 16, 1994 1
504 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.