+.\" Copyright (c) 1989 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms are permitted
+.\" provided that the above copyright notice and this paragraph are
+.\" duplicated in all such forms and that any documentation,
+.\" advertising materials, and other materials related to such
+.\" distribution and use acknowledge that the software was developed
+.\" by the University of California, Berkeley. The name of the
+.\" University may not be used to endorse or promote products derived
+.\" from this software without specific prior written permission.
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" @(#)fts.3 5.1 (Berkeley) %G%
+.\"
+.TH FTS 3 ""
+.UC 7
+.SH NAME
+fts \- traverse a file hierarchy
+.SH SYNOPSIS
+.nf
+.ft B
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <fts.h>
+
+FTS *
+ftsopen(path, options, compar)
+char *path;
+int options, (*compar)();
+
+FTS *
+ftsopen(path_argv, options | FTS_MULTIPLE, compar)
+char *path_argv[];
+int options, (*compar)();
+
+FTSENT *
+ftsread(ftsp);
+FTS *ftsp;
+
+FTSENT *
+ftschildren(ftsp)
+FTS *ftsp;
+
+ftsset(ftsp, f, options)
+FTS *ftsp;
+FTSENT *f;
+int options;
+
+ftsclose(ftsp)
+FTS *ftsp;
+.ft R
+.fi
+.SH DESCRIPTION
+The
+.IR fts (3)
+utilities are provided for traversing UNIX file hierarchies.
+Two structures are defined (and typedef'd) in the include file <\fIfts.h\fP>.
+The first is FTS, the structure that defines the file hierarchy stream.
+The second is FTSENT, the structure that defines a file in the file
+hierarchy.
+.PP
+The
+.I ftsopen
+routine returns a pointer to a file hierarchy rooted at
+.IR path .
+The
+.I options
+specified are formed by
+.IR or 'ing
+one or more of the following values:
+.TP
+FTS_LOGICAL
+This option causes
+.I ftsread
+to use the function
+.IR stat (2),
+by default, to determine the status of each file.
+If this option is set, the only symbolic links returned to the application
+are those referencing non-existent files.
+Either FTS_LOGICAL or FTS_PHYSICAL
+.B must
+be provided to the
+.I ftsopen
+routine.
+.TP
+FTS_MULTIPLE
+.I Ftsopen
+takes a single file name as a path argument by default.
+If the FTS_MULTIPLE option is specified, the path argument is a pointer
+to an array of character pointers (``argv'') to the paths to be traversed.
+The array must be terminated by a pointer to a NULL string.
+In this case the ``logical'' hierarchy is traversed, i.e. it's as if
+there's a virtual directory that contains the list of paths supplied,
+and the hierarchy is rooted in that directory.
+.TP
+FTS_NOCHDIR
+As a performance optimization,
+.I ftsread
+changes directories as it descends the hierarchy.
+This has the side-effect that applications cannot rely on being
+in any particular directory.
+The FTS_NOCHDIR option turns off this optimization.
+Note that applications should not change the current directory
+(even if FTS_NOCHDIR is specified) unless absolute pathnames were
+provided as arguments to
+.IR ftsopen .
+.TP
+FTS_NOSTAT
+By default,
+.I ftsread
+and
+.I ftschildren
+provide file characteristic information (the
+.I statb
+field) for each file they return.
+This option relaxes that requirement; the contents of the
+.I statb
+field may be undefined, and the
+.I info
+field may be set to FTS_NS.
+.TP
+FTS_PHYSICAL
+This option causes
+.I ftsread
+to use the function
+.IR lstat (2),
+by default, to determine the status of each file.
+If this option is set, all symbolic links are returned to the application
+program.
+Either FTS_LOGICAL or FTS_PHYSICAL
+.B must
+be provided to the
+.I ftsopen
+routine.
+.TP
+FTS_SEEDOT
+This option causes the routine
+.I ftsread
+to return structures for the directory entries ``.'' and ``..''.
+By default they are ignored unless specified as an argument to
+.IR ftsopen .
+.PP
+The argument
+.I compar
+specifies a user-defined routine which is used to order the traversal
+of directories.
+.I Compar
+takes two pointers to pointers to FTSENT structures as arguments and
+should return a negative value, zero, or a positive value to indicate
+if the file referenced by its first argument comes before, in any order
+with respect to, or after, the file referenced by its second argument.
+Note, the
+.I accpath
+and
+.I path
+fields of the FTSENT structures may not be used in this comparison.
+.PP
+If both FTS_MULTIPLE and the user comparison routine are specified,
+the root paths are processed in sorted order.
+Otherwise, the root paths are processed in the order specified by
+the user.
+.PP
+The
+.I ftsclose
+routine closes a file hierarchy stream and changes the current
+directory to the directory
+.I ftsopen
+was called from.
+.I Ftsclose
+returns 0 on success, and -1 if an error occurs.
+.PP
+Each call to the
+.I ftsread
+routine returns a pointer to an FTSENT structure describing a file in
+the hierarchy.
+Directories (that are readable, searchable and do not cause cycles)
+are visited at least twice, before any of their descendants have been
+visited (pre-order) and after all their descendants have been visited
+(post-order).
+All other files are visited at least once.
+.PP
+The FTSENT structure contains at least the following fields:
+.sp
+.RS
+.nf
+.ta .5i +.5i +\w'struct ftsent *parent;\0\0\0'u
+typedef struct ftsent {
+ struct ftsent *parent; /* parent structure */
+ struct ftsent *link; /* cycle or file structure */
+ union {
+ long number; /* local numeric value */
+ void *pointer; /* local address value */
+ } local;
+ char *accpath; /* path from current directory */
+ char *path; /* path from starting directory */
+ char *name; /* file name */
+ short pathlen; /* strlen(path) */
+ short namelen; /* strlen(name) */
+ short level; /* depth (\-1 to N) */
+ unsigned short info; /* flags for entry */
+ struct stat statb; /* stat(2) information */
+} FTSENT;
+.fi
+.RE
+.PP
+The fields are as follows:
+.TP
+parent
+A pointer to a structure referencing the file in the hierarchy
+immediately above the current file/structure.
+A parent structure for the initial entry point is provided as well,
+however, only the
+.I local
+and
+.I level
+fields are guaranteed to be initialized.
+.TP
+link
+If a directory causes a cycle in the hierarchy, either because of a
+hard link between two directories, or a symbolic link pointing to a
+directory, the
+.I link
+field of the structure will point to the structure in the hierarchy
+that references the same file as the current structure.
+Upon return from the
+.I ftschildren
+routine, the
+.I link
+field points to the next structure in the linked list of entries
+from the directory.
+Otherwise, the contents of the link field are undefined.
+.TP
+local
+This field is provided for the use of the application program.
+It can be used to store either a long value or an address.
+.TP
+accpath
+A path that can be used to access the file.
+.TP
+path
+The path for the file relative to the root of the traversal.
+.TP
+name
+The basename of the file.
+.TP
+pathlen
+The length of the string referenced by
+.IR path .
+.TP
+namelen
+The length of the string referenced by
+.IR name .
+.TP
+level
+The depth of the traversal, numbered from \-1 to N.
+The parent structure of the root of the traversal is numbered \-1, and
+the structure for the root of the traversal is numbered 0.
+.TP
+info
+Information describing the file.
+With the exception of directories (FTS_D), all of these entries are
+terminal, i.e. they will not be revisited, nor will their descendants
+be visited (if they have not been visited already).
+.RS
+.TP
+FTS_D
+A directory being visited in pre-order.
+.TP
+FTS_DC
+A directory that causes a cycle.
+The
+.I link
+field of the structure will be filled in as well.
+.TP
+FTS_DEFAULT
+Anything that's not one of the others.
+.TP
+FTS_DNR
+A directory that cannot be read.
+.TP
+FTS_DNX
+A directory that cannot be searched.
+.TP
+FTS_DOT
+A file named ``.'' or ``..'' with a
+.I level
+field not equal to zero, i.e. one not specified as an argument to
+.IR ftsopen .
+(See FTS_SEEDOT.)
+.TP
+FTS_DP
+A directory that is being visited in post-order.
+The contents of the structure will be unchanged from when the
+directory was visited in pre-order.
+.TP
+FTS_ERR
+An error indicator; the external variable
+.I errno
+contains an error number indicating the reason for the error.
+.TP
+FTS_F
+A regular file.
+.TP
+FTS_NS
+No
+.IR stat (2)
+information is available at this time (see FTS_NOSTAT); the
+contents of the
+.I statb
+field are undefined.
+.TP
+FTS_SL
+A symbolic link.
+.TP
+FTS_SLNONE
+A symbolic link with a non-existent target.
+.RE
+.TP
+statb
+.IR Stat (2)
+information for the file.
+.PP
+The
+.IR accpath
+and
+.I path
+fields are guaranteed to be NULL-terminated
+.B only
+for the file most recently returned by
+.IR ftsread .
+The
+.I name
+field is always NULL-terminated.
+To use these fields to reference any other active files may require
+that they be modified using the information contained in the
+.I pathlen
+field.
+Any such modifications should be undone before further calls to
+.I ftsread
+are attempted.
+.PP
+If all the members of the hierarchy have been returned,
+.I ftsread
+returns NULL and sets the external variable
+.I errno
+to 0.
+If an error unrelated to a file in the hierarchy occurs,
+.I ftsread
+returns NULL and sets errno appropriately.
+Otherwise, a pointer to an FTSENT structure is returned, and an
+error may or may not have occurred; see FTS_ERR above.
+.PP
+When the most recently returned file from
+.I ftsread
+is a directory being visited in pre-order,
+.I ftschildren
+returns a pointer to the first entry in a linked list (sorted by
+the comparison routine, if provided) of the directory entries
+it contains.
+The linked list is linked through the
+.I link
+field of the FTSENT structure.
+Each call to
+.I ftschildren
+recreates the list.
+Note, cycles are not detected until a directory is actually visited,
+therefore
+.I ftschildren
+will never return a structure with an
+.I info
+field set to FTS_DC.
+If the current file is not a directory being visited in pre-order,
+or if an error occurs, or the file does not contain any entries
+.I ftschildren
+returns NULL.
+If an error occurs,
+.I ftschildren
+sets errno appropriately, otherwise it sets errno to zero.
+.PP
+The pointers returned by
+.I ftsread
+and
+.I ftschildren
+point to structures which may be overwritten.
+Structures returned by
+.I ftschildren
+and
+.I ftsread
+may be overwritten after a call to
+.I ftsclose
+on the same file hierarchy.
+Otherwise, structures returned by
+.I ftschildren
+will not be overwritten until a subsequent call to either
+.I ftschildren
+or
+.I ftsread
+on the same file hierarchy.
+Structures returned by
+.I ftsread
+will not not be overwritten until a subsequent call to
+.I ftsread
+on the same file hierarchy stream, unless it represents a file of type
+directory, in which case it will not be overwritten until after a
+subsequent call to
+.I ftsread
+after it has been returned by the function
+.I ftsread
+in post-order.
+.PP
+The routine
+.I ftsset
+allows the user application to determine further processing for the
+file
+.I f
+of the stream
+.IR ftsp .
+.I Ftsset
+returns 0 on success, and -1 if an error occurs.
+.I Option
+may be set to any one of the following values.
+.TP
+FTS_AGAIN
+Re-visit the file; any file type may be re-visited.
+The next call to
+.I ftsread
+will return the referenced file.
+The
+.I stat
+and
+.I info
+fields of the structure will be reinitialized at that time,
+but no other fields will have been modified.
+This option is meaningful only for the most recently returned
+file from
+.IR ftsread .
+Normal use is for post-order directory visits, where it causes the
+directory to be re-visited (in both pre and post-order) as well as all
+of its descendants.
+.TP
+FTS_FOLLOW
+The referenced file must be a symbolic link.
+If the referenced file is the one most recently returned by
+.IR ftsread ,
+the next call to
+.I ftsread
+returns the file with the
+.I info
+and
+.I statb
+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
+.IR ftschildren ,
+the
+.I info
+and
+.I statb
+fields of the structure, when returned by
+.IR ftsread ,
+will reflect the target of the symbolic link instead of the symbolic link
+itself.
+In either case, if the target of the link is a directory, the pre-order
+return, followed by the return of all of its descendants, followed by a
+post-order return, is done.
+.TP
+FTS_SKIP
+No descendants of this file are visited.
+.PP
+Hard links between directories that do not cause cycles or symbolic
+links to symbolic links may cause files to be visited more than once,
+or directories more than twice.
+.SH ERRORS
+.I Ftsopen
+may fail and set errno for any of the errors specified for the library
+routine
+.IR malloc (3).
+.PP
+.I Ftsclose
+may fail and set errno for any of the errors specified for the library
+routine
+.IR chdir (2).
+.PP
+.I Ftsread
+and
+.I ftschildren
+may fail and set errno for any of the errors specified for the library
+routines
+.IR chdir (2),
+.IR getgroups (2),
+.IR malloc (3),
+.IR opendir (3),
+.IR readdir (3)
+and
+.IR stat (2).
+.SH SEE ALSO
+find(1), chdir(2), stat(2), qsort(3)
+.SH STANDARDS
+The
+.I fts
+utility is expected to be POSIX 1003.1 compliant.
projects / unix-history / commitdiff