diff options
Diffstat (limited to 'man3/ftw.3')
| -rw-r--r-- | man3/ftw.3 | 502 |
1 files changed, 0 insertions, 502 deletions
diff --git a/man3/ftw.3 b/man3/ftw.3 deleted file mode 100644 index 655bd38ac..000000000 --- a/man3/ftw.3 +++ /dev/null @@ -1,502 +0,0 @@ -'\" t -.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) -.\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) -.\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net> -.\" and copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: GPL-2.0-or-later -.\" -.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) -.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> -.\" document FTW_ACTIONRETVAL; include .SH RETURN VALUE; -.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and -.\" Michael Kerrisk <mtk.manpages@gmail.com> -.\" reorganized and rewrote much of the page -.\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com> -.\" Added an example program. -.\" -.TH ftw 3 (date) "Linux man-pages (unreleased)" -.SH NAME -ftw, nftw \- file tree walk -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <ftw.h> -.P -.BI "int nftw(const char *" dirpath , -.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , -.BI " int " typeflag ", struct FTW *" ftwbuf ), -.BI " int " nopenfd ", int " flags ); -.P -.B [[deprecated]] -.BI "int ftw(const char *" dirpath , -.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , -.BI " int " typeflag ), -.BI " int " nopenfd ); -.fi -.P -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.P -.BR nftw (): -.nf - _XOPEN_SOURCE >= 500 -.fi -.SH DESCRIPTION -.BR nftw () -walks through the directory tree that is -located under the directory \fIdirpath\fP, -and calls \fIfn\fP() once for each entry in the tree. -By default, directories are handled before the files and -subdirectories they contain (preorder traversal). -.P -To avoid using up all of the calling process's file descriptors, -\fInopenfd\fP specifies the maximum number of directories that -.BR nftw () -will hold open simultaneously. -When -the search depth exceeds this, -.BR nftw () -will become slower because -directories have to be closed and reopened. -.BR nftw () -uses at most -one file descriptor for each level in the directory tree. -.P -For each entry found in the tree, -.BR nftw () -calls -\fIfn\fP() with four arguments: -.IR fpath , -.IR sb , -.IR typeflag , -and -.IR ftwbuf . -.I fpath -is the pathname of the entry, -and is expressed either as a pathname relative to the calling process's -current working directory at the time of the call to -.BR nftw (), -if -.I dirpath -was expressed as a relative pathname, -or as an absolute pathname, if -.I dirpath -was expressed as an absolute pathname. -.I sb -is a pointer to the -.I stat -structure returned by a call to -.BR stat (2) -for -.IR fpath . -.P -The -.I typeflag -argument passed to -.IR fn () -is an integer that has one of the following values: -.TP -.B FTW_F -.I fpath -is a regular file. -.TP -.B FTW_D -.I fpath -is a directory. -.TP -.B FTW_DNR -.I fpath -is a directory which can't be read. -.TP -.B FTW_DP -.I fpath -is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP. -(If -.B FTW_DEPTH -was not specified in -.IR flags , -then directories will always be visited with -.I typeflag -set to -.BR FTW_D .) -All of the files -and subdirectories within \fIfpath\fP have been processed. -.TP -.B FTW_NS -The -.BR stat (2) -call failed on -.IR fpath , -which is not a symbolic link. -The probable cause for this is that the caller had read permission -on the parent directory, so that the filename -.I fpath -could be seen, -but did not have execute permission, -so that the file could not be reached for -.BR stat (2). -The contents of the buffer pointed to by -.I sb -are undefined. -.TP -.B FTW_SL -.I fpath -is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP. -.\" To obtain the definition of this constant from -.\" .IR <ftw.h> , -.\" either -.\" .B _BSD_SOURCE -.\" must be defined, or -.\" .BR _XOPEN_SOURCE -.\" must be defined with a value of 500 or more. -.TP -.B FTW_SLN -.I fpath -is a symbolic link pointing to a nonexistent file. -(This occurs only if \fBFTW_PHYS\fP is not set.) -In this case the -.I sb -argument passed to -.IR fn () -contains information returned by performing -.BR lstat (2) -on the "dangling" symbolic link. -(But see BUGS.) -.P -The fourth argument -.RI ( ftwbuf ) -that -.BR nftw () -supplies when calling -\fIfn\fP() -is a pointer to a structure of type \fIFTW\fP: -.P -.in +4n -.EX -struct FTW { - int base; - int level; -}; -.EE -.in -.P -.I base -is the offset of the filename (i.e., basename component) -in the pathname given in -.IR fpath . -.I level -is the depth of -.I fpath -in the directory tree, relative to the root of the tree -.RI ( dirpath , -which has depth 0). -.P -To stop the tree walk, \fIfn\fP() returns a nonzero value; this -value will become the return value of -.BR nftw (). -As long as \fIfn\fP() returns 0, -.BR nftw () -will continue either until it has traversed the entire tree, -in which case it will return zero, -or until it encounters an error (such as a -.BR malloc (3) -failure), in which case it will return \-1. -.P -Because -.BR nftw () -uses dynamic data structures, the only safe way to -exit out of a tree walk is to return a nonzero value from \fIfn\fP(). -To allow a signal to terminate the walk without causing a memory leak, -have the handler set a global flag that is checked by \fIfn\fP(). -\fIDon't\fP use -.BR longjmp (3) -unless the program is going to terminate. -.P -The \fIflags\fP argument of -.BR nftw () -is formed by ORing zero or more of the -following flags: -.TP -.BR FTW_ACTIONRETVAL " (since glibc 2.3.3)" -If this glibc-specific flag is set, then -.BR nftw () -handles the return value from -.IR fn () -differently. -.IR fn () -should return one of the following values: -.RS -.TP -.B FTW_CONTINUE -Instructs -.BR nftw () -to continue normally. -.TP -.B FTW_SKIP_SIBLINGS -If \fIfn\fP() returns this value, then -siblings of the current entry will be skipped, -and processing continues in the parent. -.\" If \fBFTW_DEPTH\fP -.\" is set, the entry's parent directory is processed next (with -.\" \fIflag\fP set to \fBFTW_DP\fP). -.TP -.B FTW_SKIP_SUBTREE -If \fIfn\fP() is called with an entry that is a directory -(\fItypeflag\fP is \fBFTW_D\fP), this return -value will prevent objects within that directory from being passed as -arguments to \fIfn\fP(). -.BR nftw () -continues processing with the next sibling of the directory. -.TP -.B FTW_STOP -Causes -.BR nftw () -to return immediately with the return value -\fBFTW_STOP\fP. -.P -Other return values could be associated with new actions in the future; -\fIfn\fP() should not return values other than those listed above. -.P -The feature test macro -.B _GNU_SOURCE -must be defined -(before including -.I any -header files) -in order to -obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP. -.RE -.TP -.B FTW_CHDIR -If set, do a -.BR chdir (2) -to each directory before handling its contents. -This is useful if the program needs to perform some action -in the directory in which \fIfpath\fP resides. -(Specifying this flag has no effect on the pathname that is passed in the -.I fpath -argument of -.IR fn .) -.TP -.B FTW_DEPTH -If set, do a post-order traversal, that is, call \fIfn\fP() for -the directory itself \fIafter\fP handling the contents of the directory -and its subdirectories. -(By default, each directory is handled \fIbefore\fP its contents.) -.TP -.B FTW_MOUNT -If set, stay within the same filesystem -(i.e., do not cross mount points). -.TP -.B FTW_PHYS -If set, do not follow symbolic links. -(This is what you want.) -If not set, symbolic links are followed, but no file is reported twice. -.IP -If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set, -then the function -.IR fn () -is never called for a directory that would be a descendant of itself. -.SS ftw() -.BR ftw () -is an older function that offers a subset of the functionality of -.BR nftw (). -The notable differences are as follows: -.IP \[bu] 3 -.BR ftw () -has no -.I flags -argument. -It behaves the same as when -.BR nftw () -is called with -.I flags -specified as zero. -.IP \[bu] -The callback function, -.IR fn (), -is not supplied with a fourth argument. -.IP \[bu] -The range of values that is passed via the -.I typeflag -argument supplied to -.IR fn () -is smaller: just -.BR FTW_F , -.BR FTW_D , -.BR FTW_DNR , -.BR FTW_NS , -and (possibly) -.BR FTW_SL . -.SH RETURN VALUE -These functions return 0 on success, and \-1 if an error occurs. -.P -If \fIfn\fP() returns nonzero, -then the tree walk is terminated and the value returned by \fIfn\fP() -is returned as the result of -.BR ftw () -or -.BR nftw (). -.P -If -.BR nftw () -is called with the \fBFTW_ACTIONRETVAL\fP flag, -then the only nonzero value that should be used by \fIfn\fP() -to terminate the tree walk is \fBFTW_STOP\fP, -and that value is returned as the result of -.BR nftw (). -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.na -.nh -.BR nftw () -T} Thread safety MT-Safe cwd -T{ -.na -.nh -.BR ftw () -T} Thread safety MT-Safe -.TE -.SH VERSIONS -In some implementations (e.g., glibc), -.BR ftw () -will never use \fBFTW_SL\fP; on other systems \fBFTW_SL\fP occurs only -for symbolic links that do not point to an existing file; -and again on other systems -.BR ftw () -will use \fBFTW_SL\fP for each symbolic link. -If -.I fpath -is a symbolic link and -.BR stat (2) -failed, POSIX.1-2008 states -that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP -is passed in -.IR typeflag . -For predictable results, use -.BR nftw (). -.SH STANDARDS -POSIX.1-2008. -.SH HISTORY -.TP -.BR ftw () -POSIX.1-2001, SVr4, SUSv1. -POSIX.1-2008 marks it as obsolete. -.TP -.BR nftw () -glibc 2.1. -POSIX.1-2001, SUSv1. -.TP -.B FTW_SL -POSIX.1-2001, SUSv1. -.SH NOTES -POSIX.1-2008 notes that the results are unspecified if -.I fn -does not preserve the current working directory. -.SH BUGS -According to POSIX.1-2008, when the -.I typeflag -argument passed to -.IR fn () -contains -.BR FTW_SLN , -the buffer pointed to by -.I sb -should contain information about the dangling symbolic link -(obtained by calling -.BR lstat (2) -on the link). -Early glibc versions correctly followed the POSIX specification on this point. -However, as a result of a regression introduced in glibc 2.4, -the contents of the buffer pointed to by -.I sb -were undefined when -.B FTW_SLN -is passed in -.IR typeflag . -(More precisely, the contents of the buffer were left unchanged in this case.) -This regression was eventually fixed in glibc 2.30, -.\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736 -.\" http://austingroupbugs.net/view.php?id=1121 -.\" glibc commit 6ba205b2c35e3e024c8c12d2ee1b73363e84da87 -.\" https://sourceware.org/bugzilla/show_bug.cgi?id=23501 -so that the glibc implementation (once more) follows the POSIX specification. -.SH EXAMPLES -The following program traverses the directory tree under the path named -in its first command-line argument, or under the current directory -if no argument is supplied. -It displays various information about each file. -The second command-line argument can be used to specify characters that -control the value assigned to the \fIflags\fP -argument when calling -.BR nftw (). -.SS Program source -\& -.\" SRC BEGIN (ftw.c) -.EX -#define _XOPEN_SOURCE 500 -#include <ftw.h> -#include <stdint.h> -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -\& -static int -display_info(const char *fpath, const struct stat *sb, - int tflag, struct FTW *ftwbuf) -{ - printf("%\-3s %2d ", - (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" : - (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" : - (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" : - (tflag == FTW_SLN) ? "sln" : "???", - ftwbuf\->level); -\& - if (tflag == FTW_NS) - printf("\-\-\-\-\-\-\-"); - else - printf("%7jd", (intmax_t) sb\->st_size); -\& - printf(" %\-40s %d %s\en", - fpath, ftwbuf\->base, fpath + ftwbuf\->base); -\& - return 0; /* To tell nftw() to continue */ -} -\& -int -main(int argc, char *argv[]) -{ - int flags = 0; -\& - if (argc > 2 && strchr(argv[2], \[aq]d\[aq]) != NULL) - flags |= FTW_DEPTH; - if (argc > 2 && strchr(argv[2], \[aq]p\[aq]) != NULL) - flags |= FTW_PHYS; -\& - if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) - == \-1) - { - perror("nftw"); - exit(EXIT_FAILURE); - } -\& - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.BR stat (2), -.BR fts (3), -.BR readdir (3) |