Return to fts.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen

Annotation of 43BSDReno/lib/libc/gen/fts.3, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1989 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted provided
        !             5: .\" that: (1) source distributions retain this entire copyright notice and
        !             6: .\" comment, and (2) distributions including binaries display the following
        !             7: .\" acknowledgement:  ``This product includes software developed by the
        !             8: .\" University of California, Berkeley and its contributors'' in the
        !             9: .\" documentation or other materials provided with the distribution and in
        !            10: .\" all advertising materials mentioning features or use of this software.
        !            11: .\" Neither the name of the University nor the names of its contributors may
        !            12: .\" be used to endorse or promote products derived from this software without
        !            13: .\" specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"    @(#)fts.3       5.6 (Berkeley) 6/23/90
        !            19: .\"
        !            20: .TH FTS 3 "June 23, 1990"
        !            21: .UC 7
        !            22: .SH NAME
        !            23: fts \- traverse a file hierarchy
        !            24: .SH SYNOPSIS
        !            25: .nf
        !            26: .ft B
        !            27: #include <sys/types.h>
        !            28: #include <sys/stat.h>
        !            29: #include <fts.h>
        !            30: 
        !            31: FTS *
        !            32: ftsopen(path_argv, options, compar)
        !            33: char *path_argv[];
        !            34: int options, (*compar)();
        !            35: 
        !            36: FTSENT *
        !            37: ftsread(ftsp);
        !            38: FTS *ftsp;
        !            39: 
        !            40: FTSENT *
        !            41: ftschildren(ftsp)
        !            42: FTS *ftsp;
        !            43: 
        !            44: ftsset(ftsp, f, options)
        !            45: FTS *ftsp;
        !            46: FTSENT *f;
        !            47: int options;
        !            48: 
        !            49: ftsclose(ftsp)
        !            50: FTS *ftsp;
        !            51: .ft R
        !            52: .fi
        !            53: .SH DESCRIPTION
        !            54: The
        !            55: .IR fts (3)
        !            56: utilities are provided for traversing UNIX file hierarchies.
        !            57: Two structures are defined (and typedef'd) in the include file <\fIfts.h\fP>.
        !            58: The first is FTS, the structure that defines the file hierarchy stream.
        !            59: The second is FTSENT, the structure that defines a file in the file
        !            60: hierarchy.
        !            61: .PP
        !            62: The
        !            63: .I ftsopen
        !            64: routine takes a pointer to an array of character pointers (``argv'')
        !            65: naming the file hierarchies to be traversed.
        !            66: The array must be terminated by a pointer to a NULL string.
        !            67: .PP
        !            68: The 
        !            69: .I options
        !            70: specified are formed by
        !            71: .IR or 'ing
        !            72: one or more of the following values:
        !            73: .TP
        !            74: FTS_LOGICAL
        !            75: This option causes 
        !            76: .I ftsread
        !            77: to use the function
        !            78: .IR stat (2),
        !            79: by default, to determine the status of each file.
        !            80: If this option is set, the only symbolic links returned to the application
        !            81: are those referencing non-existent files.
        !            82: Either FTS_LOGICAL or FTS_PHYSICAL
        !            83: .B must
        !            84: be provided to the 
        !            85: .I ftsopen
        !            86: routine.
        !            87: .TP
        !            88: FTS_NOCHDIR
        !            89: As a performance optimization,
        !            90: .I ftsread
        !            91: changes directories as it descends the hierarchy.
        !            92: This has the side-effect that applications cannot rely on being
        !            93: in any particular directory.
        !            94: The FTS_NOCHDIR option turns off this optimization.
        !            95: Note that applications should not change the current directory
        !            96: (even if FTS_NOCHDIR is specified) unless absolute pathnames were
        !            97: provided as arguments to
        !            98: .IR ftsopen .
        !            99: .TP
        !           100: FTS_NOSTAT
        !           101: By default,
        !           102: .I ftsread
        !           103: and
        !           104: .I ftschildren
        !           105: provide file characteristic information (the
        !           106: .I statb
        !           107: field) for each file they return.
        !           108: This option relaxes that requirement; the contents of the
        !           109: .I statb
        !           110: field may be undefined, and the
        !           111: .I info
        !           112: field may be set to FTS_NS.
        !           113: .TP
        !           114: FTS_PHYSICAL
        !           115: This option causes 
        !           116: .I ftsread
        !           117: to use the function
        !           118: .IR lstat (2),
        !           119: by default, to determine the status of each file.
        !           120: If this option is set, all symbolic links are returned to the application
        !           121: program.
        !           122: Either FTS_LOGICAL or FTS_PHYSICAL
        !           123: .B must
        !           124: be provided to the 
        !           125: .I ftsopen
        !           126: routine.
        !           127: .TP
        !           128: FTS_SEEDOT
        !           129: This option causes the routine
        !           130: .I ftsread
        !           131: to return structures for the directory entries ``.'' and ``..''.
        !           132: By default they are ignored unless specified as an argument to
        !           133: .IR ftsopen .
        !           134: .TP
        !           135: FTS_XDEV
        !           136: This option keeps
        !           137: .I fts
        !           138: from descending into directories that have a different device number
        !           139: than the file the descent began from.
        !           140: .PP
        !           141: The argument
        !           142: .I compar
        !           143: specifies a user-defined routine which is used to order the traversal
        !           144: of directories.
        !           145: .I Compar
        !           146: takes two pointers to pointers to FTSENT structures as arguments and
        !           147: should return a negative value, zero, or a positive value to indicate
        !           148: if the file referenced by its first argument comes before, in any order
        !           149: with respect to, or after, the file referenced by its second argument.
        !           150: .PP
        !           151: The
        !           152: .I fts_accpath
        !           153: and
        !           154: .I fts_path
        !           155: fields of the FTSENT structures may not be used in this comparison.
        !           156: If the option
        !           157: .I FTS_NOSTAT
        !           158: is specified, the
        !           159: .I fts_stab
        !           160: field may not be used as well.
        !           161: If the
        !           162: .I compar
        !           163: argument is NULL the directory traversal order is unspecified except
        !           164: for the root paths which are traversed in the order listed in
        !           165: .IR path_argv .
        !           166: .PP
        !           167: The
        !           168: .I ftsclose
        !           169: routine closes a file hierarchy stream and changes the current
        !           170: directory to the directory
        !           171: .I ftsopen
        !           172: was called from.
        !           173: .I Ftsclose
        !           174: returns 0 on success, and -1 if an error occurs.
        !           175: .PP
        !           176: Each call to the
        !           177: .I ftsread 
        !           178: routine returns a pointer to an FTSENT structure describing a file in
        !           179: the hierarchy.
        !           180: Directories (that are readable, searchable and do not cause cycles)
        !           181: are visited at least twice, before any of their descendants have been
        !           182: visited (pre-order) and after all their descendants have been visited
        !           183: (post-order).
        !           184: All other files are visited at least once.
        !           185: .PP
        !           186: The FTSENT structure contains at least the following fields:
        !           187: .sp
        !           188: .RS
        !           189: .nf
        !           190: .ta .5i +.5i +\w'struct ftsent *parent;\0\0\0'u
        !           191: typedef struct ftsent {
        !           192:        struct ftsent *fts_parent;              /* parent structure */
        !           193:        struct ftsent *fts_link;                /* cycle or file structure */
        !           194:        union {
        !           195:                long number;            /* local numeric value */
        !           196:                void *pointer;          /* local address value */
        !           197:        } fts_local;
        !           198:        char *fts_accpath;                      /* path from current directory */
        !           199:        char *fts_path;                 /* path from starting directory */
        !           200:        char *fts_name;                 /* file name */
        !           201:        short fts_pathlen;                      /* strlen(path) */
        !           202:        short fts_namelen;                      /* strlen(name) */
        !           203:        short fts_level;                        /* depth (\-1 to N) */
        !           204:        unsigned short fts_info;                /* flags for entry */
        !           205:        struct stat fts_statb;                  /* stat(2) information */
        !           206: } FTSENT;
        !           207: .fi
        !           208: .RE
        !           209: .PP
        !           210: The fields are as follows:
        !           211: .TP
        !           212: fts_parent
        !           213: A pointer to a structure referencing the file in the hierarchy
        !           214: immediately above the current file/structure.
        !           215: A parent structure for the initial entry point is provided as well,
        !           216: however, only the
        !           217: .I fts_local
        !           218: and
        !           219: .I fts_level
        !           220: fields are guaranteed to be initialized.
        !           221: .TP
        !           222: fts_link
        !           223: If a directory causes a cycle in the hierarchy, either because of a
        !           224: hard link between two directories, or a symbolic link pointing to a
        !           225: directory, the
        !           226: .I fts_link
        !           227: field of the structure will point to the structure in the hierarchy 
        !           228: that references the same file as the current structure.
        !           229: Upon return from the
        !           230: .I ftschildren
        !           231: routine, the
        !           232: .I fts_link
        !           233: field points to the next structure in the linked list of entries
        !           234: from the directory.
        !           235: Otherwise, the contents of the
        !           236: .I fts_link
        !           237: field are undefined.
        !           238: .TP
        !           239: fts_local
        !           240: This field is provided for the use of the application program.
        !           241: It can be used to store either a long value or an address.
        !           242: .TP
        !           243: fts_accpath
        !           244: A path that can be used to access the file.
        !           245: .TP
        !           246: fts_path
        !           247: The path for the file relative to the root of the traversal.
        !           248: .TP
        !           249: fts_name
        !           250: The basename of the file.
        !           251: .TP
        !           252: fts_pathlen
        !           253: The length of the string referenced by
        !           254: .IR fts_path .
        !           255: .TP
        !           256: fts_namelen
        !           257: The length of the string referenced by
        !           258: .IR fts_name .
        !           259: .TP 
        !           260: fts_level
        !           261: The depth of the traversal, numbered from \-1 to N.
        !           262: The parent structure of the root of the traversal is numbered \-1, and
        !           263: the structure for the root of the traversal is numbered 0.
        !           264: .TP 
        !           265: fts_info
        !           266: Information describing the file.
        !           267: With the exception of directories (FTS_D), all of these entries are
        !           268: terminal, i.e. they will not be revisited, nor will their descendants
        !           269: be visited (if they have not been visited already).
        !           270: .RS
        !           271: .TP
        !           272: FTS_D
        !           273: A directory being visited in pre-order.
        !           274: .TP
        !           275: FTS_DC
        !           276: A directory that causes a cycle.
        !           277: The 
        !           278: .I fts_link
        !           279: field of the structure will be filled in as well.
        !           280: .TP
        !           281: FTS_DEFAULT
        !           282: Anything that's not one of the others.
        !           283: .TP
        !           284: FTS_DNR
        !           285: A directory that cannot be read.
        !           286: .TP
        !           287: FTS_DNX
        !           288: A directory that cannot be searched.
        !           289: .TP
        !           290: FTS_DOT
        !           291: A file named ``.'' or ``..'' with a
        !           292: .I fts_level
        !           293: field not equal to zero, i.e. one not specified as an argument to
        !           294: .IR ftsopen .
        !           295: (See FTS_SEEDOT.)
        !           296: .TP
        !           297: FTS_DP
        !           298: A directory that is being visited in post-order.
        !           299: The contents of the structure will be unchanged from when the
        !           300: directory was visited in pre-order.
        !           301: .TP
        !           302: FTS_ERR
        !           303: An error indicator; the external variable
        !           304: .I errno
        !           305: contains an error number indicating the reason for the error.
        !           306: .TP
        !           307: FTS_F
        !           308: A regular file.
        !           309: .TP
        !           310: FTS_NS
        !           311: No
        !           312: .IR stat (2)
        !           313: information is available at this time (see FTS_NOSTAT); the
        !           314: contents of the
        !           315: .I fts_statb
        !           316: field are undefined.
        !           317: .TP
        !           318: FTS_SL
        !           319: A symbolic link.
        !           320: .TP
        !           321: FTS_SLNONE
        !           322: A symbolic link with a non-existent target.
        !           323: .RE
        !           324: .TP
        !           325: fts_statb
        !           326: .IR Stat (2)
        !           327: information for the file.
        !           328: .PP
        !           329: The
        !           330: .I fts_accpath
        !           331: and
        !           332: .I fts_path
        !           333: fields are guaranteed to be NULL-terminated
        !           334: .B only
        !           335: for the file most recently returned by
        !           336: .IR ftsread .
        !           337: The
        !           338: .I fts_name
        !           339: field is always NULL-terminated.
        !           340: To use these fields to reference any other active files may require
        !           341: that they be modified using the information contained in the
        !           342: .I fts_pathlen
        !           343: field.
        !           344: Any such modifications should be undone before further calls to
        !           345: .I ftsread
        !           346: are attempted.
        !           347: .PP
        !           348: If all the members of the hierarchy have been returned,
        !           349: .I ftsread
        !           350: returns NULL and sets the external variable
        !           351: .I errno
        !           352: to 0.
        !           353: If an error unrelated to a file in the hierarchy occurs,
        !           354: .I ftsread
        !           355: returns NULL and sets errno appropriately.
        !           356: Otherwise, a pointer to an FTSENT structure is returned, and an
        !           357: error may or may not have occurred; see FTS_ERR above.
        !           358: .PP
        !           359: When the most recently returned file from 
        !           360: .I ftsread
        !           361: is a directory being visited in pre-order, 
        !           362: .I ftschildren
        !           363: returns a pointer to the first entry in a linked list (sorted by
        !           364: the comparison routine, if provided) of the directory entries
        !           365: it contains.
        !           366: The linked list is linked through the
        !           367: .I fts_link
        !           368: field of the FTSENT structure.
        !           369: Each call to
        !           370: .I ftschildren
        !           371: recreates the list.
        !           372: Note, cycles are not detected until a directory is actually visited,
        !           373: therefore
        !           374: .I ftschildren
        !           375: will never return a structure with an
        !           376: .I fts_info
        !           377: field set to FTS_DC.
        !           378: If the current file is not a directory being visited in pre-order,
        !           379: or if an error occurs, or the file does not contain any entries
        !           380: .I ftschildren
        !           381: returns NULL.
        !           382: If an error occurs,
        !           383: .I ftschildren
        !           384: sets errno appropriately, otherwise it sets errno to zero.
        !           385: .PP
        !           386: The pointers returned by
        !           387: .I ftsread
        !           388: and
        !           389: .I ftschildren
        !           390: point to structures which may be overwritten.
        !           391: Structures returned by
        !           392: .I ftschildren
        !           393: and
        !           394: .I ftsread
        !           395: may be overwritten after a call to
        !           396: .I ftsclose
        !           397: on the same file hierarchy.
        !           398: Otherwise, structures returned by
        !           399: .I ftschildren
        !           400: will not be overwritten until a subsequent call to either
        !           401: .I ftschildren
        !           402: or
        !           403: .I ftsread
        !           404: on the same file hierarchy.
        !           405: Structures returned by
        !           406: .I ftsread
        !           407: will not not be overwritten until a subsequent call to
        !           408: .I ftsread
        !           409: on the same file hierarchy stream, unless it represents a file of type
        !           410: directory, in which case it will not be overwritten until after a
        !           411: subsequent call to
        !           412: .I ftsread
        !           413: after it has been returned by the function
        !           414: .I ftsread
        !           415: in post-order.
        !           416: .PP
        !           417: The routine
        !           418: .I ftsset
        !           419: allows the user application to determine further processing for the
        !           420: file
        !           421: .I f
        !           422: of the stream
        !           423: .IR ftsp .
        !           424: .I Ftsset
        !           425: returns 0 on success, and -1 if an error occurs.
        !           426: .I Option
        !           427: may be set to any one of the following values.
        !           428: .TP
        !           429: FTS_AGAIN
        !           430: Re-visit the file; any file type may be re-visited.
        !           431: The next call to
        !           432: .I ftsread
        !           433: will return the referenced file.
        !           434: The 
        !           435: .I fts_stat
        !           436: and
        !           437: .I fts_info
        !           438: fields of the structure will be reinitialized at that time,
        !           439: but no other fields will have been modified.
        !           440: This option is meaningful only for the most recently returned
        !           441: file from
        !           442: .IR ftsread .
        !           443: Normal use is for post-order directory visits, where it causes the
        !           444: directory to be re-visited (in both pre and post-order) as well as all
        !           445: of its descendants.
        !           446: .TP
        !           447: FTS_FOLLOW
        !           448: The referenced file must be a symbolic link.
        !           449: If the referenced file is the one most recently returned by
        !           450: .IR ftsread ,
        !           451: the next call to
        !           452: .I ftsread
        !           453: returns the file with the
        !           454: .I fts_info
        !           455: and
        !           456: .I fts_statb
        !           457: fields reinitialized to reflect the target of the symbolic link instead
        !           458: of the symbolic link itself.
        !           459: If the file is one of those most recently returned by
        !           460: .IR ftschildren ,
        !           461: the
        !           462: .I fts_info
        !           463: and
        !           464: .I fts_statb
        !           465: fields of the structure, when returned by
        !           466: .IR ftsread ,
        !           467: will reflect the target of the symbolic link instead of the symbolic link
        !           468: itself.
        !           469: In either case, if the target of the link is a directory, the pre-order
        !           470: return, followed by the return of all of its descendants, followed by a
        !           471: post-order return, is done.
        !           472: .TP
        !           473: FTS_SKIP
        !           474: No descendants of this file are visited.
        !           475: .PP
        !           476: Hard links between directories that do not cause cycles or symbolic
        !           477: links to symbolic links may cause files to be visited more than once,
        !           478: or directories more than twice.
        !           479: .SH ERRORS
        !           480: .I Ftsopen
        !           481: may fail and set errno for any of the errors specified for the library
        !           482: routine
        !           483: .IR malloc (3).
        !           484: .PP
        !           485: .I Ftsclose
        !           486: may fail and set errno for any of the errors specified for the library
        !           487: routine
        !           488: .IR chdir (2).
        !           489: .PP
        !           490: .I Ftsread
        !           491: and
        !           492: .I ftschildren
        !           493: may fail and set errno for any of the errors specified for the library
        !           494: routines
        !           495: .IR chdir (2),
        !           496: .IR getgroups (2),
        !           497: .IR malloc (3),
        !           498: .IR opendir (3),
        !           499: .IR readdir (3)
        !           500: and
        !           501: .IR stat (2).
        !           502: .SH SEE ALSO
        !           503: find(1), chdir(2), stat(2), qsort(3)
        !           504: .SH STANDARDS
        !           505: The
        !           506: .I fts
        !           507: utility is expected to be a superset of the POSIX 1003.1 specification.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.