diff options
author | das <das@FreeBSD.org> | 2004-07-05 23:12:11 +0000 |
---|---|---|
committer | das <das@FreeBSD.org> | 2004-07-05 23:12:11 +0000 |
commit | 629365ba47f92c56495e82b1ed53268e7fc99d8a (patch) | |
tree | c7edc64da61500c67547189bbc0e12486814d317 /lib/libc/gen/ftw.3 | |
parent | f2aa52f71a3c1352f909f999aa5c8940d403c060 (diff) | |
download | FreeBSD-src-629365ba47f92c56495e82b1ed53268e7fc99d8a.zip FreeBSD-src-629365ba47f92c56495e82b1ed53268e7fc99d8a.tar.gz |
Documentation for ftw(3) and nftw(3).
Obtained from: OpenBSD
Diffstat (limited to 'lib/libc/gen/ftw.3')
-rw-r--r-- | lib/libc/gen/ftw.3 | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/lib/libc/gen/ftw.3 b/lib/libc/gen/ftw.3 new file mode 100644 index 0000000..fff9c6f --- /dev/null +++ b/lib/libc/gen/ftw.3 @@ -0,0 +1,210 @@ +.\" $OpenBSD: ftw.3,v 1.5 2004/01/25 14:48:32 jmc Exp $ +.\" +.\" Copyright (c) 2003 Todd C. Miller <Todd.Miller@courtesan.com> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.\" $FreeBSD$ +.\" +.Dd July 5, 2004 +.Dt FTW 3 +.Os +.Sh NAME +.Nm ftw, nftw +.Nd traverse (walk) a file tree +.Sh SYNOPSIS +.Fd #include <ftw.h> +.Ft int +.Fo ftw +.Fa "const char *path" +.Fa "int (*fn)(const char *, const struct stat *, int)" +.Fa "int maxfds" +.Fc +.Ft int +.Fo nftw +.Fa "const char *path" +.Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *, int, struct\ FTW\ *)" +.Fa "int maxfds" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Pp +The +.Fn ftw +and +.Fn nftw +functions traverse (walk) the directory hierarchy rooted in +.Fa path . +For each object in the hierarchy, these functions call the function +pointed to by +.Fa fn . +The +.Fn ftw +function passes this function a pointer to a NUL-terminated string containing +the name of the object, a pointer to a stat structure corresponding to the +object, and an integer flag. +The +.Fn nftw +function passes the aforementioned arguments plus a pointer to a +.Dv FTW +structure as defined by +.Aq Pa ftw.h +(shown below): +.Bd -literal +struct FTW { + int base; /* offset of basename into pathname */ + int level; /* directory depth relative to starting point */ +}; +.Ed +.Pp +Possible values for the flag passed to +.Fa fn +are: +.Bl -tag -width FTW_DNR +.It Dv FTW_F +A regular file. +.It Dv FTW_D +A directory being visited in pre-order. +.It Dv FTW_DNR +A directory which cannot be read. +The directory will not be descended into. +.It Dv FTW_DP +A directory being visited in post-order +.No ( Ns Fn nftw +only). +.It Dv FTW_NS +A file for which no +.Xr stat 2 +information was available. +The contents of the stat structure are undefined. +.It Dv FTW_SL +A symbolic link. +.It Dv FTW_SLN +A symbolic link with a non-existent target +.No ( Ns Fn nftw +only). +.El +.Pp +The +.Fn ftw +function traverses the tree in pre-order. +That is, it processes the directory before the directory's contents. +.Pp +The +.Fa maxfds +argument specifies the maximum number of file descriptors +to keep open while traversing the tree. +It has no effect in this implementation. +.Pp +The +.Fn nftw +function has an additional +.Fa flags +argument with the following possible values: +.Bl -tag -width FTW_MOUNT +.It Dv FTW_PHYS +Physical walk, don't follow symbolic links. +.It Dv FTW_MOUNT +The walk will not cross a mount point. +.It FTW_DEPTH +Process directories in post-order. +Contents of a directory are visited before the directory itself. +By default, +.Fn nftw +traverses the tree in pre-order. +.It FTW_CHDIR +Change to a directory before reading it. +By default, +.Fn nftw +will change its starting directory. +The current working directory will be restored to its original value before +.Fn nftw +returns. +.El +.Sh RETURN VALUES +If the tree was traversed successfully, the +.Fn ftw +and +.Fn nftw +functions return 0. +If the function pointed to by +.Fa fn +returns a non-zero value, +.Fn ftw +and +.Fn nftw +will stop processing the tree and return the value from +.Fa fn . +Both functions return \-1 if an error is detected. +.Sh ERRORS +The +.Fn ftw +and +.Fn nftw +functions may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr close 2 , +.Xr open 2 , +.Xr stat 2 , +.Xr malloc 3 , +.Xr opendir 3 +and +.Xr readdir 3 . +If the +.Dv FTW_CHDIR +flag is set, the +.Fn nftw +function may fail and set +.Va errno +for any of the errors specified for +.Xr chdir 2 . +In addition, either function may fail and set +.Va errno +as follows: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa maxfds +argument is less than 1. +.El +.Sh SEE ALSO +.Xr chdir 2 , +.Xr close 2 , +.Xr open 2 , +.Xr stat 2 , +.Xr fts 3 , +.Xr malloc 3 , +.Xr opendir 3 , +.Xr readdir 3 +.Sh STANDARDS +The +.Fn ftw +and +.Fn nftw +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +These functions first appeared in System V Release 3. +Their first +.Fx +appearance was in +.Fx 5.3 . +.Sh BUGS +The +.Fa maxfds +argument is currently ignored. |