Return to ftw.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libc / gen

Annotation of src/lib/libc/gen/ftw.3, Revision 1.5

1.5     ! jruoho      1: .\"    $NetBSD: ftw.3,v 1.4 2010/03/22 19:30:53 joerg Exp $
1.1       agc         2: .\"
                      3: .\"    From OpenBSD: ftw.3,v 1.4 2003/10/30 18:52:58 jmc Exp
                      4: .\"
                      5: .\" Copyright (c) 2003 Todd C. Miller <Todd.Miller@courtesan.com>
                      6: .\"
                      7: .\" Permission to use, copy, modify, and distribute this software for any
                      8: .\" purpose with or without fee is hereby granted, provided that the above
                      9: .\" copyright notice and this permission notice appear in all copies.
                     10: .\"
                     11: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     12: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     13: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     14: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     15: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     16: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     17: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     18: .\"
                     19: .\" Sponsored in part by the Defense Advanced Research Projects
                     20: .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
                     21: .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
                     22: .\"
1.5     ! jruoho     23: .Dd April 30, 2010
1.1       agc        24: .Dt FTW 3
                     25: .Os
                     26: .Sh NAME
                     27: .Nm ftw, nftw
                     28: .Nd traverse (walk) a file tree
                     29: .Sh SYNOPSIS
1.2       wiz        30: .In ftw.h
1.1       agc        31: .Ft int
                     32: .Fo ftw
                     33: .Fa "const char *path"
                     34: .Fa "int (*fn)(const char *, const struct stat *, int)"
                     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\ *)"
                     41: .Fa "int maxfds"
                     42: .Fa "int flags"
                     43: .Fc
                     44: .Sh DESCRIPTION
                     45: .Bf -symbolic
                     46: These functions are provided for compatibility with legacy code.
                     47: New code should use the
                     48: .Xr fts 3
                     49: functions.
                     50: .Ef
                     51: .Pp
                     52: The
                     53: .Fn ftw
                     54: and
                     55: .Fn nftw
                     56: functions traverse (walk) the directory hierarchy rooted in
                     57: .Fa path .
                     58: For each object in the hierarchy, these functions call the function
                     59: pointed to by
                     60: .Fa fn .
                     61: The
                     62: .Fn ftw
                     63: function passes this function a pointer to a NUL-terminated string containing
                     64: the name of the object, a pointer to a stat structure corresponding to the
                     65: object, and an integer flag.
                     66: The
                     67: .Fn nftw
                     68: function passes the aforementioned arguments plus a pointer to a
                     69: .Dv FTW
                     70: structure as defined by
1.4       joerg      71: .In ftw.h
1.1       agc        72: (shown below):
                     73: .Bd -literal
                     74: struct FTW {
                     75:     int base;  /* offset of basename into pathname */
                     76:     int level; /* directory depth relative to starting point */
                     77: };
                     78: .Ed
                     79: .Pp
                     80: Possible values for the flag passed to
                     81: .Fa fn
                     82: are:
                     83: .Bl -tag -width FTW_DNR
                     84: .It Dv FTW_F
                     85: A regular file.
                     86: .It Dv FTW_D
                     87: A directory being visited in pre-order.
                     88: .It Dv FTW_DNR
                     89: A directory which cannot be read.
                     90: The directory will not be descended into.
                     91: .It Dv FTW_DP
                     92: A directory being visited in post-order
1.2       wiz        93: .Pq Fn nftw No only .
1.1       agc        94: .It Dv FTW_NS
                     95: A file for which no
                     96: .Xr stat 2
                     97: information was available.
                     98: The contents of the stat structure are undefined.
                     99: .It Dv FTW_SL
                    100: A symbolic link.
                    101: .It Dv FTW_SLN
                    102: A symbolic link with a non-existent target
1.2       wiz       103: .Pq Fn nftw No only .
1.1       agc       104: .El
                    105: .Pp
                    106: The
                    107: .Fn ftw
                    108: function traverses the tree in pre-order.
                    109: That is, it processes the directory before the directory's contents.
                    110: .Pp
                    111: The
                    112: .Fa maxfds
                    113: argument specifies the maximum number of file descriptors
                    114: to keep open while traversing the tree.
                    115: It has no effect in this implementation.
                    116: .Pp
                    117: The
                    118: .Fn nftw
                    119: function has an additional
                    120: .Fa flags
                    121: argument with the following possible values:
                    122: .Bl -tag -width FTW_MOUNT
                    123: .It Dv FTW_PHYS
                    124: Physical walk, don't follow symbolic links.
                    125: .It Dv FTW_MOUNT
                    126: The walk will not cross a mount point.
                    127: .It FTW_DEPTH
                    128: Process directories in post-order.
                    129: Contents of a directory are visited before the directory itself.
                    130: By default,
                    131: .Fn nftw
                    132: traverses the tree in pre-order.
                    133: .It FTW_CHDIR
                    134: Change to a directory before reading it.
                    135: By default,
                    136: .Fn nftw
                    137: will change its starting directory.
                    138: The current working directory will be restored to its original value before
                    139: .Fn nftw
                    140: returns.
                    141: .El
                    142: .Sh RETURN VALUES
                    143: If the tree was traversed successfully, the
                    144: .Fn ftw
                    145: and
                    146: .Fn nftw
                    147: functions return 0.
                    148: If the function pointed to by
                    149: .Fa fn
                    150: returns a non-zero value,
                    151: .Fn ftw
                    152: and
                    153: .Fn nftw
                    154: will stop processing the tree and return the value from
                    155: .Fa fn .
                    156: Both functions return \-1 if an error is detected.
                    157: .Sh ERRORS
                    158: The
                    159: .Fn ftw
                    160: and
                    161: .Fn nftw
                    162: functions may fail and set
                    163: .Va errno
                    164: for any of the errors specified for the library functions
                    165: .Xr close 2 ,
                    166: .Xr open 2 ,
                    167: .Xr stat 2 ,
                    168: .Xr malloc 3 ,
1.2       wiz       169: .Xr opendir 3 ,
1.1       agc       170: and
                    171: .Xr readdir 3 .
                    172: If the
                    173: .Dv FGTW_CHDIR
                    174: flag is set, the
                    175: .Fn nftw
                    176: function may fail and set
                    177: .Va errno
                    178: for any of the errors specified for
                    179: .Xr chdir 2 .
                    180: In addition, either function may fail and set
                    181: .Va errno
                    182: as follows:
                    183: .Bl -tag -width Er
                    184: .It Bq Er EINVAL
                    185: The
                    186: .Fa maxfds
                    187: argument is less than 1 or greater than
                    188: .Dv OPEN_MAX .
                    189: .El
                    190: .Sh SEE ALSO
                    191: .Xr chdir 2 ,
                    192: .Xr close 2 ,
                    193: .Xr open 2 ,
                    194: .Xr stat 2 ,
                    195: .Xr fts 3 ,
                    196: .Xr malloc 3 ,
                    197: .Xr opendir 3 ,
                    198: .Xr readdir 3
                    199: .Sh STANDARDS
                    200: The
                    201: .Fn ftw
                    202: and
                    203: .Fn nftw
                    204: functions conform to
1.3       wiz       205: .St -p1003.1-2001 .
1.5     ! jruoho    206: The
        !           207: .St -p1003.1-2008
        !           208: revision marked the function
        !           209: .Fn ftw
        !           210: as obsolete.
1.1       agc       211: .Sh BUGS
                    212: The
                    213: .Fa maxfds
                    214: argument is currently ignored.