Module Name: src
Committed By: uwe
Date: Mon Oct 28 09:30:50 UTC 2024
Modified Files:
src/lib/libc/gen: fts.3
Log Message:
fts(3): structures are Vt not Fa
To generate a diff of this commit:
cvs rdiff -u -r1.32 -r1.33 src/lib/libc/gen/fts.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/gen/fts.3
diff -u src/lib/libc/gen/fts.3:1.32 src/lib/libc/gen/fts.3:1.33
--- src/lib/libc/gen/fts.3:1.32 Mon Oct 28 01:18:54 2024
+++ src/lib/libc/gen/fts.3 Mon Oct 28 09:30:49 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: fts.3,v 1.32 2024/10/28 01:18:54 jschauma Exp $
+.\" $NetBSD: fts.3,v 1.33 2024/10/28 09:30:49 uwe Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993, 1994
.\" The Regents of the University of California. All rights reserved.
@@ -95,24 +95,24 @@ prune and/or re-visit portions of the hi
Two structures are defined (and typedef'd) in the include file
.In 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.
The
-.Fa FTSENT
+.Vt FTSENT
structure contains at least the following fields, which are
described in greater detail below:
.Bd -literal -offset 2n
@@ -138,7 +138,7 @@ These fields are defined as follows:
.Bl -tag -width "fts_namelen"
.It Fa fts_info
One of the following flags describing the returned
-.Fa FTSENT
+.Vt FTSENT
structure and
the file it represents.
With the exception of directories without errors
@@ -154,11 +154,11 @@ A directory that causes a cycle in the t
(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
@@ -180,7 +180,7 @@ which was not specified as a file name t
.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
@@ -239,15 +239,15 @@ 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 \-1, and the
-.Fa FTSENT
+.Vt FTSENT
structure for the root
itself is numbered 0.
.It Fa fts_errno
Upon return of a
-.Fa FTSENT
+.Vt FTSENT
structure from the
.Fn fts_children
or
@@ -282,7 +282,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.
@@ -312,9 +312,9 @@ of a hard link between two directories,
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
@@ -337,10 +337,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.
@@ -379,11 +379,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
@@ -413,7 +413,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.
@@ -431,11 +431,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
@@ -457,7 +457,7 @@ encountered in the file hierarchy are ig
This option causes the
.Nm
routines to return
-.Fa FTSENT
+.Vt FTSENT
structures for them.
.It Dv FTS_WHITEOUT
Return whiteout entries, which are normally hidden.
@@ -474,7 +474,7 @@ specifies a user-defined function which
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
@@ -485,7 +485,7 @@ The
and
.Fa fts_pathlen
fields of the
-.Fa FTSENT
+.Vt FTSENT
structures may
.Em never
be used in this comparison.
@@ -518,7 +518,7 @@ appropriately.
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
@@ -543,14 +543,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
@@ -561,7 +561,7 @@ on the same file hierarchy stream unless
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.
@@ -569,17 +569,17 @@ in post-order.
The
.Fn fts_children
function returns a pointer to an
-.Fa FTSENT
+.Vt FTSENT
structure describing the first entry in a
.Dv NULL Ns -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
@@ -594,7 +594,7 @@ will return a pointer to the files in th
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,
@@ -614,7 +614,7 @@ and sets
appropriately.
.Pp
The
-.Fa FTSENT
+.Vt FTSENT
structures returned by
.Fn fts_children
may be overwritten after a call to
