diff options
Diffstat (limited to 'lib/libc/gen/ftw.3')
| -rw-r--r-- | lib/libc/gen/ftw.3 | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/lib/libc/gen/ftw.3 b/lib/libc/gen/ftw.3 new file mode 100644 index 000000000000..c9a1d6f1eee9 --- /dev/null +++ b/lib/libc/gen/ftw.3 @@ -0,0 +1,276 @@ +.\" $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. +.\" +.Dd March 12, 2020 +.Dt FTW 3 +.Os +.Sh NAME +.Nm ftw , nftw +.Nd traverse (walk) a file tree +.Sh SYNOPSIS +.In ftw.h +.Ft int +.Fo ftw +.Fa "const char *path" +.Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int\*[rp]" +.Fa "int maxfds" +.Fc +.Ft int +.Fo nftw +.Fa "const char *path" +.Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int, struct FTW *\*[rp]" +.Fa "int maxfds" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +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 +.Dv NUL Ns +-terminated string containing +the name of the object, a pointer to a +.Vt stat +structure corresponding to the +object, and an integer flag. +The +.Fn nftw +function passes the aforementioned arguments plus a pointer to a +.Vt FTW +structure as defined by +.In 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 ".Dv 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 +.Po Fn nftw +only +.Pc . +.It Dv FTW_NS +A file for which no +.Xr stat 2 +information was available. +The contents of the +.Vt stat +structure are undefined. +.It Dv FTW_SL +A symbolic link. +.It Dv FTW_SLN +A symbolic link with a non-existent target +.Po Fn nftw +only +.Pc . +.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 ".Dv FTW_MOUNT" +.It Dv FTW_PHYS +Physical walk, do not 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 EXAMPLES +Following there is an example that shows how +.Nm nftw +can be used. +It traverses the file tree starting at the directory pointed +by the only program argument and shows the complete path and a brief +indicator about the file type. +.Bd -literal -offset 2n +#include <ftw.h> +#include <stdio.h> +#include <sysexits.h> + +int +nftw_callback(const char *path, const struct stat *sb, int typeflag, struct FTW *ftw) +{ + char type; + + switch(typeflag) { + case FTW_F: + type = 'F'; + break; + case FTW_D: + type = 'D'; + break; + case FTW_DNR: + type = '-'; + break; + case FTW_DP: + type = 'd'; + break; + case FTW_NS: + type = 'X'; + break; + case FTW_SL: + type = 'S'; + break; + case FTW_SLN: + type = 's'; + break; + default: + type = '?'; + break; + } + + printf("[%c] %s\\n", type, path); + + return (0); +} + +int +main(int argc, char **argv) +{ + + if (argc != 2) { + printf("Usage %s <directory>\\n", argv[0]); + return (EX_USAGE); + } else + return (nftw(argv[1], nftw_callback, /* UNUSED */ 1, 0)); +} +.Ed +.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 +.At V.3 . +Their first +.Fx +appearance was in +.Fx 5.3 . +.Sh BUGS +The +.Fa maxfds +argument is currently ignored. |