Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 823 insertions, 0 deletions

diff --git a/man3/fts.3 b/man3/fts.3
new file mode 100644
index 0000000..2a2745c
--- /dev/null
+++ b/man3/fts.3
@@ -0,0 +1,823 @@
+'\" 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 2023-07-20 "Linux man-pages 6.05.01"
+.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>
+.PP
+.BI "FTS *fts_open(char *const *" path_argv ", int " options ,
+.BI "              int (*_Nullable " compar ")(const FTSENT **, const FTSENT **));"
+.PP
+.BI "FTSENT *fts_read(FTS *" ftsp );
+.PP
+.BI "FTSENT *fts_children(FTS *" ftsp ", int " instr );
+.PP
+.BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr );
+.PP
+.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.
+.PP
+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 (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.
+.PP
+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):
+.PP
+.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
+.PP
+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 ] 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 ] 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 ] 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
+.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
+.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 ,
+.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.)
+.PP
+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 ).
+.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
+to indicate the error.
+.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
+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.
+.PP
+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).
+.PP
+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.
+.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
+.RB [ l ] 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
+.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
+.sp 1
+.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)