ftw(3C)ftw(3C)NAMEftw(), nftw() - walk a file tree executing a function
SYNOPSIS
UNIX95
Obsolescent Interfaces
DESCRIPTION
The function recursively descends the directory hierarchy rooted in
path. For each object in the hierarchy, calls fn, passing it a pointer
to a null-terminated character string containing the name of the
object, a pointer to a structure containing information about the
object (see in stat(2)), and an integer, obj_flags. The possible val‐
ues of obj_flags, defined in the header file, are:
The object is a file.
The object is a directory.
The object is a symbolic link.
The object is a directory without read permission.
fn will not be called for any of its descendants.
failed on the object. The contents of the
structure are undefined. If the failure was
caused by a lack of permissions, the walk will
continue. For all other errors will terminate
the walk and return
Tree traversal continues until the tree is exhausted, an invocation of
fn returns a nonzero value, or an error is detected within such as an
I/O error. If the tree is exhausted, returns zero. If fn returns a
nonzero value, stops its tree traversal and returns the same value as
returned by fn. If detects an error, it returns and sets the error
type in (see errno(2)).
reports a directory before reporting any of its descendants.
and use one file descriptor for each level in the tree. The depth
argument limits the number of file descriptors that can be used. If
depth is 0 or negative, the effect is the same as if it were 1. depth
must not be greater than the number of file descriptors currently
available for use. For best performance, depth should be at least as
large as the number of levels in the tree.
is similar to except that it takes the additional argument flags, and
does not report or enter a directory which has already been visited
during the walk. The flags field is the inclusive OR of the following
values, as defined in the header file:
If set, does a physical walk. It will not follow sym‐
bolic links, but will follow hard links.
If clear, follows both symbolic and hard links.
In addition, if the environment is defined, no
object will be reported to fn more than once.
Classic HP behavior will report a file as many
times as it is referenced.
If set, will only report files in the same file system as
path. (See for one exception involving loopback
file systems (LOFS)).
If clear, will report all objects encountered in
the walk.
If set, performs a depth-first search. A directory's
contents will be reported before the directory is
reported to fn.
If clear, the directory will be reported before
its descendants.
If set, the walk does a
(see chdir(2)) to each directory before reading
its contents. At the time a directory is
reported to fn, the current working directory
will be the parent of the reported directory. A
directory must have both read and execute permis‐
sions, otherwise the directory is reported as a
object, no will be done and it will not be
entered.
If clear, will not alter the process' current
working directory, and the directory only needs
read permission to be reported as a or object.
If set and any or failure occurs, fn is called with the object
flag and the walk continues.
If clear and or fails due to lack of permissions,
fn is called with the object type. If the envi‐
ronment is defined, the walk continues. The HP
classic behavior will terminate the walk and
return For any error other than permissions, or
any error from other system calls such as
opendir(3C) or readdir(3C), does not call fn,
terminates the walk and returns
calls fn with four arguments for each object reported. The first argu‐
ment is the path name of the file, directory, or symbolic link. The
second argument is a pointer to a structure (see lstat(2)) containing
information about the object. The third argument is an integer giving
additional information as follows:
The object is a file.
The object is a directory.
The object is a directory and subdirectories have been visited.
This can be passed to fn only if is specified.
The object is a symbolic link.
This can be passed to fn only if is specified.
The object is a symbolic link that does not point to an existing
object.
This can be passed to fn only if is not speci‐
fied.
The object is a directory that cannot be read, or does not have
execute
permissions when is specified. The function fn
is not called for any of the directory's descen‐
dants.
or failed on the object. The contents of the struc‐
ture passed to fn are undefined. If the failure
occurred due to lack of permissions, is set to If
the environment is defined, the walk will always
continue after permissions errors. For classic
HP behavior, the flag must be set for the walk to
continue.
Note that this behavior differs from
The fourth argument is different for the default environment and the
environment. For the default environment, the fourth argument is a
structure For the environment, the fourth argument is a pointer to a
structure (ie: contains the following members:
The value of base is the offset from the first character in the path
name to where the base name of the object starts; this path name is
passed as the first argument to fn. The value of level indicates depth
relative to the start of the walk, where the start level has a value of
zero.
APPLICATION USAGE
can execute concurrently in separate threads. and are serialized if
the path argument is relative (i.e., does not start with '/'), or the
flag is set. For best concurrency, call with an absolute starting path
and do not set
To use the prototype, the environment must be defined. This is done by
defining the environment variable, passing the flag as a compiler
option, and adding to your path. This can be done as follows:
1.
2.
3.
is to be obsoleted at a future date.
ERRORS
If or fails, it sets (see errno(2)) to one of the following values:
[EACCES] If a component of the path prefix denies
search permission, or if read permission is
denied for path, fn returns and does not
reset
[EINVAL] The value of the depth argument is invalid.
[ENAMETOOLONG] The length of the specified path name
exceeds bytes, or the length of a component
of the path name exceeds bytes while is in
effect.
[ENOENT] path points to the name of a file that does
not exist, or points to an empty string.
[ENOTDIR] A component of path is not a directory.
[EOVERFLOW] One or more of the values in or is too
large to store in the structure to be
passed to the function pointed to by fn.
Use or instead for 32-bit applications.
In addition, if the function pointed to by fn encounters system errors,
may be set accordingly.
WARNINGS
For 32-bit applications, will be truncated to its least significant
32-bits for filesystems that use 64-bit values. Note that this will
even occur for calls because is defined as an unsigned long.
For 32-bit applications accessing large file systems, use or instead in
order to avoid overflow of the structure.
contains some recursion and it is possible for it to terminate with a
memory fault when applied to file trees which contain a large number of
directories, or a large number of files when FTW_PHYS is clear and the
UNIX95 environment is defined.
uses to allocate dynamic storage during operation (see malloc(3C)). If
it is forcibly terminated (such as if is executed by fn or an interrupt
routine), the calling function will not have a chance to free that
storage, causing it to remain allocated until the process terminates.
A safe way to handle interrupts is to store the fact that an interrupt
has occurred, and arrange to have fn return a nonzero value at its next
invocation.
If the starting path is in a loopback file system (LOFS) and is set (to
stay within the LOFS), but is clear (symbolic and hard links are fol‐
lowed), cannot determine whether a link referencing a file on the same
_device_ is really within the LOFS. It is possible with this specific
combination of factors to have some files reported to fn which should
not be.
Obsolescent Interfaces
is to be obsoleted at a future date.
AUTHOR
and were developed by AT&T and HP.
SEE ALSOstat(2), fgetpos64(3S), malloc(3C), thread_safety(5).
STANDARDS CONFORMANCEftw(3C)
