diff options
Diffstat (limited to 'man3/fts.3')
| -rw-r--r-- | man3/fts.3 | 823 |
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) |