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