|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH FTW "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 |
ftw
|
|
Packit |
7cfc04 |
\(em traverse (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 ftw(const char *\fIpath\fP, int (*\fIfn\fP)(const char *,
|
|
Packit |
7cfc04 |
const struct stat *\fIptr\fP, int \fIflag\fP), int \fIndirs\fP);
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
function shall recursively descend the directory hierarchy rooted in
|
|
Packit |
7cfc04 |
.IR path .
|
|
Packit |
7cfc04 |
For each object in the hierarchy,
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
shall call the function pointed to by
|
|
Packit |
7cfc04 |
.IR fn ,
|
|
Packit |
7cfc04 |
passing it a pointer to a null-terminated character string containing
|
|
Packit |
7cfc04 |
the name of the object, a pointer to a
|
|
Packit |
7cfc04 |
.BR stat
|
|
Packit |
7cfc04 |
structure containing information about the object, filled in as if
|
|
Packit |
7cfc04 |
\fIstat\fR()
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
\fIlstat\fR()
|
|
Packit |
7cfc04 |
had been called to retrieve the information. Possible values of the
|
|
Packit |
7cfc04 |
integer, defined in the
|
|
Packit |
7cfc04 |
.IR <ftw.h>
|
|
Packit |
7cfc04 |
header, are:
|
|
Packit |
7cfc04 |
.IP FTW_D 10
|
|
Packit |
7cfc04 |
For a directory.
|
|
Packit |
7cfc04 |
.IP FTW_DNR 10
|
|
Packit |
7cfc04 |
For a directory that cannot be read.
|
|
Packit |
7cfc04 |
.IP FTW_F 10
|
|
Packit |
7cfc04 |
For a non-directory file.
|
|
Packit |
7cfc04 |
.IP FTW_SL 10
|
|
Packit |
7cfc04 |
For a symbolic link (but see also FTW_NS below).
|
|
Packit |
7cfc04 |
.IP FTW_NS 10
|
|
Packit |
7cfc04 |
For an object other than a symbolic link on which
|
|
Packit |
7cfc04 |
\fIstat\fR()
|
|
Packit |
7cfc04 |
could not successfully be executed. If the object is a symbolic link
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIstat\fR()
|
|
Packit |
7cfc04 |
failed, it is unspecified whether
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
passes FTW_SL or FTW_NS to the user-supplied function.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the integer is FTW_DNR, descendants of that directory shall not be
|
|
Packit |
7cfc04 |
processed. If the integer is FTW_NS, the
|
|
Packit |
7cfc04 |
.BR stat
|
|
Packit |
7cfc04 |
structure contains undefined values. An example of an object that
|
|
Packit |
7cfc04 |
would cause FTW_NS to be passed to the function pointed to by
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
would be a file in a directory with read but without execute (search)
|
|
Packit |
7cfc04 |
permission.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
function shall visit a directory before visiting any of its
|
|
Packit |
7cfc04 |
descendants.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
function shall use at most one file descriptor for each level in
|
|
Packit |
7cfc04 |
the tree.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.IR ndirs
|
|
Packit |
7cfc04 |
should be in the range [1,\c
|
|
Packit |
7cfc04 |
{OPEN_MAX}].
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The tree traversal shall continue until either the tree is exhausted,
|
|
Packit |
7cfc04 |
an invocation of
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
returns a non-zero value, or some error, other than
|
|
Packit |
7cfc04 |
.BR [EACCES] ,
|
|
Packit |
7cfc04 |
is detected within
|
|
Packit |
7cfc04 |
\fIftw\fR().
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR ndirs
|
|
Packit |
7cfc04 |
argument shall specify the maximum number of directory streams or file
|
|
Packit |
7cfc04 |
descriptors or both available for use by
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
while traversing the tree. When
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
returns it shall close any directory streams and file descriptors it
|
|
Packit |
7cfc04 |
uses not counting any opened by the application-supplied
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
function.
|
|
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
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
function need not be thread-safe.
|
|
Packit |
7cfc04 |
.SH "RETURN VALUE"
|
|
Packit |
7cfc04 |
If the tree is exhausted,
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
shall return 0. If the function pointed to by
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
returns a non-zero value,
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
shall stop its tree traversal and return whatever value was returned
|
|
Packit |
7cfc04 |
by the function pointed to by
|
|
Packit |
7cfc04 |
.IR fn .
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
detects an error, it shall return \(mi1 and set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to indicate the error.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
encounters an error other than
|
|
Packit |
7cfc04 |
.BR [EACCES]
|
|
Packit |
7cfc04 |
(see FTW_DNR and FTW_NS above), it shall return \(mi1 and set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to indicate the error. The external variable
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
may contain any error value that is possible when a directory is opened
|
|
Packit |
7cfc04 |
or when one of the
|
|
Packit |
7cfc04 |
.IR stat
|
|
Packit |
7cfc04 |
functions is executed on a directory or file.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIftw\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 |
.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 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
function may fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINVAL
|
|
Packit |
7cfc04 |
The value of the
|
|
Packit |
7cfc04 |
.IR ndirs
|
|
Packit |
7cfc04 |
argument is invalid.
|
|
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 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 |
.P
|
|
Packit |
7cfc04 |
In addition, if the function pointed to by
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
encounters system errors,
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
may be set accordingly.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
.SS "Walking a Directory Structure"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The following example walks the current directory structure, calling
|
|
Packit |
7cfc04 |
the
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
function for every directory entry, using at most 10 file descriptors:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
#include <ftw.h>
|
|
Packit |
7cfc04 |
\&...
|
|
Packit |
7cfc04 |
if (ftw(".", fn, 10) != 0) {
|
|
Packit |
7cfc04 |
perror("ftw"); exit(2);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
function may allocate dynamic storage during its operation. If
|
|
Packit |
7cfc04 |
\fIftw\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 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
does not have a chance to free that storage, so it remains
|
|
Packit |
7cfc04 |
permanently allocated. A safe way to handle interrupts is to store the
|
|
Packit |
7cfc04 |
fact that an interrupt has occurred, and arrange to have the function
|
|
Packit |
7cfc04 |
pointed to by
|
|
Packit |
7cfc04 |
.IR fn
|
|
Packit |
7cfc04 |
return a non-zero value at its next invocation.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Applications should use the
|
|
Packit |
7cfc04 |
\fInftw\fR()
|
|
Packit |
7cfc04 |
function instead of the obsolescent
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
function.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIftw\fR()
|
|
Packit |
7cfc04 |
function may be removed in a future version.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "\fIfdopendir\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfstatat\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIlongjmp\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fInftw\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIsiglongjmp\fR\^(\|)"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fB<ftw.h>\fP",
|
|
Packit |
7cfc04 |
.IR "\fB<sys_stat.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 .
|