mirror of https://github.com/mkerrisk/man-pages
254 lines
7.2 KiB
Plaintext
254 lines
7.2 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "NFTW" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" nftw
|
|
.SH NAME
|
|
nftw \- walk a file tree
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <ftw.h>
|
|
.br
|
|
.sp
|
|
int nftw(const char *\fP\fIpath\fP\fB, int (*\fP\fIfn\fP\fB)(const
|
|
char *,
|
|
.br
|
|
\ \ \ \ \ \ const struct stat *, int, struct FTW *), int\fP \fIdepth\fP\fB,
|
|
int\fP
|
|
\fIflags\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fInftw\fP() function shall recursively descend the directory
|
|
hierarchy rooted in \fIpath\fP. The \fInftw\fP() function
|
|
has a similar effect to \fIftw\fP() except that it takes an additional
|
|
argument \fIflags\fP,
|
|
which is a bitwise-inclusive OR of zero or more of the following flags:
|
|
.TP 7
|
|
FTW_CHDIR
|
|
If set, \fInftw\fP() shall change the current working directory to
|
|
each directory as it reports files in that directory. If
|
|
clear, \fInftw\fP() shall not change the current working directory.
|
|
.TP 7
|
|
FTW_DEPTH
|
|
If set, \fInftw\fP() shall report all files in a directory before
|
|
reporting the directory itself. If clear, \fInftw\fP()
|
|
shall report any directory before reporting the files in that directory.
|
|
.TP 7
|
|
FTW_MOUNT
|
|
If set, \fInftw\fP() shall only report files in the same file system
|
|
as \fIpath\fP. If clear, \fInftw\fP() shall report all
|
|
files encountered during the walk.
|
|
.TP 7
|
|
FTW_PHYS
|
|
If set, \fInftw\fP() shall perform a physical walk and shall not follow
|
|
symbolic links.
|
|
.sp
|
|
.LP
|
|
If FTW_PHYS is clear and FTW_DEPTH is set, \fInftw\fP() shall follow
|
|
links instead of reporting them, but shall not report any
|
|
directory that would be a descendant of itself. If FTW_PHYS is clear
|
|
and FTW_DEPTH is clear, \fInftw\fP() shall follow links
|
|
instead of reporting them, but shall not report the contents of any
|
|
directory that would be a descendant of itself.
|
|
.LP
|
|
At each file it encounters, \fInftw\fP() shall call the user-supplied
|
|
function \fIfn\fP with four arguments:
|
|
.IP " *" 3
|
|
The first argument is the pathname of the object.
|
|
.LP
|
|
.IP " *" 3
|
|
The second argument is a pointer to the \fBstat\fP buffer containing
|
|
information on the object.
|
|
.LP
|
|
.IP " *" 3
|
|
The third argument is an integer giving additional information. Its
|
|
value is one of the following:
|
|
.TP 7
|
|
FTW_F
|
|
.RS
|
|
The object is a file.
|
|
.RE
|
|
.TP 7
|
|
FTW_D
|
|
.RS
|
|
The object is a directory.
|
|
.RE
|
|
.TP 7
|
|
FTW_DP
|
|
.RS
|
|
The object is a directory and subdirectories have been visited. (This
|
|
condition shall only occur if the FTW_DEPTH flag is
|
|
included in \fIflags\fP.)
|
|
.RE
|
|
.TP 7
|
|
FTW_SL
|
|
.RS
|
|
The object is a symbolic link. (This condition shall only occur if
|
|
the FTW_PHYS flag is included in \fIflags\fP.)
|
|
.RE
|
|
.TP 7
|
|
FTW_SLN
|
|
.RS
|
|
The object is a symbolic link that does not name an existing file.
|
|
(This condition shall only occur if the FTW_PHYS flag is not
|
|
included in \fIflags\fP.)
|
|
.RE
|
|
.TP 7
|
|
FTW_DNR
|
|
.RS
|
|
The object is a directory that cannot be read. The \fIfn\fP function
|
|
shall not be called for any of its descendants.
|
|
.RE
|
|
.TP 7
|
|
FTW_NS
|
|
.RS
|
|
The \fIstat\fP() function failed on the object because of lack of
|
|
appropriate permission.
|
|
The \fBstat\fP buffer passed to \fIfn\fP is undefined. Failure of
|
|
\fIstat\fP() for any
|
|
other reason is considered an error and \fInftw\fP() shall return
|
|
-1.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
.IP " *" 3
|
|
The fourth argument is a pointer to an \fBFTW\fP structure. The value
|
|
of \fBbase\fP is the offset of the object's filename in
|
|
the pathname passed as the first argument to \fIfn\fP. The value of
|
|
\fBlevel\fP indicates depth relative to the root of the walk,
|
|
where the root level is 0.
|
|
.LP
|
|
.LP
|
|
The results are unspecified if the application-supplied \fIfn\fP function
|
|
does not preserve the current working directory.
|
|
.LP
|
|
The argument \fIdepth\fP sets the maximum number of file descriptors
|
|
that shall be used by \fInftw\fP() while traversing the
|
|
file tree. At most one file descriptor shall be used for each directory
|
|
level.
|
|
.LP
|
|
The \fInftw\fP() function need not be reentrant. A function that is
|
|
not required to be reentrant is not required to be
|
|
thread-safe.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
The \fInftw\fP() function shall continue until the first of the following
|
|
conditions occurs:
|
|
.IP " *" 3
|
|
An invocation of \fIfn\fP shall return a non-zero value, in which
|
|
case \fInftw\fP() shall return that value.
|
|
.LP
|
|
.IP " *" 3
|
|
The \fInftw\fP() function detects an error other than [EACCES] (see
|
|
FTW_DNR and FTW_NS above), in which case \fInftw\fP()
|
|
shall return -1 and set \fIerrno\fP to indicate the error.
|
|
.LP
|
|
.IP " *" 3
|
|
The tree is exhausted, in which case \fInftw\fP() shall return 0.
|
|
.LP
|
|
.SH ERRORS
|
|
.LP
|
|
The \fInftw\fP() function shall fail if:
|
|
.TP 7
|
|
.B EACCES
|
|
Search permission is denied for any component of \fIpath\fP or read
|
|
permission is denied for \fIpath\fP, or \fIfn\fP returns
|
|
-1 and does not reset \fIerrno\fP.
|
|
.TP 7
|
|
.B ELOOP
|
|
A loop exists in symbolic links encountered during resolution of the
|
|
\fIpath\fP argument.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname
|
|
component is longer than {NAME_MAX}.
|
|
.TP 7
|
|
.B ENOENT
|
|
A component of \fIpath\fP does not name an existing file or \fIpath\fP
|
|
is an empty string.
|
|
.TP 7
|
|
.B ENOTDIR
|
|
A component of \fIpath\fP is not a directory.
|
|
.TP 7
|
|
.B EOVERFLOW
|
|
A field in the \fBstat\fP structure cannot be represented correctly
|
|
in the current programming environment for one or more
|
|
files found in the file hierarchy.
|
|
.sp
|
|
.LP
|
|
The \fInftw\fP() function may fail if:
|
|
.TP 7
|
|
.B ELOOP
|
|
More than {SYMLOOP_MAX} symbolic links were encountered during resolution
|
|
of the \fIpath\fP argument.
|
|
.TP 7
|
|
.B EMFILE
|
|
{OPEN_MAX} file descriptors are currently open in the calling process.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
Pathname resolution of a symbolic link produced an intermediate result
|
|
whose length exceeds {PATH_MAX}.
|
|
.TP 7
|
|
.B ENFILE
|
|
Too many files are currently open in the system.
|
|
.sp
|
|
.LP
|
|
In addition, \fIerrno\fP may be set if the function pointed to by
|
|
\fIfn\fP causes \fIerrno\fP to be set.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
The following example walks the \fB/tmp\fP directory and its subdirectories,
|
|
calling the \fInftw\fP() function for every
|
|
directory entry, to a maximum of 5 levels deep.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <ftw.h>
|
|
\&...
|
|
int nftwfunc(const char *, const struct stat *, int, struct FTW *);
|
|
.sp
|
|
|
|
int nftwfunc(const char *filename, const struct stat *statptr,
|
|
int fileflags, struct FTW *pfwt)
|
|
{
|
|
return 0;
|
|
}
|
|
\&...
|
|
char *startpath = "/tmp";
|
|
int depth = 5;
|
|
int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
|
|
int ret;
|
|
.sp
|
|
|
|
ret = nftw(startpath, nftwfunc, depth, flags);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIlstat\fP() , \fIopendir\fP() , \fIreaddir\fP() , \fIstat\fP() ,
|
|
the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<ftw.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|