summaryrefslogtreecommitdiffstats
path: root/lib/libc/gen/fts.3
diff options
context:
space:
mode:
authorru <ru@FreeBSD.org>2002-12-19 09:40:28 +0000
committerru <ru@FreeBSD.org>2002-12-19 09:40:28 +0000
commit51fe7c1a888747c57136cc34ec54a93a0487b745 (patch)
treef0781cb8e5be3a35234a6d0c123d6ae11ba70e40 /lib/libc/gen/fts.3
parent3424a53ebeadf7ab320c37cf93702953cee94efe (diff)
downloadFreeBSD-src-51fe7c1a888747c57136cc34ec54a93a0487b745.zip
FreeBSD-src-51fe7c1a888747c57136cc34ec54a93a0487b745.tar.gz
mdoc(7) police: "The .Fa argument.".
Diffstat (limited to 'lib/libc/gen/fts.3')
-rw-r--r--lib/libc/gen/fts.372
1 files changed, 36 insertions, 36 deletions
diff --git a/lib/libc/gen/fts.3 b/lib/libc/gen/fts.3
index b50b316..541286d 100644
--- a/lib/libc/gen/fts.3
+++ b/lib/libc/gen/fts.3
@@ -95,25 +95,25 @@ prune and/or re-visit portions of the hierarchy.
Two structures are defined (and typedef'd) in the include file
.Aq Pa fts.h .
The first is
-.Fa FTS ,
+.Vt FTS ,
the structure that represents the file hierarchy itself.
The second is
-.Fa FTSENT ,
+.Vt FTSENT ,
the structure that represents a file in the file
hierarchy.
Normally, an
-.Fa FTSENT
+.Vt FTSENT
structure is returned for every file in the file
hierarchy.
In this manual page,
.Dq file
and
-.Dq Fa FTSENT No structure
+.Dq Vt FTSENT No structure
are generally
interchangeable.
.Pp
The
-.Fa FTS
+.Vt FTS
structure contains space for a single pointer, which may be used to
store application data or per-hierarchy state.
The
@@ -123,7 +123,7 @@ and
functions may be used to set and retrieve this pointer.
This is likely to be useful only when accessed from the sort
comparison function, which can determine the original
-.Fa FTS
+.Vt FTS
stream of its arguments using the
.Fn fts_get_stream
function.
@@ -132,7 +132,7 @@ The two
functions are also available as macros of the same name.
.Pp
The
-.Fa FTSENT
+.Vt FTSENT
structure contains at least the following fields, which are
described in greater detail below:
.Bd -literal
@@ -158,7 +158,7 @@ These fields are defined as follows:
.Bl -tag -width "fts_namelen"
.It Fa fts_info
One of the following values describing the returned
-.Fa FTSENT
+.Vt FTSENT
structure and
the file it represents.
With the exception of directories without errors
@@ -174,11 +174,11 @@ A directory that causes a cycle in the tree.
(The
.Fa fts_cycle
field of the
-.Fa FTSENT
+.Vt FTSENT
structure will be filled in as well.)
.It Dv FTS_DEFAULT
Any
-.Fa FTSENT
+.Vt FTSENT
structure that represents a file type not explicitly described
by one of the other
.Fa fts_info
@@ -200,7 +200,7 @@ which was not specified as a file name to
.It Dv FTS_DP
A directory being visited in post-order.
The contents of the
-.Fa FTSENT
+.Vt FTSENT
structure will be unchanged from when
it was returned in pre-order, i.e. with the
.Fa fts_info
@@ -257,19 +257,19 @@ The length of the string referenced by
The depth of the traversal, numbered from \-1 to N, where this file
was found.
The
-.Fa FTSENT
+.Vt FTSENT
structure representing the parent of the starting point (or root)
of the traversal is numbered
.Dv FTS_ROOTPARENTLEVEL
(\-1), and the
-.Fa FTSENT
+.Vt FTSENT
structure for the root
itself is numbered
.Dv FTS_ROOTLEVEL
(0).
.It Fa fts_errno
Upon return of a
-.Fa FTSENT
+.Vt FTSENT
structure from the
.Fn fts_children
or
@@ -304,7 +304,7 @@ It is initialized to
.Dv NULL .
.It Fa fts_parent
A pointer to the
-.Fa FTSENT
+.Vt FTSENT
structure referencing the file in the hierarchy
immediately above the current file, i.e. the directory of which this
file is a member.
@@ -333,9 +333,9 @@ of a hard link between two directories, or a symbolic link pointing to a
directory, the
.Fa fts_cycle
field of the structure will point to the
-.Fa FTSENT
+.Vt FTSENT
structure in the hierarchy that references the same file as the current
-.Fa FTSENT
+.Vt FTSENT
structure.
Otherwise, the contents of the
.Fa fts_cycle
@@ -358,10 +358,10 @@ fields are guaranteed to be
for the file most recently returned by
.Fn fts_read .
To use these fields to reference any files represented by other
-.Fa FTSENT
+.Vt FTSENT
structures will require that the path buffer be modified using the
information contained in that
-.Fa FTSENT
+.Vt FTSENT
structure's
.Fa fts_pathlen
field.
@@ -400,11 +400,11 @@ is also specified.
This option causes the
.Nm
routines to return
-.Fa FTSENT
+.Vt 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
-.Fa FTSENT
+.Vt FTSENT
structures
are returned to the application are those referencing non-existent files.
Either
@@ -434,7 +434,7 @@ pathnames were provided as arguments to
.Fn fts_open .
.It Dv FTS_NOSTAT
By default, returned
-.Fa FTSENT
+.Vt FTSENT
structures reference file characteristic information (the
.Fa statp
field) for each file visited.
@@ -452,11 +452,11 @@ field undefined.
This option causes the
.Nm
routines to return
-.Fa FTSENT
+.Vt FTSENT
structures for symbolic links themselves instead
of the target files they point to.
If this option is set,
-.Fa FTSENT
+.Vt FTSENT
structures for all symbolic links in the
hierarchy are returned to the application.
Either
@@ -478,7 +478,7 @@ encountered in the file hierarchy are ignored.
This option causes the
.Nm
routines to return
-.Fa FTSENT
+.Vt FTSENT
structures for them.
.It Dv FTS_XDEV
This option prevents
@@ -493,7 +493,7 @@ specifies a user-defined function which may be used to order the traversal
of the hierarchy.
It
takes two pointers to pointers to
-.Fa FTSENT
+.Vt 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
@@ -504,7 +504,7 @@ The
and
.Fa fts_pathlen
fields of the
-.Fa FTSENT
+.Vt FTSENT
structures may
.Em never
be used in this comparison.
@@ -529,7 +529,7 @@ everything else.
The
.Fn fts_read
function returns a pointer to an
-.Fa FTSENT
+.Vt FTSENT
structure describing a file in
the hierarchy.
Directories (that are readable and do not cause cycles) are visited at
@@ -554,14 +554,14 @@ and sets
.Va errno
appropriately.
If an error related to a returned file occurs, a pointer to an
-.Fa FTSENT
+.Vt FTSENT
structure is returned, and
.Va errno
may or may not have been set (see
.Fa fts_info ) .
.Pp
The
-.Fa FTSENT
+.Vt FTSENT
structures returned by
.Fn fts_read
may be overwritten after a call to
@@ -572,7 +572,7 @@ 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
.Fn fts_read
after the
-.Fa FTSENT
+.Vt FTSENT
structure has been returned by the function
.Fn fts_read
in post-order.
@@ -580,16 +580,16 @@ in post-order.
The
.Fn fts_children
function returns a pointer to an
-.Fa FTSENT
+.Vt FTSENT
structure describing the first entry in a NULL-terminated linked list of
the files in the directory represented by the
-.Fa FTSENT
+.Vt FTSENT
structure most recently returned by
.Fn fts_read .
The list is linked through the
.Fa fts_link
field of the
-.Fa FTSENT
+.Vt FTSENT
structure, and is ordered by the user-specified comparison function, if any.
Repeated calls to
.Fn fts_children
@@ -604,7 +604,7 @@ will return a pointer to the files in the logical directory specified to
i.e. the arguments specified to
.Fn fts_open .
Otherwise, if the
-.Fa FTSENT
+.Vt FTSENT
structure most recently returned by
.Fn fts_read
is not a directory being visited in pre-order,
@@ -624,7 +624,7 @@ and sets
appropriately.
.Pp
The
-.Fa FTSENT
+.Vt FTSENT
structures returned by
.Fn fts_children
may be overwritten after a call to
OpenPOWER on IntegriCloud