+++ /dev/null
-.\" $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $
-.\"
-.\" Copyright (c) 1989, 1991, 1993, 1994
-.\" The Regents of the University of California. All rights reserved.
-.\"
-.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the University of
-.\" California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
-.\" may be used to endorse or promote products derived from this software
-.\" without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\" %%%LICENSE_END
-.\"
-.\" @(#)fts.3 8.5 (Berkeley) 4/16/94
-.\"
-.\" 2007-12-08, mtk, Converted from mdoc to man macros
-.\"
-.TH FTS 3 2014-03-18 "Linux" "Linux Programmer's Manual"
-.SH NAME
-fts, fts_open, fts_read, fts_children, fts_set, fts_close \- \
-traverse a file hierarchy
-.SH SYNOPSIS
-.nf
-.B #include <sys/types.h>
-.B #include <sys/stat.h>
-.B #include <fts.h>
-.sp
-.BI "FTS *fts_open(char * const *" path_argv ", int " options ", "
-.BI " int (*" compar ")(const FTSENT **, const FTSENT **));"
-.sp
-.BI "FTSENT *fts_read(FTS *" ftsp );
-.sp
-.BI "FTSENT *fts_children(FTS *" ftsp ", int " options );
-.sp
-.BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " options );
-.sp
-.BI "int fts_close(FTS *" ftsp );
-.fi
-.SH DESCRIPTION
-The
-fts functions are provided for traversing
-file hierarchies.
-A simple overview is that the
-.BR fts_open ()
-function returns a "handle" on a file hierarchy, which is then supplied to
-the other
-fts functions.
-The function
-.BR fts_read ()
-returns a pointer to a structure describing one of the files in the file
-hierarchy.
-The function
-.BR fts_children ()
-returns a pointer to a linked list of structures, each of which describes
-one of the files contained in a directory in the hierarchy.
-In general, directories are visited two distinguishable times; in preorder
-(before any of their descendants are visited) and in postorder (after all
-of their descendants have been visited).
-Files are visited once.
-It is possible to walk the hierarchy "logically" (visiting the files that
-symbolic links point to)
-or physically (visiting the symbolic links themselves),
-order the walk of the hierarchy or
-prune and/or revisit portions of the hierarchy.
-.PP
-Two structures are defined (and typedef'd) in the include file
-.IR <fts.h> .
-The first is
-.IR FTS ,
-the structure that represents the file hierarchy itself.
-The second is
-.IR FTSENT ,
-the structure that represents a file in the file
-hierarchy.
-Normally, an
-.I FTSENT
-structure is returned for every file in the file
-hierarchy.
-In this manual page, "file" and
-"FTSENT structure"
-are generally interchangeable.
-The
-.I FTSENT
-structure contains at least the following fields, which are
-described in greater detail below:
-.in +4n
-.nf
-
-typedef struct _ftsent {
- unsigned short fts_info; /* flags for FTSENT structure */
- char *fts_accpath; /* access path */
- char *fts_path; /* root path */
- short fts_pathlen; /* strlen(fts_path) */
- char *fts_name; /* filename */
- short fts_namelen; /* strlen(fts_name) */
- short fts_level; /* depth (\-1 to N) */
- int fts_errno; /* file errno */
- long fts_number; /* local numeric value */
- void *fts_pointer; /* local address value */
- struct ftsent *fts_parent; /* parent directory */
- struct ftsent *fts_link; /* next file structure */
- struct ftsent *fts_cycle; /* cycle structure */
- struct stat *fts_statp; /* stat(2) information */
-} FTSENT;
-.fi
-.in
-.PP
-These fields are defined as follows:
-.\" .Bl -tag -width "fts_namelen"
-.TP 12
-.IR fts_info
-One of the following flags describing the returned
-.I FTSENT
-structure and
-the file it represents.
-With the exception of directories without errors
-.RB ( FTS_D ),
-all of these
-entries are terminal, that is, they will not be revisited, nor will any
-of their descendants be visited.
-.\" .Bl -tag -width FTS_DEFAULT
-.RS 12
-.TP 12
-.BR FTS_D
-A directory being visited in preorder.
-.TP
-.BR FTS_DC
-A directory that causes a cycle in the tree.
-(The
-.I fts_cycle
-field of the
-.I FTSENT
-structure will be filled in as well.)
-.TP
-.BR FTS_DEFAULT
-Any
-.I FTSENT
-structure that represents a file type not explicitly described
-by one of the other
-.I fts_info
-values.
-.TP
-.BR FTS_DNR
-A directory which cannot be read.
-This is an error return, and the
-.I fts_errno
-field will be set to indicate what caused the error.
-.TP
-.BR FTS_DOT
-A file named
-"."
-or
-".."
-which was not specified as a filename to
-.BR fts_open ()
-(see
-.BR FTS_SEEDOT ).
-.TP
-.BR FTS_DP
-A directory being visited in postorder.
-The contents of the
-.I FTSENT
-structure will be unchanged from when
-it was returned in preorder, that is, with the
-.I fts_info
-field set to
-.BR FTS_D .
-.TP
-.BR FTS_ERR
-This is an error return, and the
-.I fts_errno
-field will be set to indicate what caused the error.
-.TP
-.BR FTS_F
-A regular file.
-.TP
-.BR FTS_NS
-A file for which no
-.BR stat (2)
-information was available.
-The contents of the
-.I fts_statp
-field are undefined.
-This is an error return, and the
-.I fts_errno
-field will be set to indicate what caused the error.
-.TP
-.BR FTS_NSOK
-A file for which no
-.BR stat (2)
-information was requested.
-The contents of the
-.I fts_statp
-field are undefined.
-.TP
-.BR FTS_SL
-A symbolic link.
-.TP
-.BR FTS_SLNONE
-A symbolic link with a nonexistent target.
-The contents of the
-.I fts_statp
-field reference the file characteristic information for the symbolic link
-itself.
-.\" .El
-.RE
-.TP
-.IR fts_accpath
-A path for accessing the file from the current directory.
-.TP
-.IR fts_path
-The path for the file relative to the root of the traversal.
-This path contains the path specified to
-.BR fts_open ()
-as a prefix.
-.TP
-.IR fts_pathlen
-The length of the string referenced by
-.IR fts_path .
-.TP
-.IR fts_name
-The name of the file.
-.TP
-.IR fts_namelen
-The length of the string referenced by
-.IR fts_name .
-.TP
-.IR fts_level
-The depth of the traversal, numbered from \-1 to N, where this file
-was found.
-The
-.I FTSENT
-structure representing the parent of the starting point (or root)
-of the traversal is numbered \-1, and the
-.I FTSENT
-structure for the root
-itself is numbered 0.
-.TP
-.IR fts_errno
-Upon return of a
-.I FTSENT
-structure from the
-.BR fts_children ()
-or
-.BR fts_read ()
-functions, with its
-.I fts_info
-field set to
-.BR FTS_DNR ,
-.BR FTS_ERR
-or
-.BR FTS_NS ,
-the
-.I fts_errno
-field contains the value of the external variable
-.I errno
-specifying the cause of the error.
-Otherwise, the contents of the
-.I fts_errno
-field are undefined.
-.TP
-.IR fts_number
-This field is provided for the use of the application program and is
-not modified by the
-fts functions.
-It is initialized to 0.
-.TP
-.IR fts_pointer
-This field is provided for the use of the application program and is
-not modified by the
-fts functions.
-It is initialized to
-NULL.
-.TP
-.IR fts_parent
-A pointer to the
-.I FTSENT
-structure referencing the file in the hierarchy
-immediately above the current file, that is, the directory of which this
-file is a member.
-A parent structure for the initial entry point is provided as well,
-however, only the
-.IR fts_level ,
-.I fts_number
-and
-.I fts_pointer
-fields are guaranteed to be initialized.
-.TP
-.IR fts_link
-Upon return from the
-.BR fts_children ()
-function, the
-.I fts_link
-field points to the next structure in the NULL-terminated linked list of
-directory members.
-Otherwise, the contents of the
-.I fts_link
-field are undefined.
-.TP
-.IR fts_cycle
-If a directory causes a cycle in the hierarchy (see
-.BR FTS_DC ),
-either because
-of a hard link between two directories, or a symbolic link pointing to a
-directory, the
-.I fts_cycle
-field of the structure will point to the
-.I FTSENT
-structure in the hierarchy that references the same file as the current
-.I FTSENT
-structure.
-Otherwise, the contents of the
-.I fts_cycle
-field are undefined.
-.TP
-.IR fts_statp
-A pointer to
-.BR stat (2)
-information for the file.
-.\" .El
-.PP
-A single buffer is used for all of the paths of all of the files in the
-file hierarchy.
-Therefore, the
-.I fts_path
-and
-.I fts_accpath
-fields are guaranteed to be
-null-terminated
-.I only
-for the file most recently returned by
-.BR fts_read ().
-To use these fields to reference any files represented by other
-.I FTSENT
-structures will require that the path buffer be modified using the
-information contained in that
-.I FTSENT
-structure's
-.I fts_pathlen
-field.
-Any such modifications should be undone before further calls to
-.BR fts_read ()
-are attempted.
-The
-.I fts_name
-field is always
-null-terminated.
-.SS fts_open()
-The
-.BR fts_open ()
-function takes a pointer to an array of character pointers naming one
-or more paths which make up a logical file hierarchy to be traversed.
-The array must be terminated by a
-null pointer.
-.PP
-There are
-a number of options, at least one of which (either
-.BR FTS_LOGICAL
-or
-.BR FTS_PHYSICAL )
-must be specified.
-The options are selected by ORing
-the following values:
-.\" .Bl -tag -width "FTS_PHYSICAL"
-.TP 13
-.BR FTS_COMFOLLOW
-This option causes any symbolic link specified as a root path to be
-followed immediately whether or not
-.BR FTS_LOGICAL
-is also specified.
-.TP
-.BR FTS_LOGICAL
-This option causes the
-fts routines to return
-.I FTSENT
-structures for the targets of symbolic links
-instead of the symbolic links themselves.
-If this option is set, the only symbolic links for which
-.I FTSENT
-structures
-are returned to the application are those referencing nonexistent files.
-Either
-.BR FTS_LOGICAL
-or
-.BR FTS_PHYSICAL
-.I must
-be provided to the
-.BR fts_open ()
-function.
-.TP
-.BR FTS_NOCHDIR
-As a performance optimization, the
-fts functions change directories as they walk the file hierarchy.
-This has the side-effect that an application cannot rely on being
-in any particular directory during the traversal.
-The
-.BR FTS_NOCHDIR
-option turns off this optimization, and the
-fts functions will not change the current directory.
-Note that applications should not themselves change their current directory
-and try to access files unless
-.BR FTS_NOCHDIR
-is specified and absolute
-pathnames were provided as arguments to
-.BR fts_open ().
-.TP
-.BR FTS_NOSTAT
-By default, returned
-.I FTSENT
-structures reference file characteristic information (the
-.I statp
-field) for each file visited.
-This option relaxes that requirement as a performance optimization,
-allowing the
-fts functions to set the
-.I fts_info
-field to
-.BR FTS_NSOK
-and leave the contents of the
-.I statp
-field undefined.
-.TP
-.BR FTS_PHYSICAL
-This option causes the
-fts routines to return
-.I FTSENT
-structures for symbolic links themselves instead
-of the target files they point to.
-If this option is set,
-.I FTSENT
-structures for all symbolic links in the
-hierarchy are returned to the application.
-Either
-.BR FTS_LOGICAL
-or
-.BR FTS_PHYSICAL
-.I must
-be provided to the
-.BR fts_open ()
-function.
-.TP
-.BR FTS_SEEDOT
-By default, unless they are specified as path arguments to
-.BR fts_open (),
-any files named
-"."
-or
-".."
-encountered in the file hierarchy are ignored.
-This option causes the
-fts routines to return
-.I FTSENT
-structures for them.
-.TP
-.BR FTS_XDEV
-This option prevents
-fts from descending into directories that have a different device number
-than the file from which the descent began.
-.\" .El
-.PP
-The argument
-.BR compar ()
-specifies a user-defined function which may be used to order the traversal
-of the hierarchy.
-It
-takes two pointers to pointers to
-.I FTSENT
-structures as arguments and
-should return a negative value, zero, or a positive value to indicate
-if the file referenced by its first argument comes before, in any order
-with respect to, or after, the file referenced by its second argument.
-The
-.IR fts_accpath ,
-.I fts_path
-and
-.I fts_pathlen
-fields of the
-.I FTSENT
-structures may
-.I never
-be used in this comparison.
-If the
-.I fts_info
-field is set to
-.BR FTS_NS
-or
-.BR FTS_NSOK ,
-the
-.I fts_statp
-field may not either.
-If the
-.BR compar ()
-argument is
-NULL,
-the directory traversal order is in the order listed in
-.I path_argv
-for the root paths, and in the order listed in the directory for
-everything else.
-.SS fts_read()
-The
-.BR fts_read ()
-function returns a pointer to an
-.I FTSENT
-structure describing a file in
-the hierarchy.
-Directories (that are readable and do not cause cycles) are visited at
-least twice, once in preorder and once in postorder.
-All other files are visited at least once.
-(Hard links between directories that do not cause cycles or symbolic
-links to symbolic links may cause files to be visited more than once,
-or directories more than twice.)
-.PP
-If all the members of the hierarchy have been returned,
-.BR fts_read ()
-returns
-NULL
-and sets the external variable
-.I errno
-to 0.
-If an error unrelated to a file in the hierarchy occurs,
-.BR fts_read ()
-returns
-NULL
-and sets
-.I errno
-appropriately.
-If an error related to a returned file occurs, a pointer to an
-.I FTSENT
-structure is returned, and
-.I errno
-may or may not have been set (see
-.IR fts_info ).
-.PP
-The
-.I FTSENT
-structures returned by
-.BR fts_read ()
-may be overwritten after a call to
-.BR fts_close ()
-on the same file hierarchy stream, or, after a call to
-.BR fts_read ()
-on the same file hierarchy stream unless they represent a file of type
-directory, in which case they will not be overwritten until after a call to
-.BR fts_read ()
-after the
-.I FTSENT
-structure has been returned by the function
-.BR fts_read ()
-in postorder.
-.SS fts_children()
-The
-.BR fts_children ()
-function returns a pointer to an
-.I FTSENT
-structure describing the first entry in a NULL-terminated linked list of
-the files in the directory represented by the
-.I FTSENT
-structure most recently returned by
-.BR fts_read ().
-The list is linked through the
-.I fts_link
-field of the
-.I FTSENT
-structure, and is ordered by the user-specified comparison function, if any.
-Repeated calls to
-.BR fts_children ()
-will re-create this linked list.
-.PP
-As a special case, if
-.BR fts_read ()
-has not yet been called for a hierarchy,
-.BR fts_children ()
-will return a pointer to the files in the logical directory specified to
-.BR fts_open (),
-that is, the arguments specified to
-.BR fts_open ().
-Otherwise, if the
-.I FTSENT
-structure most recently returned by
-.BR fts_read ()
-is not a directory being visited in preorder,
-or the directory does not contain any files,
-.BR fts_children ()
-returns
-NULL
-and sets
-.I errno
-to zero.
-If an error occurs,
-.BR fts_children ()
-returns
-NULL
-and sets
-.I errno
-appropriately.
-.PP
-The
-.I FTSENT
-structures returned by
-.BR fts_children ()
-may be overwritten after a call to
-.BR fts_children (),
-.BR fts_close ()
-or
-.BR fts_read ()
-on the same file hierarchy stream.
-.PP
-.I Option
-may be set to the following value:
-.\" .Bl -tag -width FTS_NAMEONLY
-.TP 13
-.BR FTS_NAMEONLY
-Only the names of the files are needed.
-The contents of all the fields in the returned linked list of structures
-are undefined with the exception of the
-.I fts_name
-and
-.I fts_namelen
-fields.
-.\" .El
-.SS fts_set()
-The function
-.BR fts_set ()
-allows the user application to determine further processing for the
-file
-.I f
-of the stream
-.IR ftsp .
-The
-.BR fts_set ()
-function
-returns 0 on success, and \-1 if an error occurs.
-.I Option
-must be set to one of the following values:
-.\" .Bl -tag -width FTS_PHYSICAL
-.TP 13
-.BR FTS_AGAIN
-Revisit the file; any file type may be revisited.
-The next call to
-.BR fts_read ()
-will return the referenced file.
-The
-.I fts_stat
-and
-.I fts_info
-fields of the structure will be reinitialized at that time,
-but no other fields will have been changed.
-This option is meaningful only for the most recently returned
-file from
-.BR fts_read ().
-Normal use is for postorder directory visits, where it causes the
-directory to be revisited (in both preorder and postorder) as well as all
-of its descendants.
-.TP
-.BR FTS_FOLLOW
-The referenced file must be a symbolic link.
-If the referenced file is the one most recently returned by
-.BR fts_read (),
-the next call to
-.BR fts_read ()
-returns the file with the
-.I fts_info
-and
-.I fts_statp
-fields reinitialized to reflect the target of the symbolic link instead
-of the symbolic link itself.
-If the file is one of those most recently returned by
-.BR fts_children (),
-the
-.I fts_info
-and
-.I fts_statp
-fields of the structure, when returned by
-.BR fts_read (),
-will reflect the target of the symbolic link instead of the symbolic link
-itself.
-In either case, if the target of the symbolic link does not exist, the
-fields of the returned structure will be unchanged and the
-.I fts_info
-field will be set to
-.BR FTS_SLNONE .
-.IP
-If the target of the link is a directory, the preorder return, followed
-by the return of all of its descendants, followed by a postorder return,
-is done.
-.TP
-.BR FTS_SKIP
-No descendants of this file are visited.
-The file may be one of those most recently returned by either
-.BR fts_children ()
-or
-.BR fts_read ().
-.\" .El
-.SS fts_close()
-The
-.BR fts_close ()
-function closes a file hierarchy stream
-.I ftsp
-and restores the current directory to the directory from which
-.BR fts_open ()
-was called to open
-.IR ftsp .
-The
-.BR fts_close ()
-function
-returns 0 on success, and \-1 if an error occurs.
-.SH ERRORS
-The function
-.BR fts_open ()
-may fail and set
-.I errno
-for any of the errors specified for
-.BR open (2)
-and
-.BR malloc (3).
-.PP
-The function
-.BR fts_close ()
-may fail and set
-.I errno
-for any of the errors specified for
-.BR chdir (2)
-and
-.BR close (2).
-.PP
-The functions
-.BR fts_read ()
-and
-.BR fts_children ()
-may fail and set
-.I errno
-for any of the errors specified for
-.BR chdir (2),
-.BR malloc (3),
-.BR opendir (3),
-.BR readdir (3),
-and
-.BR stat (2).
-.PP
-In addition,
-.BR fts_children (),
-.BR fts_open (),
-and
-.BR fts_set ()
-may fail and set
-.I errno
-as follows:
-.TP
-.B EINVAL
-The options were invalid.
-.SH VERSIONS
-These functions are available in Linux since glibc2.
-.SH CONFORMING TO
-4.4BSD.
-.SH BUGS
-All of the APIs described in this man page are not safe when compiling
-a program using the LFS APIs (e.g., when compiling with
-.IR -D_FILE_OFFSET_BITS=64 ).
-.\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838
-.\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460
-.\" The following statement is years old, and seems no closer to
-.\" being true -- mtk
-.\" The
-.\" .I fts
-.\" utility is expected to be included in a future
-.\" POSIX.1
-.\" revision.
-.SH SEE ALSO
-.BR find (1),
-.BR chdir (2),
-.BR stat (2),
-.BR ftw (3),
-.BR qsort (3)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
