CONTENTS

LIBRARY

SYNOPSIS

DESCRIPTION

Two structures are defined (and typedef’d) in the include file
.In fts.h . The first is
.Vt FTS , the structure that represents the file hierarchy itself. The second is
.Vt FTSENT , the structure that represents a file in the file hierarchy. Normally, an
.Vt FTSENT structure is returned for every file in the file hierarchy. In this manual page, "file" and "Vt FTSENT structure" are generally interchangeable.

The
.Vt FTS structure contains space for a single pointer, which may be used to store application data or per-hierarchy state. The fts_set_clientptr and fts_get_clientptr functions may be used to set and retrieve this pointer. This is likely to be useful only when accessed from the sort comparison function, which can determine the original
.Vt FTS stream of its arguments using the fts_get_stream function. The two get functions are also available as macros of the same name.

The
.Vt FTSENT structure contains at least the following fields, which are described in greater detail below:
typedef struct _ftsent {
u_short fts_info;/* flags for FTSENT structure */
char *fts_accpath; /* access path */
char *fts_path; /* root path */
u_short fts_pathlen; /* strlen(fts_path) */
char *fts_name; /* file name */
u_short fts_namelen; /* strlen(fts_name) */
short fts_level; /* depth (-1 to N) */
int fts_errno; /* file errno */
long fts_number; /* local numeric value */
void *fts_pointer; /* local address value */
int64_t fts_bignum; /* local 64-bit numeric value */
struct ftsent *fts_parent; /* parent directory */
struct ftsent *fts_link; /* next file structure */
struct ftsent *fts_cycle; /* cycle structure */
struct stat *fts_statp; /* stat(2) information */
} FTSENT;

These fields are defined as follows:

A single buffer is used for all of the paths of all of the files in the file hierarchy. Therefore, the fts_path and fts_accpath fields are guaranteed to be NUL -terminated only for the file most recently returned by fts_read. To use these fields to reference any files represented by other
.Vt FTSENT structures will require that the path buffer be modified using the information contained in that
.Vt FTSENT structure’s fts_pathlen field. Any such modifications should be undone before further calls to fts_read are attempted. The fts_name field is always NUL -terminated.

There are a number of options, at least one of which (either FTS_LOGICAL or FTS_PHYSICAL) must be specified. The options are selected by or ’ing the following values:

If all the members of the hierarchy have been returned, fts_read returns NULL and sets the external variable errno to 0. If an error unrelated to a file in the hierarchy occurs, fts_read returns NULL and sets errno appropriately. If an error related to a returned file occurs, a pointer to an
.Vt FTSENT structure is returned, and errno may or may not have been set (see fts_info).

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

The
.Vt FTSENT structures returned by fts_children may be overwritten after a call to fts_children, fts_close or fts_read on the same file hierarchy stream.

Option may be set to the following value:

FTS_SET

FTS_CLOSE

ERRORS

The function fts_close may fail and set errno for any of the errors specified for the library functions chdir(2) and close(2).

The functions fts_read and fts_children may fail and set errno for any of the errors specified for the library functions chdir(2), malloc(3), opendir(3), readdir(3) and stat(2).

In addition, fts_children, fts_open and fts_set may fail and set errno as follows:

SEE ALSO

HISTORY