summaryrefslogtreecommitdiffstats
path: root/man3/fts.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/fts.3')
-rw-r--r--man3/fts.3826
1 files changed, 0 insertions, 826 deletions
diff --git a/man3/fts.3 b/man3/fts.3
deleted file mode 100644
index fa33766..0000000
--- a/man3/fts.3
+++ /dev/null
@@ -1,826 +0,0 @@
-'\" t
-.\" $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.
-.\"
-.\" SPDX-License-Identifier: BSD-4-Clause-UC
-.\"
-.\" @(#)fts.3 8.5 (Berkeley) 4/16/94
-.\"
-.\" 2007-12-08, mtk, Converted from mdoc to man macros
-.\"
-.TH fts 3 2024-01-16 "Linux man-pages 6.7"
-.SH NAME
-fts, fts_open, fts_read, fts_children, fts_set, fts_close \- \
-traverse a file hierarchy
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc )
-.SH SYNOPSIS
-.nf
-.B #include <sys/types.h>
-.B #include <sys/stat.h>
-.B #include <fts.h>
-.P
-.BI "FTS *fts_open(char *const *" path_argv ", int " options ,
-.BI " int (*_Nullable " compar ")(const FTSENT **, const FTSENT **));"
-.P
-.BI "FTSENT *fts_read(FTS *" ftsp );
-.P
-.BI "FTSENT *fts_children(FTS *" ftsp ", int " instr );
-.P
-.BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr );
-.P
-.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" (of type
-.IR "FTS\ *" )
-that refers to a file hierarchy "stream".
-This handle 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.
-.P
-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.
-.P
-Two structures (and associated types) are defined in the include file
-.IR <fts.h> .
-The first type is
-.IR FTS ,
-the structure that represents the file hierarchy itself.
-The second type 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.
-.P
-The
-.I FTSENT
-structure contains fields describing a file.
-The structure contains at least the following fields
-(there are additional fields that
-should be considered private to the implementation):
-.P
-.in +4n
-.EX
-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) +
- strlen(fts_name) */
- 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; /* [l]stat(2) information */
-.\" Also:
-.\" ino_t fts_ino; /* inode (only for directories)*/
-.\" dev_t fts_dev; /* device (only for directories)*/
-.\" nlink_t fts_nlink; /* link count (only for directories)*/
-.\" u_short fts_flags; /* private flags for FTSENT structure */
-.\" u_short fts_instr; /* fts_set() instructions */
-} FTSENT;
-.EE
-.in
-.P
-These fields are defined as follows:
-.\" .Bl -tag -width "fts_namelen"
-.TP
-.I fts_info
-One of the following values 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
-.TP
-.B FTS_D
-A directory being visited in preorder.
-.TP
-.B 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
-.B FTS_DEFAULT
-Any
-.I FTSENT
-structure that represents a file type not explicitly described
-by one of the other
-.I fts_info
-values.
-.TP
-.B 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
-.B FTS_DOT
-A file named
-"."
-or
-".."
-which was not specified as a filename to
-.BR fts_open ()
-(see
-.BR FTS_SEEDOT ).
-.TP
-.B 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
-.B FTS_ERR
-This is an error return, and the
-.I fts_errno
-field will be set to indicate what caused the error.
-.TP
-.B FTS_F
-A regular file.
-.TP
-.B FTS_NS
-A file for which no
-.RB [ l ]\c
-.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
-.B FTS_NSOK
-A file for which no
-.RB [ l ]\c
-.BR stat (2)
-information was requested.
-The contents of the
-.I fts_statp
-field are undefined.
-.TP
-.B FTS_SL
-A symbolic link.
-.TP
-.B 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
-.I fts_accpath
-A path for accessing the file from the current directory.
-.TP
-.I 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
-.I fts_pathlen
-The sum of the lengths of the strings referenced by
-.I fts_path
-and
-.IR fts_name .
-.TP
-.I fts_name
-The name of the file.
-.TP
-.I fts_namelen
-The length of the string referenced by
-.IR fts_name .
-.TP
-.I 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
-.I fts_errno
-If
-.BR fts_children ()
-or
-.BR fts_read ()
-returns an
-.I FTSENT
-structure whose
-.I fts_info
-field is set to
-.BR FTS_DNR ,
-.BR FTS_ERR ,
-or
-.BR FTS_NS ,
-the
-.I fts_errno
-field contains the error number (i.e., the
-.I errno
-value)
-specifying the cause of the error.
-Otherwise, the contents of the
-.I fts_errno
-field are undefined.
-.TP
-.I 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
-.I 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
-.I 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 ,
-.IR fts_number ,
-and
-.I fts_pointer
-fields are guaranteed to be initialized.
-.TP
-.I 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
-.I 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
-.I fts_statp
-A pointer to
-.RB [ l ]\c
-.BR stat (2)
-information for the file.
-.\" .El
-.P
-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.
-.P
-There are
-a number of options, at least one of which (either
-.B FTS_LOGICAL
-or
-.BR FTS_PHYSICAL )
-must be specified.
-The options are selected by ORing
-the following values:
-.\" .Bl -tag -width "FTS_PHYSICAL"
-.TP
-.B 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:
-the
-.I fts_statp
-field is obtained via
-.BR stat (2)
-with a fallback to
-.BR lstat (2).
-.TP
-.B 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:
-the
-.I fts_statp
-field is obtained via
-.BR lstat (2).
-.TP
-.B FTS_COMFOLLOW
-This option causes any symbolic link specified as a root path to be
-followed immediately, as if via
-.BR FTS_LOGICAL ,
-regardless of the primary mode.
-.TP
-.B 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.
-This
-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
-.B FTS_NOCHDIR
-is specified and absolute
-pathnames were provided as arguments to
-.BR fts_open ().
-.TP
-.B FTS_NOSTAT
-By default, returned
-.I FTSENT
-structures reference file characteristic information (the
-.I fts_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
-.B FTS_NSOK
-and leave the contents of the
-.I fts_statp
-field undefined.
-.TP
-.B 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
-.B 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
-.P
-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 ,
-.IR 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
-.B 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.)
-.P
-If all the members of the hierarchy have been returned,
-.BR fts_read ()
-returns NULL and sets
-.I errno
-to 0.
-If an error unrelated to a file in the hierarchy occurs,
-.BR fts_read ()
-returns
-NULL
-and sets
-.I errno
-to indicate the error.
-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 ).
-.P
-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.
-.P
-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
-to indicate the error.
-.P
-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.
-.P
-The
-.I instr
-argument is either zero or the following value:
-.\" .Bl -tag -width FTS_NAMEONLY
-.TP
-.B 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.
-.P
-The
-.I instr
-argument is either 0 (meaning "do nothing") or one of the following values:
-.\" .Bl -tag -width FTS_PHYSICAL
-.TP
-.B 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
-.B 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
-.B 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 the file hierarchy stream referred to by
-.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).
-.P
-In addition,
-.BR fts_open ()
-may fail and set
-.I errno
-as follows:
-.TP
-.B ENOENT
-Any element of
-.I path_argv
-was an empty string.
-.P
-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).
-.P
-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
-.RB [ l ]\c
-.BR stat (2).
-.P
-In addition,
-.BR fts_children (),
-.BR fts_open (),
-and
-.BR fts_set ()
-may fail and set
-.I errno
-as follows:
-.TP
-.B EINVAL
-.I options
-or
-.I instr
-was invalid.
-.SH ATTRIBUTES
-For an explanation of the terms used in this section, see
-.BR attributes (7).
-.TS
-allbox;
-lbx lb lb
-l l l.
-Interface Attribute Value
-T{
-.na
-.nh
-.BR fts_open (),
-.BR fts_set (),
-.BR fts_close ()
-T} Thread safety MT-Safe
-T{
-.na
-.nh
-.BR fts_read (),
-.BR fts_children ()
-T} Thread safety MT-Unsafe
-.TE
-.SH STANDARDS
-None.
-.SH HISTORY
-glibc 2.
-4.4BSD.
-.SH BUGS
-Before glibc 2.23,
-.\" Fixed by commit 8b7b7f75d91f7bac323dd6a370aeb3e9c5c4a7d5
-.\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838
-.\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460
-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 ).
-.\"
-.\" 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 lstat (2),
-.BR stat (2),
-.BR ftw (3),
-.BR qsort (3)