| ftw.3 (131660) | ftw.3 (131757) |
|---|---|
| 1.\" $OpenBSD: ftw.3,v 1.5 2004/01/25 14:48:32 jmc Exp $ 2.\" 3.\" Copyright (c) 2003 Todd C. Miller <Todd.Miller@courtesan.com> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" --- 4 unchanged lines hidden (view full) --- 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" Sponsored in part by the Defense Advanced Research Projects 18.\" Agency (DARPA) and Air Force Research Laboratory, Air Force 19.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. 20.\" | 1.\" $OpenBSD: ftw.3,v 1.5 2004/01/25 14:48:32 jmc Exp $ 2.\" 3.\" Copyright (c) 2003 Todd C. Miller <Todd.Miller@courtesan.com> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" --- 4 unchanged lines hidden (view full) --- 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" Sponsored in part by the Defense Advanced Research Projects 18.\" Agency (DARPA) and Air Force Research Laboratory, Air Force 19.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. 20.\" |
| 21.\" $FreeBSD: head/lib/libc/gen/ftw.3 131660 2004-07-05 23:12:11Z das $ | 21.\" $FreeBSD: head/lib/libc/gen/ftw.3 131757 2004-07-07 20:11:35Z ru $ |
| 22.\" 23.Dd July 5, 2004 24.Dt FTW 3 25.Os 26.Sh NAME | 22.\" 23.Dd July 5, 2004 24.Dt FTW 3 25.Os 26.Sh NAME |
| 27.Nm ftw, nftw | 27.Nm ftw , nftw |
| 28.Nd traverse (walk) a file tree 29.Sh SYNOPSIS | 28.Nd traverse (walk) a file tree 29.Sh SYNOPSIS |
| 30.Fd #include <ftw.h> | 30.In ftw.h |
| 31.Ft int 32.Fo ftw 33.Fa "const char *path" | 31.Ft int 32.Fo ftw 33.Fa "const char *path" |
| 34.Fa "int (*fn)(const char *, const struct stat *, int)" | 34.Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int\*[rp]" |
| 35.Fa "int maxfds" 36.Fc 37.Ft int 38.Fo nftw 39.Fa "const char *path" | 35.Fa "int maxfds" 36.Fc 37.Ft int 38.Fo nftw 39.Fa "const char *path" |
| 40.Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *, int, struct\ FTW\ *)" | 40.Fa "int \*[lp]*fn\*[rp]\*[lp](const char *, const struct stat *, int, struct FTW *\*[rp]" |
| 41.Fa "int maxfds" 42.Fa "int flags" 43.Fc 44.Sh DESCRIPTION | 41.Fa "int maxfds" 42.Fa "int flags" 43.Fc 44.Sh DESCRIPTION |
| 45.Pp | |
| 46The 47.Fn ftw 48and 49.Fn nftw 50functions traverse (walk) the directory hierarchy rooted in 51.Fa path . 52For each object in the hierarchy, these functions call the function 53pointed to by 54.Fa fn . 55The 56.Fn ftw | 45The 46.Fn ftw 47and 48.Fn nftw 49functions traverse (walk) the directory hierarchy rooted in 50.Fa path . 51For each object in the hierarchy, these functions call the function 52pointed to by 53.Fa fn . 54The 55.Fn ftw |
| 57function passes this function a pointer to a NUL-terminated string containing 58the name of the object, a pointer to a stat structure corresponding to the | 56function passes this function a pointer to a 57.Dv NUL Ns 58-terminated string containing 59the name of the object, a pointer to a 60.Vt stat 61structure corresponding to the |
| 59object, and an integer flag. 60The 61.Fn nftw 62function passes the aforementioned arguments plus a pointer to a | 62object, and an integer flag. 63The 64.Fn nftw 65function passes the aforementioned arguments plus a pointer to a |
| 63.Dv FTW | 66.Vt FTW |
| 64structure as defined by | 67structure as defined by |
| 65.Aq Pa ftw.h | 68.In ftw.h |
| 66(shown below): 67.Bd -literal 68struct FTW { 69 int base; /* offset of basename into pathname */ 70 int level; /* directory depth relative to starting point */ 71}; 72.Ed 73.Pp 74Possible values for the flag passed to 75.Fa fn 76are: | 69(shown below): 70.Bd -literal 71struct FTW { 72 int base; /* offset of basename into pathname */ 73 int level; /* directory depth relative to starting point */ 74}; 75.Ed 76.Pp 77Possible values for the flag passed to 78.Fa fn 79are: |
| 77.Bl -tag -width FTW_DNR | 80.Bl -tag -width ".Dv FTW_DNR" |
| 78.It Dv FTW_F 79A regular file. 80.It Dv FTW_D 81A directory being visited in pre-order. 82.It Dv FTW_DNR 83A directory which cannot be read. 84The directory will not be descended into. 85.It Dv FTW_DP 86A directory being visited in post-order | 81.It Dv FTW_F 82A regular file. 83.It Dv FTW_D 84A directory being visited in pre-order. 85.It Dv FTW_DNR 86A directory which cannot be read. 87The directory will not be descended into. 88.It Dv FTW_DP 89A directory being visited in post-order |
| 87.No ( Ns Fn nftw | 90.Fn ( nftw |
| 88only). 89.It Dv FTW_NS 90A file for which no 91.Xr stat 2 92information was available. | 91only). 92.It Dv FTW_NS 93A file for which no 94.Xr stat 2 95information was available. |
| 93The contents of the stat structure are undefined. | 96The contents of the 97.Vt stat 98structure are undefined. |
| 94.It Dv FTW_SL 95A symbolic link. 96.It Dv FTW_SLN 97A symbolic link with a non-existent target | 99.It Dv FTW_SL 100A symbolic link. 101.It Dv FTW_SLN 102A symbolic link with a non-existent target |
| 98.No ( Ns Fn nftw | 103.Fn ( nftw |
| 99only). 100.El 101.Pp 102The 103.Fn ftw 104function traverses the tree in pre-order. 105That is, it processes the directory before the directory's contents. 106.Pp 107The 108.Fa maxfds 109argument specifies the maximum number of file descriptors 110to keep open while traversing the tree. 111It has no effect in this implementation. 112.Pp 113The 114.Fn nftw 115function has an additional 116.Fa flags 117argument with the following possible values: | 104only). 105.El 106.Pp 107The 108.Fn ftw 109function traverses the tree in pre-order. 110That is, it processes the directory before the directory's contents. 111.Pp 112The 113.Fa maxfds 114argument specifies the maximum number of file descriptors 115to keep open while traversing the tree. 116It has no effect in this implementation. 117.Pp 118The 119.Fn nftw 120function has an additional 121.Fa flags 122argument with the following possible values: |
| 118.Bl -tag -width FTW_MOUNT | 123.Bl -tag -width ".Dv FTW_MOUNT" |
| 119.It Dv FTW_PHYS | 124.It Dv FTW_PHYS |
| 120Physical walk, don't follow symbolic links. | 125Physical walk, do not follow symbolic links. |
| 121.It Dv FTW_MOUNT 122The walk will not cross a mount point. 123.It FTW_DEPTH 124Process directories in post-order. 125Contents of a directory are visited before the directory itself. 126By default, 127.Fn nftw 128traverses the tree in pre-order. --- 65 unchanged lines hidden (view full) --- 194.Sh STANDARDS 195The 196.Fn ftw 197and 198.Fn nftw 199functions conform to 200.St -p1003.1-2001 . 201.Sh HISTORY | 126.It Dv FTW_MOUNT 127The walk will not cross a mount point. 128.It FTW_DEPTH 129Process directories in post-order. 130Contents of a directory are visited before the directory itself. 131By default, 132.Fn nftw 133traverses the tree in pre-order. --- 65 unchanged lines hidden (view full) --- 199.Sh STANDARDS 200The 201.Fn ftw 202and 203.Fn nftw 204functions conform to 205.St -p1003.1-2001 . 206.Sh HISTORY |
| 202These functions first appeared in System V Release 3. | 207These functions first appeared in 208.At V.3 . |
| 203Their first 204.Fx 205appearance was in 206.Fx 5.3 . 207.Sh BUGS 208The 209.Fa maxfds 210argument is currently ignored. | 209Their first 210.Fx 211appearance was in 212.Fx 5.3 . 213.Sh BUGS 214The 215.Fa maxfds 216argument is currently ignored. |