|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH NFTW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
nftw
|
|
Packit |
7cfc04 |
\(em walk a file tree
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
#include <ftw.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
int nftw(const char *\fIpath\fP, int (*\fIfn\fP)(const char *,
|
|
Packit |
7cfc04 |
const struct stat *, int, struct FTW *), int \fIfd_limit\fP, int \fIflags\fP);
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
function shall recursively descend the directory hierarchy rooted in
|
|
Packit |
7cfc04 |
.IR path .
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
function has a similar effect to
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
except that it takes an additional argument
|
|
Packit |
7cfc04 |
.IR flags ,
|
|
Packit |
7cfc04 |
which is a bitwise-inclusive OR of zero or more of the following flags:
|
|
Packit |
7cfc04 |
.IP FTW_CHDIR 12
|
|
Packit |
7cfc04 |
If set,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall change the current working directory to each directory as it
|
|
Packit |
7cfc04 |
reports files in that directory. If clear,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall not change the current working directory.
|
|
Packit |
7cfc04 |
.IP FTW_DEPTH 12
|
|
Packit |
7cfc04 |
If set,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall report all files in a directory before reporting the directory
|
|
Packit |
7cfc04 |
itself. If clear,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall report any directory before reporting the files in that directory.
|
|
Packit |
7cfc04 |
.IP FTW_MOUNT 12
|
|
Packit |
7cfc04 |
If set,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall only report files in the same file system as
|
|
Packit |
7cfc04 |
.IR path .
|
|
Packit |
7cfc04 |
If clear,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall report all files encountered during the walk.
|
|
Packit |
7cfc04 |
.IP FTW_PHYS 12
|
|
Packit |
7cfc04 |
If set,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall perform a physical walk and shall not follow symbolic links.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If FTW_PHYS is clear and FTW_DEPTH is set,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall follow links instead of reporting them, but shall not report any
|
|
Packit |
7cfc04 |
directory that would be a descendant of itself. If FTW_PHYS is clear
|
|
Packit |
7cfc04 |
and FTW_DEPTH is clear,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall follow links instead of reporting them, but shall not report the
|
|
Packit |
7cfc04 |
contents of any directory that would be a descendant of itself.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
At each file it encounters,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall call the user-supplied function
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
with four arguments:
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
The first argument is the pathname of the object.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
The second argument is a pointer to the
|
|
Packit |
7cfc04 |
.BR stat
|
|
Packit |
7cfc04 |
buffer containing information on the object, filled in as if
|
|
Packit |
7cfc04 |
\fIfstatat\fR(),
|
|
Packit |
7cfc04 |
\fIstat\fR(),
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
\fIlstat\fR()
|
|
Packit |
7cfc04 |
had been called to retrieve the information.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
The third argument is an integer giving additional information. Its
|
|
Packit |
7cfc04 |
value is one of the following:
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.IP FTW_D 10
|
|
Packit |
7cfc04 |
The object is a directory.
|
|
Packit |
7cfc04 |
.IP FTW_DNR 10
|
|
Packit |
7cfc04 |
The object is a directory that cannot be read. The
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
function shall not be called for any of its descendants.
|
|
Packit |
7cfc04 |
.IP FTW_DP 10
|
|
Packit |
7cfc04 |
The object is a directory and subdirectories have been visited. (This
|
|
Packit |
7cfc04 |
condition shall only occur if the FTW_DEPTH flag is included in
|
|
Packit |
7cfc04 |
.IR flags .)
|
|
Packit |
7cfc04 |
.IP FTW_F 10
|
|
Packit |
7cfc04 |
The object is a non-directory file.
|
|
Packit |
7cfc04 |
.IP FTW_NS 10
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIstat\fR()
|
|
Packit |
7cfc04 |
function failed on the object because of lack of appropriate
|
|
Packit |
7cfc04 |
permission. The
|
|
Packit |
7cfc04 |
.BR stat
|
|
Packit |
7cfc04 |
buffer passed to
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
is undefined. Failure of
|
|
Packit |
7cfc04 |
\fIstat\fR()
|
|
Packit |
7cfc04 |
for any other reason is considered an error and
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall return \(mi1.
|
|
Packit |
7cfc04 |
.IP FTW_SL 10
|
|
Packit |
7cfc04 |
The object is a symbolic link. (This condition shall only occur if the
|
|
Packit |
7cfc04 |
FTW_PHYS flag is included in
|
|
Packit |
7cfc04 |
.IR flags .)
|
|
Packit |
7cfc04 |
.IP FTW_SLN 10
|
|
Packit |
7cfc04 |
The object is a symbolic link that does not name an existing file.
|
|
Packit |
7cfc04 |
(This condition shall only occur if the FTW_PHYS flag is not included in
|
|
Packit |
7cfc04 |
.IR flags .)
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
The fourth argument is a pointer to an
|
|
Packit |
7cfc04 |
.BR FTW
|
|
Packit |
7cfc04 |
structure.
|
|
Packit |
7cfc04 |
The value of
|
|
Packit |
7cfc04 |
.BR base
|
|
Packit |
7cfc04 |
is the offset of the object's filename in the pathname passed as the
|
|
Packit |
7cfc04 |
first argument to
|
|
Packit |
7cfc04 |
.IR fn .
|
|
Packit |
7cfc04 |
The value of
|
|
Packit |
7cfc04 |
.BR level
|
|
Packit |
7cfc04 |
indicates depth relative to the root of the walk, where the root level
|
|
Packit |
7cfc04 |
is 0.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The results are unspecified if the application-supplied
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
function does not preserve the current working directory.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.IR fd_limit
|
|
Packit |
7cfc04 |
sets the maximum number of file descriptors that shall be used by
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
while traversing the file tree. At most one file descriptor shall be
|
|
Packit |
7cfc04 |
used for each directory level.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
function need not be thread-safe.
|
|
Packit |
7cfc04 |
.SH "RETURN VALUE"
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
function shall continue until the first of the following conditions
|
|
Packit |
7cfc04 |
occurs:
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
An invocation of
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
shall return a non-zero value, in which case
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall return that value.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
function detects an error other than
|
|
Packit |
7cfc04 |
.BR [EACCES]
|
|
Packit |
7cfc04 |
(see FTW_DNR and FTW_NS above),
|
|
Packit |
7cfc04 |
in which case
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall return \(mi1 and set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to indicate the error.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
The tree is exhausted, in which case
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
shall return 0.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
function shall fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EACCES
|
|
Packit |
7cfc04 |
Search permission is denied for any component of
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
or read permission is denied for
|
|
Packit |
7cfc04 |
.IR path ,
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
returns \(mi1 and does not reset
|
|
Packit |
7cfc04 |
.IR errno .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ELOOP
|
|
Packit |
7cfc04 |
A loop exists in symbolic links encountered during resolution of the
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENAMETOOLONG
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
The length of a component of a pathname is longer than
|
|
Packit |
7cfc04 |
{NAME_MAX}.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENOENT
|
|
Packit |
7cfc04 |
A component of
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
does not name an existing file or
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
is an empty string.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENOTDIR
|
|
Packit |
7cfc04 |
A component of
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
names an existing file that is neither a directory nor a symbolic link
|
|
Packit |
7cfc04 |
to a directory.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EOVERFLOW
|
|
Packit |
7cfc04 |
A field in the
|
|
Packit |
7cfc04 |
.BR stat
|
|
Packit |
7cfc04 |
structure cannot be represented correctly in the current programming
|
|
Packit |
7cfc04 |
environment for one or more files found in the file hierarchy.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
function may fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ELOOP
|
|
Packit |
7cfc04 |
More than
|
|
Packit |
7cfc04 |
{SYMLOOP_MAX}
|
|
Packit |
7cfc04 |
symbolic links were encountered during resolution of the
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EMFILE
|
|
Packit |
7cfc04 |
All file descriptors available to the process are currently open.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENAMETOOLONG
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
The length of a pathname exceeds
|
|
Packit |
7cfc04 |
{PATH_MAX},
|
|
Packit |
7cfc04 |
or pathname resolution of a symbolic link produced an intermediate
|
|
Packit |
7cfc04 |
result with a length that exceeds
|
|
Packit |
7cfc04 |
{PATH_MAX}.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENFILE
|
|
Packit |
7cfc04 |
Too many files are currently open in the system.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
In addition,
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
may be set if the function pointed to by
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
causes
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to be set.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
The following program traverses the directory tree under the path named
|
|
Packit |
7cfc04 |
in its first command-line argument, or under the current directory if
|
|
Packit |
7cfc04 |
no argument is supplied. It displays various information about each
|
|
Packit |
7cfc04 |
file. The second command-line argument can be used to specify characters
|
|
Packit |
7cfc04 |
that control the value assigned to the
|
|
Packit |
7cfc04 |
.IR flags
|
|
Packit |
7cfc04 |
argument when calling
|
|
Packit |
7cfc04 |
\fInftw\fR().
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
#include <ftw.h>
|
|
Packit |
7cfc04 |
#include <stdio.h>
|
|
Packit |
7cfc04 |
#include <stdlib.h>
|
|
Packit |
7cfc04 |
#include <string.h>
|
|
Packit |
7cfc04 |
#include <stdint.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
static int
|
|
Packit |
7cfc04 |
display_info(const char *fpath, const struct stat *sb,
|
|
Packit |
7cfc04 |
int tflag, struct FTW *ftwbuf)
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
printf("%-3s %2d %7jd %-40s %d %s\en",
|
|
Packit |
7cfc04 |
(tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" :
|
|
Packit |
7cfc04 |
(tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ?
|
|
Packit |
7cfc04 |
(S_ISBLK(sb->st_mode) ? "f b" :
|
|
Packit |
7cfc04 |
S_ISCHR(sb->st_mode) ? "f c" :
|
|
Packit |
7cfc04 |
S_ISFIFO(sb->st_mode) ? "f p" :
|
|
Packit |
7cfc04 |
S_ISREG(sb->st_mode) ? "f r" :
|
|
Packit |
7cfc04 |
S_ISSOCK(sb->st_mode) ? "f s" : "f ?") :
|
|
Packit |
7cfc04 |
(tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" :
|
|
Packit |
7cfc04 |
(tflag == FTW_SLN) ? "sln" : "?",
|
|
Packit |
7cfc04 |
ftwbuf->level, (intmax_t) sb->st_size,
|
|
Packit |
7cfc04 |
fpath, ftwbuf->base, fpath + ftwbuf->base);
|
|
Packit |
7cfc04 |
return 0; /* To tell nftw() to continue */
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
int
|
|
Packit |
7cfc04 |
main(int argc, char *argv[])
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
int flags = 0;
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
if (argc > 2 && strchr(argv[2], 'd') != NULL)
|
|
Packit |
7cfc04 |
flags |= FTW_DEPTH;
|
|
Packit |
7cfc04 |
if (argc > 2 && strchr(argv[2], 'p') != NULL)
|
|
Packit |
7cfc04 |
flags |= FTW_PHYS;
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) == -1)
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
perror("nftw");
|
|
Packit |
7cfc04 |
exit(EXIT_FAILURE);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
exit(EXIT_SUCCESS);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
function may allocate dynamic storage during its operation. If
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
is forcibly terminated, such as by
|
|
Packit |
7cfc04 |
\fIlongjmp\fR()
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
\fIsiglongjmp\fR()
|
|
Packit |
7cfc04 |
being executed by the function pointed to by
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
or an interrupt routine,
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
does not have a chance to free that storage, so it remains permanently
|
|
Packit |
7cfc04 |
allocated. A safe way to handle interrupts is to store the fact that an
|
|
Packit |
7cfc04 |
interrupt has occurred, and arrange to have the function pointed to by
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
return a non-zero value at its next invocation.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "\fIfdopendir\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfstatat\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIreaddir\fR\^(\|)"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fB<ftw.h>\fP"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|