![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to fts.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen|
Return to fts.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen |
1.1 root 1: .\" Copyright (c) 1989 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms are permitted provided
5: .\" that: (1) source distributions retain this entire copyright notice and
6: .\" comment, and (2) distributions including binaries display the following
7: .\" acknowledgement: ``This product includes software developed by the
8: .\" University of California, Berkeley and its contributors'' in the
9: .\" documentation or other materials provided with the distribution and in
10: .\" all advertising materials mentioning features or use of this software.
11: .\" Neither the name of the University nor the names of its contributors may
12: .\" be used to endorse or promote products derived from this software without
13: .\" specific prior written permission.
14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17: .\"
18: .\" @(#)fts.3 5.6 (Berkeley) 6/23/90
19: .\"
20: .TH FTS 3 "June 23, 1990"
21: .UC 7
22: .SH NAME
23: fts \- traverse a file hierarchy
24: .SH SYNOPSIS
25: .nf
26: .ft B
27: #include <sys/types.h>
28: #include <sys/stat.h>
29: #include <fts.h>
30:
31: FTS *
32: ftsopen(path_argv, options, compar)
33: char *path_argv[];
34: int options, (*compar)();
35:
36: FTSENT *
37: ftsread(ftsp);
38: FTS *ftsp;
39:
40: FTSENT *
41: ftschildren(ftsp)
42: FTS *ftsp;
43:
44: ftsset(ftsp, f, options)
45: FTS *ftsp;
46: FTSENT *f;
47: int options;
48:
49: ftsclose(ftsp)
50: FTS *ftsp;
51: .ft R
52: .fi
53: .SH DESCRIPTION
54: The
55: .IR fts (3)
56: utilities are provided for traversing UNIX file hierarchies.
57: Two structures are defined (and typedef'd) in the include file <\fIfts.h\fP>.
58: The first is FTS, the structure that defines the file hierarchy stream.
59: The second is FTSENT, the structure that defines a file in the file
60: hierarchy.
61: .PP
62: The
63: .I ftsopen
64: routine takes a pointer to an array of character pointers (``argv'')
65: naming the file hierarchies to be traversed.
66: The array must be terminated by a pointer to a NULL string.
67: .PP
68: The
69: .I options
70: specified are formed by
71: .IR or 'ing
72: one or more of the following values:
73: .TP
74: FTS_LOGICAL
75: This option causes
76: .I ftsread
77: to use the function
78: .IR stat (2),
79: by default, to determine the status of each file.
80: If this option is set, the only symbolic links returned to the application
81: are those referencing non-existent files.
82: Either FTS_LOGICAL or FTS_PHYSICAL
83: .B must
84: be provided to the
85: .I ftsopen
86: routine.
87: .TP
88: FTS_NOCHDIR
89: As a performance optimization,
90: .I ftsread
91: changes directories as it descends the hierarchy.
92: This has the side-effect that applications cannot rely on being
93: in any particular directory.
94: The FTS_NOCHDIR option turns off this optimization.
95: Note that applications should not change the current directory
96: (even if FTS_NOCHDIR is specified) unless absolute pathnames were
97: provided as arguments to
98: .IR ftsopen .
99: .TP
100: FTS_NOSTAT
101: By default,
102: .I ftsread
103: and
104: .I ftschildren
105: provide file characteristic information (the
106: .I statb
107: field) for each file they return.
108: This option relaxes that requirement; the contents of the
109: .I statb
110: field may be undefined, and the
111: .I info
112: field may be set to FTS_NS.
113: .TP
114: FTS_PHYSICAL
115: This option causes
116: .I ftsread
117: to use the function
118: .IR lstat (2),
119: by default, to determine the status of each file.
120: If this option is set, all symbolic links are returned to the application
121: program.
122: Either FTS_LOGICAL or FTS_PHYSICAL
123: .B must
124: be provided to the
125: .I ftsopen
126: routine.
127: .TP
128: FTS_SEEDOT
129: This option causes the routine
130: .I ftsread
131: to return structures for the directory entries ``.'' and ``..''.
132: By default they are ignored unless specified as an argument to
133: .IR ftsopen .
134: .TP
135: FTS_XDEV
136: This option keeps
137: .I fts
138: from descending into directories that have a different device number
139: than the file the descent began from.
140: .PP
141: The argument
142: .I compar
143: specifies a user-defined routine which is used to order the traversal
144: of directories.
145: .I Compar
146: takes two pointers to pointers to FTSENT structures as arguments and
147: should return a negative value, zero, or a positive value to indicate
148: if the file referenced by its first argument comes before, in any order
149: with respect to, or after, the file referenced by its second argument.
150: .PP
151: The
152: .I fts_accpath
153: and
154: .I fts_path
155: fields of the FTSENT structures may not be used in this comparison.
156: If the option
157: .I FTS_NOSTAT
158: is specified, the
159: .I fts_stab
160: field may not be used as well.
161: If the
162: .I compar
163: argument is NULL the directory traversal order is unspecified except
164: for the root paths which are traversed in the order listed in
165: .IR path_argv .
166: .PP
167: The
168: .I ftsclose
169: routine closes a file hierarchy stream and changes the current
170: directory to the directory
171: .I ftsopen
172: was called from.
173: .I Ftsclose
174: returns 0 on success, and -1 if an error occurs.
175: .PP
176: Each call to the
177: .I ftsread
178: routine returns a pointer to an FTSENT structure describing a file in
179: the hierarchy.
180: Directories (that are readable, searchable and do not cause cycles)
181: are visited at least twice, before any of their descendants have been
182: visited (pre-order) and after all their descendants have been visited
183: (post-order).
184: All other files are visited at least once.
185: .PP
186: The FTSENT structure contains at least the following fields:
187: .sp
188: .RS
189: .nf
190: .ta .5i +.5i +\w'struct ftsent *parent;\0\0\0'u
191: typedef struct ftsent {
192: struct ftsent *fts_parent; /* parent structure */
193: struct ftsent *fts_link; /* cycle or file structure */
194: union {
195: long number; /* local numeric value */
196: void *pointer; /* local address value */
197: } fts_local;
198: char *fts_accpath; /* path from current directory */
199: char *fts_path; /* path from starting directory */
200: char *fts_name; /* file name */
201: short fts_pathlen; /* strlen(path) */
202: short fts_namelen; /* strlen(name) */
203: short fts_level; /* depth (\-1 to N) */
204: unsigned short fts_info; /* flags for entry */
205: struct stat fts_statb; /* stat(2) information */
206: } FTSENT;
207: .fi
208: .RE
209: .PP
210: The fields are as follows:
211: .TP
212: fts_parent
213: A pointer to a structure referencing the file in the hierarchy
214: immediately above the current file/structure.
215: A parent structure for the initial entry point is provided as well,
216: however, only the
217: .I fts_local
218: and
219: .I fts_level
220: fields are guaranteed to be initialized.
221: .TP
222: fts_link
223: If a directory causes a cycle in the hierarchy, either because of a
224: hard link between two directories, or a symbolic link pointing to a
225: directory, the
226: .I fts_link
227: field of the structure will point to the structure in the hierarchy
228: that references the same file as the current structure.
229: Upon return from the
230: .I ftschildren
231: routine, the
232: .I fts_link
233: field points to the next structure in the linked list of entries
234: from the directory.
235: Otherwise, the contents of the
236: .I fts_link
237: field are undefined.
238: .TP
239: fts_local
240: This field is provided for the use of the application program.
241: It can be used to store either a long value or an address.
242: .TP
243: fts_accpath
244: A path that can be used to access the file.
245: .TP
246: fts_path
247: The path for the file relative to the root of the traversal.
248: .TP
249: fts_name
250: The basename of the file.
251: .TP
252: fts_pathlen
253: The length of the string referenced by
254: .IR fts_path .
255: .TP
256: fts_namelen
257: The length of the string referenced by
258: .IR fts_name .
259: .TP
260: fts_level
261: The depth of the traversal, numbered from \-1 to N.
262: The parent structure of the root of the traversal is numbered \-1, and
263: the structure for the root of the traversal is numbered 0.
264: .TP
265: fts_info
266: Information describing the file.
267: With the exception of directories (FTS_D), all of these entries are
268: terminal, i.e. they will not be revisited, nor will their descendants
269: be visited (if they have not been visited already).
270: .RS
271: .TP
272: FTS_D
273: A directory being visited in pre-order.
274: .TP
275: FTS_DC
276: A directory that causes a cycle.
277: The
278: .I fts_link
279: field of the structure will be filled in as well.
280: .TP
281: FTS_DEFAULT
282: Anything that's not one of the others.
283: .TP
284: FTS_DNR
285: A directory that cannot be read.
286: .TP
287: FTS_DNX
288: A directory that cannot be searched.
289: .TP
290: FTS_DOT
291: A file named ``.'' or ``..'' with a
292: .I fts_level
293: field not equal to zero, i.e. one not specified as an argument to
294: .IR ftsopen .
295: (See FTS_SEEDOT.)
296: .TP
297: FTS_DP
298: A directory that is being visited in post-order.
299: The contents of the structure will be unchanged from when the
300: directory was visited in pre-order.
301: .TP
302: FTS_ERR
303: An error indicator; the external variable
304: .I errno
305: contains an error number indicating the reason for the error.
306: .TP
307: FTS_F
308: A regular file.
309: .TP
310: FTS_NS
311: No
312: .IR stat (2)
313: information is available at this time (see FTS_NOSTAT); the
314: contents of the
315: .I fts_statb
316: field are undefined.
317: .TP
318: FTS_SL
319: A symbolic link.
320: .TP
321: FTS_SLNONE
322: A symbolic link with a non-existent target.
323: .RE
324: .TP
325: fts_statb
326: .IR Stat (2)
327: information for the file.
328: .PP
329: The
330: .I fts_accpath
331: and
332: .I fts_path
333: fields are guaranteed to be NULL-terminated
334: .B only
335: for the file most recently returned by
336: .IR ftsread .
337: The
338: .I fts_name
339: field is always NULL-terminated.
340: To use these fields to reference any other active files may require
341: that they be modified using the information contained in the
342: .I fts_pathlen
343: field.
344: Any such modifications should be undone before further calls to
345: .I ftsread
346: are attempted.
347: .PP
348: If all the members of the hierarchy have been returned,
349: .I ftsread
350: returns NULL and sets the external variable
351: .I errno
352: to 0.
353: If an error unrelated to a file in the hierarchy occurs,
354: .I ftsread
355: returns NULL and sets errno appropriately.
356: Otherwise, a pointer to an FTSENT structure is returned, and an
357: error may or may not have occurred; see FTS_ERR above.
358: .PP
359: When the most recently returned file from
360: .I ftsread
361: is a directory being visited in pre-order,
362: .I ftschildren
363: returns a pointer to the first entry in a linked list (sorted by
364: the comparison routine, if provided) of the directory entries
365: it contains.
366: The linked list is linked through the
367: .I fts_link
368: field of the FTSENT structure.
369: Each call to
370: .I ftschildren
371: recreates the list.
372: Note, cycles are not detected until a directory is actually visited,
373: therefore
374: .I ftschildren
375: will never return a structure with an
376: .I fts_info
377: field set to FTS_DC.
378: If the current file is not a directory being visited in pre-order,
379: or if an error occurs, or the file does not contain any entries
380: .I ftschildren
381: returns NULL.
382: If an error occurs,
383: .I ftschildren
384: sets errno appropriately, otherwise it sets errno to zero.
385: .PP
386: The pointers returned by
387: .I ftsread
388: and
389: .I ftschildren
390: point to structures which may be overwritten.
391: Structures returned by
392: .I ftschildren
393: and
394: .I ftsread
395: may be overwritten after a call to
396: .I ftsclose
397: on the same file hierarchy.
398: Otherwise, structures returned by
399: .I ftschildren
400: will not be overwritten until a subsequent call to either
401: .I ftschildren
402: or
403: .I ftsread
404: on the same file hierarchy.
405: Structures returned by
406: .I ftsread
407: will not not be overwritten until a subsequent call to
408: .I ftsread
409: on the same file hierarchy stream, unless it represents a file of type
410: directory, in which case it will not be overwritten until after a
411: subsequent call to
412: .I ftsread
413: after it has been returned by the function
414: .I ftsread
415: in post-order.
416: .PP
417: The routine
418: .I ftsset
419: allows the user application to determine further processing for the
420: file
421: .I f
422: of the stream
423: .IR ftsp .
424: .I Ftsset
425: returns 0 on success, and -1 if an error occurs.
426: .I Option
427: may be set to any one of the following values.
428: .TP
429: FTS_AGAIN
430: Re-visit the file; any file type may be re-visited.
431: The next call to
432: .I ftsread
433: will return the referenced file.
434: The
435: .I fts_stat
436: and
437: .I fts_info
438: fields of the structure will be reinitialized at that time,
439: but no other fields will have been modified.
440: This option is meaningful only for the most recently returned
441: file from
442: .IR ftsread .
443: Normal use is for post-order directory visits, where it causes the
444: directory to be re-visited (in both pre and post-order) as well as all
445: of its descendants.
446: .TP
447: FTS_FOLLOW
448: The referenced file must be a symbolic link.
449: If the referenced file is the one most recently returned by
450: .IR ftsread ,
451: the next call to
452: .I ftsread
453: returns the file with the
454: .I fts_info
455: and
456: .I fts_statb
457: fields reinitialized to reflect the target of the symbolic link instead
458: of the symbolic link itself.
459: If the file is one of those most recently returned by
460: .IR ftschildren ,
461: the
462: .I fts_info
463: and
464: .I fts_statb
465: fields of the structure, when returned by
466: .IR ftsread ,
467: will reflect the target of the symbolic link instead of the symbolic link
468: itself.
469: In either case, if the target of the link is a directory, the pre-order
470: return, followed by the return of all of its descendants, followed by a
471: post-order return, is done.
472: .TP
473: FTS_SKIP
474: No descendants of this file are visited.
475: .PP
476: Hard links between directories that do not cause cycles or symbolic
477: links to symbolic links may cause files to be visited more than once,
478: or directories more than twice.
479: .SH ERRORS
480: .I Ftsopen
481: may fail and set errno for any of the errors specified for the library
482: routine
483: .IR malloc (3).
484: .PP
485: .I Ftsclose
486: may fail and set errno for any of the errors specified for the library
487: routine
488: .IR chdir (2).
489: .PP
490: .I Ftsread
491: and
492: .I ftschildren
493: may fail and set errno for any of the errors specified for the library
494: routines
495: .IR chdir (2),
496: .IR getgroups (2),
497: .IR malloc (3),
498: .IR opendir (3),
499: .IR readdir (3)
500: and
501: .IR stat (2).
502: .SH SEE ALSO
503: find(1), chdir(2), stat(2), qsort(3)
504: .SH STANDARDS
505: The
506: .I fts
507: utility is expected to be a superset of the POSIX 1003.1 specification.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.