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