1 files changed, 253 insertions, 0 deletions
diff --git a/man3p/nftw.3p b/man3p/nftw.3p
new file mode 100644
index 000000000..6277a8824
--- /dev/null
+++ b/man3p/nftw.3p
@@ -0,0 +1,253 @@
+.\" 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 .