fts.3

早期freebsd实现

be provided to the
.Fn fts_open
function.
.It Dv FTS_NOCHDIR
As a performance optimization, the
.Nm fts
functions change directories as they walk the file hierarchy.
This has the side-effect that an application cannot rely on being
in any particular directory during the traversal.
The
.Dv FTS_NOCHDIR
option turns off this optimization, and the
.Nm fts
functions will not change the current directory.
Note that applications should not themselves change their current directory
and try to access files unless
.Dv FTS_NOCHDIR
is specified and absolute
pathnames were provided as arguments to
.Fn fts_open .
.It Dv FTS_NOSTAT
By default, returned
.Fa FTSENT
structures reference file characteristic information (the
.Fa statp
field) for each file visited.
This option relaxes that requirement as a performance optimization,
allowing the
.Nm fts
functions to set the
.Fa fts_info
field to
.Dv FTS_NSOK
and leave the contents of the
.Fa statp
field undefined.
.It Dv FTS_PHYSICAL
This option causes the
.Nm fts
routines to return
.Fa FTSENT
structures for symbolic links themselves instead
of the target files they point to.
If this option is set,
.Fa FTSENT
structures for all symbolic links in the
hierarchy are returned to the application.
Either
.Dv FTS_LOGICAL
or
.Dv FTS_PHYSICAL
.Em must
be provided to the
.Fn fts_open
function.
.It Dv FTS_SEEDOT
By default, unless they are specified as path arguments to
.Fn fts_open ,
any files named
.Ql \&.
or
.Ql ..
encountered in the file hierarchy are ignored.
This option causes the
.Nm fts
routines to return
.Fa FTSENT
structures for them.
.It Dv FTS_XDEV
This option prevents
.Nm fts
from descending into directories that have a different device number
than the file from which the descent began.
.El
.Pp
The argument
.Fn compar
specifies a user-defined function which may be used to order the traversal
of the hierarchy.
It
takes two pointers to pointers to
.Fa 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.
The
.Fa fts_accpath ,
.Fa fts_path
and
.Fa fts_pathlen
fields of the
.Fa FTSENT
structures may
.Em never
be used in this comparison.
If the 
.Fa fts_info
field is set to
.Dv FTS_NS
or
.Dv FTS_NSOK ,
the
.Fa fts_statp
field may not either.
If the
.Fn compar
argument is
.Dv NULL ,
the directory traversal order is in the order listed in
.Fa path_argv
for the root paths, and in the order listed in the directory for
everything else.
.Sh FTS_READ
The
.Fn fts_read
function returns a pointer to an
.Fa FTSENT
structure describing a file in
the hierarchy.
Directories (that are readable and do not cause cycles) are visited at
least twice, once in pre-order and once in post-order.
All other files are visited at least once.
(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.)
.Pp
If all the members of the hierarchy have been returned,
.Fn fts_read
returns
.Dv NULL
and sets the external variable
.Va errno
to 0.
If an error unrelated to a file in the hierarchy occurs,
.Fn fts_read
returns
.Dv NULL
and sets
.Va errno
appropriately.
If an error related to a returned file occurs, a pointer to an
.Fa FTSENT
structure is returned, and
.Va errno
may or may not have been set (see
.Fa fts_info ) .
.Pp
The
.Fa FTSENT
structures returned by
.Fn fts_read
may be overwritten after a call to
.Fn fts_close
on the same file hierarchy stream, or, after a call to
.Fn fts_read
on the same file hierarchy stream unless they represent a file of type
directory, in which case they will not be overwritten until after a call to
.Fn fts_read
after the
.Fa FTSENT
structure has been returned by the function
.Fn fts_read
in post-order.
.Sh FTS_CHILDREN
The
.Fn fts_children
function returns a pointer to an
.Fa FTSENT
structure describing the first entry in a NULL-terminated linked list of
the files in the directory represented by the
.Fa FTSENT
structure most recently returned by
.Fn fts_read .
The list is linked through the
.Fa fts_link
field of the
.Fa FTSENT
structure, and is ordered by the user-specified comparison function, if any.
Repeated calls to
.Fn fts_children
will recreate this linked list.
.Pp
As a special case, if
.Fn fts_read
has not yet been called for a hierarchy,
.Fn fts_children
will return a pointer to the files in the logical directory specified to
.Fn fts_open ,
i.e. the arguments specified to
.Fn fts_open .
Otherwise, if the
.Fa FTSENT
structure most recently returned by
.Fn fts_read
is not a directory being visited in pre-order,
or the directory does not contain any files,
.Fn fts_children
returns
.Dv NULL
and sets
.Va errno
to zero.
If an error occurs,
.Fn fts_children
returns
.Dv NULL
and sets
.Va errno
appropriately.
.Pp
The
.Fa FTSENT
structures returned by
.Fn fts_children
may be overwritten after a call to
.Fn fts_children ,
.Fn fts_close
or
.Fn fts_read
on the same file hierarchy stream.
.Pp
.Em Option
may be set to the following value:
.Bl -tag -width FTS_NAMEONLY
.It Dv FTS_NAMEONLY
Only the names of the files are needed.
The contents of all the fields in the returned linked list of structures
are undefined with the exception of the
.Fa fts_name
and
.Fa fts_namelen
fields.
.El
.Sh FTS_SET
The function
.Fn fts_set
allows the user application to determine further processing for the
file
.Fa f
of the stream
.Fa ftsp .
The
.Fn fts_set
function
returns 0 on success, and \-1 if an error occurs.
.Em Option
must be set to one of the following values:
.Bl -tag -width FTS_PHYSICAL
.It Dv FTS_AGAIN
Re-visit the file; any file type may be re-visited.
The next call to
.Fn fts_read
will return the referenced file.
The
.Fa fts_stat
and
.Fa fts_info
fields of the structure will be reinitialized at that time,
but no other fields will have been changed.
This option is meaningful only for the most recently returned
file from
.Fn fts_read .
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.
.It Dv FTS_FOLLOW
The referenced file must be a symbolic link.
If the referenced file is the one most recently returned by
.Fn fts_read ,
the next call to
.Fn fts_read
returns the file with the
.Fa fts_info
and
.Fa 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
.Fn fts_children ,
the
.Fa fts_info
and
.Fa fts_statp
fields of the structure, when returned by
.Fn 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
.Fa fts_info
field will be set to
.Dv FTS_SLNONE .
.Pp
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.
.It Dv FTS_SKIP
No descendants of this file are visited.
The file may be one of those most recently returned by either
.Fn fts_children
or
.Fn fts_read .
.El
.Sh FTS_CLOSE
The
.Fn fts_close
function closes a file hierarchy stream
.Fa ftsp
and restores the current directory to the directory from which
.Fn fts_open
was called to open
.Fa ftsp .
The
.Fn fts_close
function
returns 0 on success, and \-1 if an error occurs.
.Sh ERRORS
The function
.Fn fts_open
may fail and set
.Va errno
for any of the errors specified for the library functions
.Xr open 2
and
.Xr malloc 3 .
.Pp
The function
.Fn fts_close
may fail and set
.Va errno
for any of the errors specified for the library functions
.Xr chdir 2
and
.Xr close 2 .
.Pp
The functions
.Fn fts_read
and
.Fn fts_children
may fail and set
.Va errno
for any of the errors specified for the library functions
.Xr chdir 2 ,
.Xr malloc 3 ,
.Xr opendir 3 ,
.Xr readdir 3
and
.Xr stat 2 .
.Pp
In addition,
.Fn fts_children ,
.Fn fts_open
and
.Fn fts_set
may fail and set
.Va errno
as follows:
.Bl -tag -width Er
.It Bq Er EINVAL
The options were invalid.
.El
.Sh SEE ALSO
.Xr find 1 ,
.Xr chdir 2 ,
.Xr stat 2 ,
.Xr qsort 3
.Sh STANDARDS
The
.Nm fts
utility is expected to be included in a future
.St -p1003.1-88
revision.