#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;

The ftsopen routine returns a pointer to a file hierarchy rooted at path . The options specified are formed by or 'ing one or more of the following values:

FTS_LOGICAL This option causes ftsread to use the function 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 must be provided to the ftsopen routine.

FTS_MULTIPLE 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.

FTS_NOCHDIR As a performance optimization, 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 ftsopen .

FTS_NOSTAT By default, ftsread and ftschildren provide file characteristic information (the statb field) for each file they return. This option relaxes that requirement; the contents of the statb field may be undefined, and the info field may be set to FTS_NS.

FTS_PHYSICAL This option causes ftsread to use the function 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 must be provided to the ftsopen routine.

FTS_SEEDOT This option causes the routine ftsread to return structures for the directory entries ``.'' and ``..''. By default they are ignored unless specified as an argument to ftsopen .

The argument compar specifies a user-defined routine which is used to order the traversal of directories. 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 accpath and path fields of the FTSENT structures may not be used in this comparison. If the compar argument is NULL the traversal order is undefined.

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.

The ftsclose routine closes a file hierarchy stream and changes the current directory to the directory ftsopen was called from. Ftsclose returns 0 on success, and -1 if an error occurs.

Each call to the 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.

The FTSENT structure contains at least the following fields:

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;

The fields are as follows:

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 local and level fields are guaranteed to be initialized.

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 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 ftschildren routine, the 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.

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.

accpath A path that can be used to access the file.

path The path for the file relative to the root of the traversal.

name The basename of the file.

pathlen The length of the string referenced by path .

namelen The length of the string referenced by name .

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.

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).

statb Stat (2) information for the file.

The accpath and path fields are guaranteed to be NULL-terminated only for the file most recently returned by ftsread . The 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 pathlen field. Any such modifications should be undone before further calls to ftsread are attempted.

If all the members of the hierarchy have been returned, ftsread returns NULL and sets the external variable errno to 0. If an error unrelated to a file in the hierarchy occurs, 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.

When the most recently returned file from ftsread is a directory being visited in pre-order, 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 link field of the FTSENT structure. Each call to ftschildren recreates the list. Note, cycles are not detected until a directory is actually visited, therefore ftschildren will never return a structure with an 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 ftschildren returns NULL. If an error occurs, ftschildren sets errno appropriately, otherwise it sets errno to zero.

The pointers returned by ftsread and ftschildren point to structures which may be overwritten. Structures returned by ftschildren and ftsread may be overwritten after a call to ftsclose on the same file hierarchy. Otherwise, structures returned by ftschildren will not be overwritten until a subsequent call to either ftschildren or ftsread on the same file hierarchy. Structures returned by ftsread will not not be overwritten until a subsequent call to 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 ftsread after it has been returned by the function ftsread in post-order.

The routine ftsset allows the user application to determine further processing for the file f of the stream ftsp . Ftsset returns 0 on success, and -1 if an error occurs. Option may be set to any one of the following values.

FTS_AGAIN Re-visit the file; any file type may be re-visited. The next call to ftsread will return the referenced file. The stat and 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 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.

FTS_FOLLOW The referenced file must be a symbolic link. If the referenced file is the one most recently returned by ftsread , the next call to ftsread returns the file with the info and 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 ftschildren , the info and statb fields of the structure, when returned by 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.

FTS_SKIP No descendants of this file are visited.

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.

Ftsclose may fail and set errno for any of the errors specified for the library routine chdir (2).

Ftsread and ftschildren may fail and set errno for any of the errors specified for the library routines chdir (2), getgroups (2), malloc (3), opendir (3), readdir (3) and stat (2).