fts, fts_open, fts_read, fts_children, fts_set, fts_close — traverse a file hierarchy
#include <sys/types.h> #include <sys/stat.h> #include <fts.h>
FTS
*fts_open( |
char * const *path_argv, |
| int options, | |
int (*compar)(const FTSENT **,
const FTSENT **)); |
FTSENT
*fts_read( |
FTS *ftsp); |
FTSENT
*fts_children( |
FTS *ftsp, |
int options); |
int
fts_set( |
FTS *ftsp, |
| FTSENT *f, | |
int options); |
int
fts_close( |
FTS *ftsp); |
The fts functions are provided for traversing file
hierarchies. A simple overview is that the fts_open() function returns a "handle" on a
file hierarchy, which is then supplied to the other fts
functions. The function fts_read() returns a pointer to a structure
describing one of the files in the file hierarchy. The
function fts_children() returns
a pointer to a linked list of structures, each of which
describes one of the files contained in a directory in the
hierarchy. In general, directories are visited two
distinguishable times; in preorder (before any of their
descendants are visited) and in postorder (after all of their
descendants have been visited). Files are visited once. It is
possible to walk the hierarchy "logically" (visiting the
files that symbolic links point to) or physically (visiting
the symbolic links themselves), order the walk of the
hierarchy or prune and/or revisit portions of the
hierarchy.
Two structures are defined (and typedef'd) in the include
file <fts.h> The
first is FTS, the structure
that represents the file hierarchy itself. The second is
FTSENT, the structure that
represents a file in the file hierarchy. Normally, an
FTSENT structure is returned
for every file in the file hierarchy. In this manual page,
"file" and "FTSENT structure" are generally interchangeable.
The FTSENT structure contains
at least the following fields, which are described in greater
detail below:
typedef struct _ftsent { unsigned short fts_info; /* flags for FTSENT structure */char * fts_accpath; /* access path */char * fts_path; /* root path */short fts_pathlen; /* strlen(fts_path) */char * fts_name; /* filename */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 */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:
fts_infoOne of the following flags describing the returned
FTSENT structure and the
file it represents. With the exception of directories
without errors (FTS_D),
all of these entries are terminal, that is, they will
not be revisited, nor will any of their descendants be
visited.
FTS_DA directory being visited in preorder.
FTS_DCA directory that causes a cycle in the tree. (The
fts_cyclefield of theFTSENTstructure will be filled in as well.)FTS_DEFAULTAny
FTSENTstructure that represents a file type not explicitly described by one of the otherfts_infovalues.FTS_DNRA directory which cannot be read. This is an error return, and the
fts_errnofield will be set to indicate what caused the error.FTS_DOTA file named "." or ".." which was not specified as a filename to
fts_open() (seeFTS_SEEDOT).FTS_DPA directory being visited in postorder. The contents of the
FTSENTstructure will be unchanged from when it was returned in preorder, that is, with thefts_infofield set toFTS_D.FTS_ERRThis is an error return, and the
fts_errnofield will be set to indicate what caused the error.FTS_FA regular file.
FTS_NSA file for which no stat(2) information was available. The contents of the
fts_statpfield are undefined. This is an error return, and thefts_errnofield will be set to indicate what caused the error.FTS_NSOKA file for which no stat(2) information was requested. The contents of the
fts_statpfield are undefined.FTS_SLA symbolic link.
FTS_SLNONEA symbolic link with a nonexistent target. The contents of the
fts_statpfield reference the file characteristic information for the symbolic link itself.
fts_accpathA path for accessing the file from the current directory.
fts_pathThe path for the file relative to the root of the
traversal. This path contains the path specified to
fts_open() as a
prefix.
fts_pathlenThe length of the string referenced by fts_path.
fts_nameThe name of the file.
fts_namelenThe length of the string referenced by fts_name.
fts_levelThe depth of the traversal, numbered from −1
to N, where this file was found. The FTSENT structure representing the
parent of the starting point (or root) of the traversal
is numbered −1, and the FTSENT structure for the root itself
is numbered 0.
fts_errnoUpon return of a FTSENT structure from the
fts_children() or
fts_read() functions,
with its fts_info field set to
FTS_DNR, FTS_ERR or FTS_NS, the fts_errno field contains
the value of the external variable errno specifying the cause of the
error. Otherwise, the contents of the fts_errno field are
undefined.
fts_numberThis field is provided for the use of the application program and is not modified by the fts functions. It is initialized to 0.
fts_pointerThis field is provided for the use of the application program and is not modified by the fts functions. It is initialized to NULL.
fts_parentA pointer to the FTSENT structure referencing the file
in the hierarchy immediately above the current file,
that is, the directory of which this file is a member.
A parent structure for the initial entry point is
provided as well, however, only the fts_level, fts_number and fts_pointer fields are
guaranteed to be initialized.
fts_linkUpon return from the fts_children() function, the
fts_link field
points to the next structure in the NULL-terminated
linked list of directory members. Otherwise, the
contents of the fts_link field are
undefined.
fts_cycleIf a directory causes a cycle in the hierarchy (see
FTS_DC), either because
of a hard link between two directories, or a symbolic
link pointing to a directory, the fts_cycle field of the
structure will point to the FTSENT structure in the hierarchy
that references the same file as the current
FTSENT structure.
Otherwise, the contents of the fts_cycle field are
undefined.
fts_statpA pointer to stat(2) information for the file.
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 null-terminated only for the file most recently
returned by fts_read(). To use
these fields to reference any files represented by other
FTSENT structures will require
that the path buffer be modified using the information
contained in that 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 null-terminated.
The fts_open() function
takes a pointer to an array of character pointers naming
one or more paths which make up a logical file hierarchy to
be traversed. The array must be terminated by a NULL
pointer.
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 ORing the following
values:
FTS_COMFOLLOWThis option causes any symbolic link specified as
a root path to be followed immediately whether or not
FTS_LOGICAL is also
specified.
FTS_LOGICALThis option causes the fts routines to return
FTSENT structures for
the targets of symbolic links instead of the symbolic
links themselves. If this option is set, the only
symbolic links for which FTSENT structures are returned to
the application are those referencing nonexistent
files. Either FTS_LOGICAL or FTS_PHYSICAL must be provided to the
fts_open()
function.
FTS_NOCHDIRAs a performance optimization, the 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 FTS_NOCHDIR option turns off this
optimization, and the fts functions will not change
the current directory. Note that applications should
not themselves change their current directory and try
to access files unless FTS_NOCHDIR is specified and
absolute pathnames were provided as arguments to
fts_open().
FTS_NOSTATBy default, returned FTSENT structures reference file
characteristic information (the statp field) for each file visited.
This option relaxes that requirement as a performance
optimization, allowing the fts functions to set the
fts_info
field to FTS_NSOK and
leave the contents of the statp field undefined.
FTS_PHYSICALThis option causes the fts routines to return
FTSENT structures for
symbolic links themselves instead of the target files
they point to. If this option is set, FTSENT structures for all symbolic
links in the hierarchy are returned to the
application. Either FTS_LOGICAL or FTS_PHYSICAL must be provided to the
fts_open()
function.
FTS_SEEDOTBy default, unless they are specified as path
arguments to fts_open(), any files named "." or
".." encountered in the file hierarchy are ignored.
This option causes the fts routines to return
FTSENT structures for
them.
FTS_XDEVThis option prevents fts from descending into directories that have a different device number than the file from which the descent began.
The argument compar()
specifies a user-defined function which may be used to
order the traversal of the hierarchy. It 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. The fts_accpath, fts_path and fts_pathlen fields of the
FTSENT structures may
never be used in this
comparison. If the fts_info field is set to
FTS_NS or FTS_NSOK, the fts_statp field may not
either. If the compar()
argument is NULL, the directory traversal order is in the
order listed in path_argv for the root paths,
and in the order listed in the directory for everything
else.
The fts_read() function
returns a pointer to an FTSENT structure describing a file in the
hierarchy. Directories (that are readable and do not cause
cycles) are visited at least twice, once in preorder and
once in postorder. 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.)
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
FTSENT structure is returned,
and errno may or may not have
been set (see fts_info).
The FTSENT structures
returned by fts_read() may be
overwritten after a call to fts_close() on the same file hierarchy
stream, or, after a call to 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 fts_read() after the
FTSENT structure has been
returned by the function fts_read() in postorder.
The fts_children()
function returns a pointer to an FTSENT structure describing the first
entry in a NULL-terminated linked list of the files in the
directory represented by the FTSENT structure most recently returned
by fts_read(). The list is
linked through the fts_link field of the
FTSENT structure, and is
ordered by the user-specified comparison function, if any.
Repeated calls to fts_children() will recreate this linked
list.
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(), that
is, the arguments specified to fts_open(). Otherwise, if the
FTSENT structure most
recently returned by fts_read() is not a directory being
visited in preorder, 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 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_NAMEONLYOnly 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 fts_name and fts_namelen fields.
The function fts_set()
allows the user application to determine further processing
for the file f of
the stream ftsp.
The fts_set() function
returns 0 on success, and −1 if an error occurs.
Option must be set to one of
the following values:
FTS_AGAINRevisit the file; any file type may be revisited.
The next call to fts_read() will return the
referenced file. The fts_stat and 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 fts_read(). Normal
use is for postorder directory visits, where it
causes the directory to be revisited (in both
preorder and postorder) as well as all of its
descendants.
FTS_FOLLOWThe referenced file must be a symbolic link. If
the referenced file is the one most recently returned
by fts_read(), the next
call to fts_read()
returns the file with the fts_info and 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
fts_children(), the
fts_info and
fts_statp
fields of the structure, when returned by
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
fts_info
field will be set to FTS_SLNONE.
If the target of the link is a directory, the preorder return, followed by the return of all of its descendants, followed by a postorder return, is done.
FTS_SKIPNo descendants of this file are visited. The file
may be one of those most recently returned by either
fts_children() or
fts_read().
The function fts_open() may
fail and set errno for any of
the errors specified for open(2) and malloc(3).
The function fts_close() may
fail and set errno for any of
the errors specified for chdir(2) and close(2).
The functions fts_read() and
fts_children() may fail and set
errno for any of the errors
specified for 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:
The options were invalid.
This page is part of release 3.52 of the Linux man-pages project. A
description of the project, and information about reporting
bugs, can be found at
http://www.kernel.org/doc/man−pages/.
|
$NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $ Copyright (c) 1989, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. %%%LICENSE_START(BSD_4_CLAUSE_UCB) Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgement: This product includes software developed by the University of California, Berkeley and its contributors. 4. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. %%%LICENSE_END (#)fts.3 8.5 (Berkeley) 4/16/94 2007-12-08, mtk, Converted from mdoc to man macros |