summaryrefslogtreecommitdiff
path: root/lib/libc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/libc')
-rw-r--r--lib/libc/gen/basename.314
-rw-r--r--lib/libc/gen/clock.34
-rw-r--r--lib/libc/gen/confstr.315
-rw-r--r--lib/libc/gen/ctermid.38
-rw-r--r--lib/libc/gen/ctype.36
-rw-r--r--lib/libc/gen/devname.313
-rw-r--r--lib/libc/gen/directory.347
-rw-r--r--lib/libc/gen/dirname.326
-rw-r--r--lib/libc/gen/err.319
-rw-r--r--lib/libc/gen/exec.345
-rw-r--r--lib/libc/gen/fnmatch.321
-rw-r--r--lib/libc/gen/ftok.38
-rw-r--r--lib/libc/gen/fts.3182
-rw-r--r--lib/libc/gen/getbsize.319
-rw-r--r--lib/libc/gen/getcap.3302
15 files changed, 410 insertions, 319 deletions
diff --git a/lib/libc/gen/basename.3 b/lib/libc/gen/basename.3
index 543eb2bc0dd..c712fed6613 100644
--- a/lib/libc/gen/basename.3
+++ b/lib/libc/gen/basename.3
@@ -24,7 +24,7 @@
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.\" $OpenBSD: basename.3,v 1.9 1999/05/28 22:00:21 espie Exp $
+.\" $OpenBSD: basename.3,v 1.10 1999/05/29 16:08:54 aaron Exp $
.\"
.Dd August 17, 1997
.Dt BASENAME 3
@@ -52,7 +52,9 @@ characters, a pointer to the string
.Qq \&/
is returned. If
.Ar path
-is a NULL pointer or the empty string, a pointer to the string
+is a
+.Dv NULL
+pointer or the empty string, a pointer to the string
.Qq \&.
is returned.
.Sh RETURN VALUES
@@ -63,7 +65,9 @@ returns a pointer to the last component of
.Pp
If
.Fn basename
-fails, a NULL pointer is returned and the global variable
+fails, a
+.Dv NULL
+pointer is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
@@ -72,7 +76,7 @@ The following error codes may be set in
.Bl -tag -width Er
.It Bq Er ENAMETOOLONG
The path component to be returned was larger than
-.Va MANPATHLEN .
+.Dv MAXPATHLEN .
.El
.Sh WARNINGS
.Fn basename
@@ -93,6 +97,4 @@ The
function first appeared in
.Ox 2.2 .
.Sh AUTHOR
-.nf
Todd C. Miller <Todd.Miller@courtesan.com>
-.fi
diff --git a/lib/libc/gen/clock.3 b/lib/libc/gen/clock.3
index c5acd30f05a..bbc7933e8a3 100644
--- a/lib/libc/gen/clock.3
+++ b/lib/libc/gen/clock.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: clock.3,v 1.2 1996/08/19 08:21:50 tholo Exp $
+.\" $OpenBSD: clock.3,v 1.3 1999/05/29 16:08:54 aaron Exp $
.\"
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -56,7 +56,7 @@ calling process, measured in
The
.Fn clock
function returns the amount of time used unless an error occurs, in which
-case the return value is \-1.
+case the return value is -1.
.Sh SEE ALSO
.Xr getrusage 2
.Sh STANDARDS
diff --git a/lib/libc/gen/confstr.3 b/lib/libc/gen/confstr.3
index 6c4d5f75692..4c79893c58d 100644
--- a/lib/libc/gen/confstr.3
+++ b/lib/libc/gen/confstr.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: confstr.3,v 1.6 1999/05/27 20:49:33 aaron Exp $
+.\" $OpenBSD: confstr.3,v 1.7 1999/05/29 16:08:54 aaron Exp $
.\"
.\" Copyright (c) 1993
.\" The Regents of the University of California. All rights reserved.
@@ -56,7 +56,7 @@ The
.Fa name
argument specifies the system variable to be queried.
Symbolic constants for each name value are found in the include file
-.Li <unistd.h> .
+.Aq Pa unistd.h .
The
.Fa len
argument specifies the size of the buffer referenced by the
@@ -66,13 +66,16 @@ If
.Fa len
is non-zero,
.Fa buf
-is a non-null pointer, and
+is a
+.Pf non- Dv NULL
+pointer, and
.Fa name
-has a value, up to
+has a value; up to
.Fa len
\- 1 bytes of the value are copied into the buffer
.Fa buf .
-The copied value is always null terminated.
+The copied value is always
+.Dv NULL Ns -terminated.
.Pp
The available values are as follows:
.Pp
@@ -104,7 +107,7 @@ was truncated.
The
.Nm
function may fail and set
-.Va error
+.Va errno
for any of the errors specified for the library functions
.Xr malloc 3
and
diff --git a/lib/libc/gen/ctermid.3 b/lib/libc/gen/ctermid.3
index 63f1cec3060..022a835c601 100644
--- a/lib/libc/gen/ctermid.3
+++ b/lib/libc/gen/ctermid.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ctermid.3,v 1.2 1996/08/19 08:22:01 tholo Exp $
+.\" $OpenBSD: ctermid.3,v 1.3 1999/05/29 16:08:54 aaron Exp $
.\"
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -63,8 +63,8 @@ file
.Aq Pa stdio.h )
bytes long.
.Pp
-The current implementation simply returns
-.Ql /dev/tty .
+The current implementation simply generates
+.Qq /dev/tty .
.Sh RETURN VALUES
Upon successful completion, a
.Pf non- Dv NULL
@@ -80,7 +80,7 @@ The current implementation detects no error conditions.
.Xr ttyname 3
.Sh STANDARDS
The
-.Xr ctermid
+.Fn ctermid
function conforms to
.St -p1003.1-88 .
.Sh BUGS
diff --git a/lib/libc/gen/ctype.3 b/lib/libc/gen/ctype.3
index d0b945405e5..4e030fd7ae5 100644
--- a/lib/libc/gen/ctype.3
+++ b/lib/libc/gen/ctype.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ctype.3,v 1.4 1999/05/25 01:13:32 aaron Exp $
+.\" $OpenBSD: ctype.3,v 1.5 1999/05/29 16:08:54 aaron Exp $
.\"
.\" Copyright (c) 1991 Regents of the University of California.
.\" All rights reserved.
@@ -89,9 +89,9 @@
.Fn toascii "int c"
.Sh DESCRIPTION
The above macros perform character tests and conversions on the integer
-.Ar c .
+.Fa c .
.Pp
-See the specific manual pages for more information.
+See each function's own manual page for more information.
.Sh SEE ALSO
.Xr isalnum 3 ,
.Xr isalpha 3 ,
diff --git a/lib/libc/gen/devname.3 b/lib/libc/gen/devname.3
index 447b0c68e12..ffdf7c0ded8 100644
--- a/lib/libc/gen/devname.3
+++ b/lib/libc/gen/devname.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: devname.3,v 1.4 1999/05/23 14:10:59 aaron Exp $
+.\" $OpenBSD: devname.3,v 1.5 1999/05/29 16:08:54 aaron Exp $
.\"
.\" Copyright (c) 1993
.\" The Regents of the University of California. All rights reserved.
@@ -47,15 +47,18 @@ The
.Fn devname
function returns a pointer to the name of the block or character
device in
-.Dq Pa /dev
+.Pa /dev
with a device number of
.Fa dev ,
and a file type matching the one encoded in
.Fa type
-which must be one of S_IFBLK or S_IFCHR.
+which must be one of
+.Dv S_IFBLK
+or
+.Dv S_IFCHR .
If no device matches the specified values, or no information is
-available, the string
-.Dq ??
+available, a pointer to the string
+.Qq ??
is returned.
.Sh SEE ALSO
.Xr stat 2 ,
diff --git a/lib/libc/gen/directory.3 b/lib/libc/gen/directory.3
index e2a1bd97729..1ef21054713 100644
--- a/lib/libc/gen/directory.3
+++ b/lib/libc/gen/directory.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: directory.3,v 1.6 1999/05/23 14:10:59 aaron Exp $
+.\" $OpenBSD: directory.3,v 1.7 1999/05/29 16:08:54 aaron Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -66,24 +66,26 @@ The
function
opens the directory named by
.Fa filename ,
-associates a
-.Em directory stream
+associates a directory stream
with it
and
returns a pointer to be used to identify the
-.Em directory stream
+directory stream
in subsequent operations. The pointer
.Dv NULL
is returned if
.Fa filename
-cannot be accessed, or if it cannot
+cannot be accessed, or if
.Xr malloc 3
-enough memory to hold the whole thing.
+cannot allocate enough memory to hold the entire structure.
.Pp
The
.Fn readdir
function
-returns a pointer to the next directory entry. It returns
+returns a pointer to the next directory entry in the named directory
+stream
+.Fa dirp .
+It returns
.Dv NULL
upon reaching the end of the directory or detecting an invalid
.Fn seekdir
@@ -93,18 +95,18 @@ The
.Fn telldir
function
returns the current location associated with the named
-.Em directory stream .
+directory stream
+.Fa dirp .
.Pp
The
.Fn seekdir
function
sets the position of the next
.Fn readdir
-operation on the
-.Em directory stream .
+operation on the named directory stream
+.Fa dirp .
The new position reverts to the one associated with the
-.Em directory stream
-when the
+directory stream when the
.Fn telldir
operation was performed. Values returned by
.Fn telldir
@@ -127,19 +129,19 @@ The
.Fn rewinddir
function
resets the position of the named
-.Em directory stream
+directory stream
+.Fa dirp
to the beginning of the directory.
.Pp
The
.Fn closedir
function
-closes the named
-.Em directory stream
+closes the named directory stream
and frees the structure associated with the
.Fa dirp
pointer,
returning 0 on success.
-On failure, \-1 is returned and the global variable
+On failure, -1 is returned and the global variable
.Va errno
is set to indicate the error.
.Pp
@@ -147,11 +149,14 @@ The
.Fn dirfd
function
returns the integer file descriptor associated with the named
-.Em directory stream ,
-see
-.Xr open 2 .
-.Pp
-Sample code which searchs a directory for entry ``name'' is:
+directory stream
+.Fa dirp
+(see
+.Xr open 2 ) .
+.Sh EXAMPLES
+Sample code which searches a directory for entry
+.Dq name
+is:
.Bd -literal -offset indent
len = strlen(name);
dirp = opendir(".");
diff --git a/lib/libc/gen/dirname.3 b/lib/libc/gen/dirname.3
index 9a13aa5ede9..0ad1174d499 100644
--- a/lib/libc/gen/dirname.3
+++ b/lib/libc/gen/dirname.3
@@ -24,7 +24,7 @@
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.\" $OpenBSD: dirname.3,v 1.5 1999/05/28 22:00:20 espie Exp $
+.\" $OpenBSD: dirname.3,v 1.6 1999/05/29 16:08:54 aaron Exp $
.\"
.Dd August 17, 1997
.Dt DIRNAME 3
@@ -44,12 +44,20 @@ is the converse of
.Xr basename 3 ;
it returns a pointer to the parent directory of the pathname pointed to by
.Ar path .
-Any trailing '/' characters are not counted as part of the directory
+Any trailing
+.Sq \&/
+characters are not counted as part of the directory
name. If
.Ar path
-is a NULL pointer, the empty string, or contains no '/' characters,
+is a
+.Dv NULL
+pointer, the empty string, or contains no
+.Sq \&/
+characters,
.Fn dirname
-returns a pointer to the string ".", signifying the current directory.
+returns a pointer to the string
+.Qq \&. ,
+signifying the current directory.
.Sh RETURN VALUES
On successful completion,
.Fn dirname
@@ -58,7 +66,9 @@ returns a pointer to the parent directory of
.Pp
If
.Fn dirname
-fails, a NULL pointer is returned and the global variable
+fails, a
+.Dv NULL
+pointer is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
@@ -66,8 +76,8 @@ The following error codes may be set in
.Va errno :
.Bl -tag -width Er
.It Bq Er ENAMETOOLONG
-the path component to be returned was larger than
-.Va MANPATHLEN .
+The path component to be returned was larger than
+.Dv MAXPATHLEN .
.El
.Sh WARNINGS
.Fn dirname
@@ -88,6 +98,4 @@ The
function first appeared in
.Ox 2.2 .
.Sh AUTHOR
-.nf
Todd C. Miller <Todd.Miller@courtesan.com>
-.fi
diff --git a/lib/libc/gen/err.3 b/lib/libc/gen/err.3
index 16ca850d7b2..ab05131218b 100644
--- a/lib/libc/gen/err.3
+++ b/lib/libc/gen/err.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: err.3,v 1.5 1999/05/23 14:10:59 aaron Exp $
+.\" $OpenBSD: err.3,v 1.6 1999/05/29 16:08:54 aaron Exp $
.\"
.\" Copyright (c) 1993
.\" The Regents of the University of California. All rights reserved.
@@ -69,13 +69,16 @@ and
.Fn warn
family of functions display a formatted error message on the standard
error output.
-In all cases, the last component of the program name, a colon character,
-and a space are output.
-If the
-.Va fmt
-argument is not NULL, the formatted error message, a colon character,
-and a space are output. The
-.Va fmt
+In all cases, the last component of the program name, followed by
+a colon
+.Pq Sq \&:
+character and a space, are output, provided
+that
+.Fa fmt
+is not
+.Dv NULL .
+The
+.Fa fmt
argument (and associated arguments) may be any format allowed by
.Xr printf 3
or a simple string.
diff --git a/lib/libc/gen/exec.3 b/lib/libc/gen/exec.3
index a7fbf530681..e1d40d9dfb0 100644
--- a/lib/libc/gen/exec.3
+++ b/lib/libc/gen/exec.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: exec.3,v 1.5 1999/05/16 19:54:51 alex Exp $
+.\" $OpenBSD: exec.3,v 1.6 1999/05/29 16:08:54 aaron Exp $
.\"
.\" Copyright (c) 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -60,7 +60,7 @@
.Sh DESCRIPTION
The
.Nm exec
-family of functions replaces the current process image with a
+family of functions replace the current process image with a
new process image.
The functions described in this manual page are front-ends for the function
.Xr execve 2 .
@@ -79,11 +79,12 @@ and subsequent ellipses in the
and
.Fn execle
functions can be thought of as
-.Em arg0 ,
-.Em arg1 ,
+.Fa arg0 ,
+.Fa arg1 ,
\&...,
-.Em argn .
-Together they describe a list of one or more pointers to null-terminated
+.Fa argn .
+Together they describe a list of one or more pointers to
+.Dv NULL Ns -terminated
strings that represent the argument list available to the executed program.
The first argument, by convention, should point to the file name associated
with the file being executed.
@@ -98,12 +99,14 @@ The
.Fn execv ,
and
.Fn execvp
-functions provide an array of pointers to null-terminated strings that
+functions provide an array of pointers to
+.Dv NULL Ns -terminated
+strings that
represent the argument list available to the new program.
The first argument, by convention, should point to the file name associated
with the file begin executed.
The array of pointers
-.Sy must
+.Em must
be terminated by a
.Dv NULL
pointer.
@@ -116,13 +119,16 @@ functions also specify the environment of the executed process by following
the
.Dv NULL
pointer that terminates the list of arguments in the parameter list
-or the pointer to the argv array with an additional parameter.
-This additional parameter is an array of pointers to null-terminated strings
+or the pointer to the
+.Va argv
+array with an additional parameter.
+This additional parameter is an array of pointers to
+.Dv NULL Ns -terminated strings
and
.Em must
be terminated by a
.Dv NULL
-pointer.
+pointer itself.
The other functions take the environment for the new process image from the
external variable
.Va environ
@@ -136,15 +142,14 @@ and
.Fn execvp
will duplicate the actions of the shell in searching for an executable file
if the specified file name does not contain a slash
-.Dq Li /
+.Pq Sq \&/
character.
The search path is the path specified in the environment by
-.Dq Ev PATH
+.Ev PATH
variable.
If this variable isn't specified, the default path
-.Dq Ev /bin:/usr/bin:
-is
-used.
+.Pa /bin:/usr/bin:\&.
+is used.
In addition, certain errors are treated specially.
.Pp
If permission is denied for a file (the attempted
@@ -180,14 +185,14 @@ executes a file with the program tracing facilities enabled (see
.Sh RETURN VALUES
If any of the
.Xr exec
-functions returns, an error will have occurred.
-The return value is \-1, and the global variable
+functions return, an error has occurred.
+The return value is -1, and the global variable
.Va errno
will be set to indicate the error.
.Sh FILES
.Bl -tag -width /bin/sh -compact
.It Pa /bin/sh
-The shell.
+default shell program
.El
.Sh ERRORS
.Fn execl ,
@@ -222,7 +227,7 @@ Historically, the default path for the
and
.Fn execvp
functions was
-.Dq Pa :/bin:/usr/bin .
+.Pa \&.:/bin:/usr/bin .
This was changed to place the current directory last to enhance system
security.
.Pp
diff --git a/lib/libc/gen/fnmatch.3 b/lib/libc/gen/fnmatch.3
index 69884fafbd2..3fa08fcde77 100644
--- a/lib/libc/gen/fnmatch.3
+++ b/lib/libc/gen/fnmatch.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: fnmatch.3,v 1.5 1999/05/25 13:06:45 aaron Exp $
+.\" $OpenBSD: fnmatch.3,v 1.6 1999/05/29 16:08:55 aaron Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -40,7 +40,7 @@
.Os
.Sh NAME
.Nm fnmatch
-.Nd match filename or pathname using shell glob rules
+.Nd match filename or pathname using shell globbing rules
.Sh SYNOPSIS
.Fd #include <fnmatch.h>
.Ft int
@@ -64,15 +64,14 @@ and
.Fa string .
The value of
.Fa flags
-is the bitwise inclusive
-.Tn OR
+is the bitwise inclusive OR
of any of the following
constants, which are defined in the include file
-.Pa fnmatch.h .
+.Aq Pa fnmatch.h .
.Bl -tag -width FNM_PATHNAME
.It Dv FNM_NOESCAPE
Normally, every occurrence of a backslash
-.Pq Ql \e
+.Pq Sq \e
followed by a character in
.Fa pattern
is replaced by that character.
@@ -97,15 +96,13 @@ The definition of
.Dq leading
is related to the specification of
.Dv FNM_PATHNAME .
-A period is always
-.Dq leading
+A period is always leading
if it is the first character in
-.Ar string .
+.Fa string .
Additionally, if
.Dv FNM_PATHNAME
is set,
-a period is
-.Dq leading
+a period is leading
if it immediately follows a slash.
.It Dv FNM_LEADING_DIR
Ignore
@@ -114,7 +111,7 @@ rest after successful
.Fa pattern
matching.
.It Dv FNM_CASEFOLD
-Ignore case distinctions in both the
+Ignore case distinctions in both the
.Fa pattern
and the
.Fa string .
diff --git a/lib/libc/gen/ftok.3 b/lib/libc/gen/ftok.3
index c9305fba1c1..891aa3acb0e 100644
--- a/lib/libc/gen/ftok.3
+++ b/lib/libc/gen/ftok.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ftok.3,v 1.4 1998/11/15 19:19:55 deraadt Exp $
+.\" $OpenBSD: ftok.3,v 1.5 1999/05/29 16:08:55 aaron Exp $
.\"
.\" Copyright (c) 1994 SigmaSoft, Th. Lockert <tholo@sigmasoft.com>
.\" All rights reserved.
@@ -30,7 +30,7 @@
.Dt ftok 3
.Sh NAME
.Nm ftok
-.Nd create IPC indentifier from path name
+.Nd create IPC indentifier from a pathname
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/ipc.h>
@@ -51,7 +51,7 @@ of an existing file and a user-selectable
.Pp
The specified
.Fa path
-must specify an existing file that is accessible to the calling process
+must refer to an existing file that is accessible to the calling process
or the call will fail. Also, note that links to files will return the
same key, given the same
.Fa id .
@@ -74,9 +74,7 @@ The
function originated with System V and is typically used by programs
that use the System V IPC routines.
.Sh AUTHOR
-.Bl -tag
Thorsten Lockert <tholo@sigmasoft.com>
-.El
.Sh BUGS
The returned key is computed based on the device and inode of the
specified
diff --git a/lib/libc/gen/fts.3 b/lib/libc/gen/fts.3
index 37971a739ba..d036d773df5 100644
--- a/lib/libc/gen/fts.3
+++ b/lib/libc/gen/fts.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: fts.3,v 1.6 1999/05/27 16:20:59 aaron Exp $
+.\" $OpenBSD: fts.3,v 1.7 1999/05/29 16:08:55 aaron Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993, 1994
.\" The Regents of the University of California. All rights reserved.
@@ -50,20 +50,22 @@
.Ft FTSENT *
.Fn fts_children "FTS *ftsp" "int options"
.Ft int
-.Fn fts_set "FTS *ftsp" "FTSENT *f" "int options"
+.Fn fts_set "FTS *ftsp" "FTSENT *f" "int option"
.Ft int
.Fn fts_close "FTS *ftsp"
.Sh DESCRIPTION
The
-.Nm fts
+.Nm
functions are provided for traversing
-.Tn UNIX
+.Ux
file hierarchies.
-A simple overview is that the
+The
.Fn fts_open
-function returns a ``handle'' on a file hierarchy, which is then supplied to
+function returns a
+.Dq handle
+on a file hierarchy, which is then supplied to
the other
-.Nm fts
+.Nm
functions.
The function
.Fn fts_read
@@ -72,34 +74,40 @@ hierarchy.
The function
.Fn 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.
+one of the files contained in a directory within the hierarchy.
+.Pp
In general, directories are visited two distinguishable times; in pre-order
(before any of their descendants are visited) and in post-order (after all
of their descendants have been visited).
Files are visited once.
-It is possible to walk the hierarchy ``logically'' (ignoring symbolic links)
-or physically (visiting symbolic links), order the walk of the hierarchy or
+It is possible to walk the hierarchy
+.Dq logically
+(ignoring symbolic links)
+or physically (visiting symbolic links), order the walk of the hierarchy, or
prune and/or re-visit portions of the hierarchy.
.Pp
Two structures are defined (and typedef'd) in the include file
.Aq Pa fts.h .
The first is
-.Fa FTS ,
+.Dv FTS ,
the structure that represents the file hierarchy itself.
The second is
-.Fa FTSENT ,
+.Dv FTSENT ,
the structure that represents a file in the file
hierarchy.
Normally, an
-.Fa FTSENT
+.Dv FTSENT
structure is returned for every file in the file
hierarchy.
-In this manual page, ``file'' and
-.Dq Fa FTSENT No structure
+In this manual page,
+.Dq file
+and
+.Dq Dv FTSENT No structure
are generally
interchangeable.
+.Pp
The
-.Fa FTSENT
+.Dv FTSENT
structure contains at least the following fields, which are
described in greater detail below:
.Bd -literal
@@ -110,7 +118,7 @@ typedef struct _ftsent {
short fts_pathlen; /* strlen(fts_path) */
char *fts_name; /* file name */
short fts_namelen; /* strlen(fts_name) */
- short fts_level; /* depth (\-1 to N) */
+ short fts_level; /* depth (-1 to N) */
int fts_errno; /* file errno */
long fts_number; /* local numeric value */
void *fts_pointer; /* local address value */
@@ -125,7 +133,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
+.Dv FTSENT
structure and
the file it represents.
With the exception of directories without errors
@@ -141,11 +149,11 @@ A directory that causes a cycle in the tree.
(The
.Fa fts_cycle
field of the
-.Fa FTSENT
+.Dv FTSENT
structure will be filled in as well.)
.It Dv FTS_DEFAULT
Any
-.Fa FTSENT
+.Dv FTSENT
structure that represents a file type not explicitly described
by one of the other
.Fa fts_info
@@ -157,9 +165,9 @@ This is an error return, and the
field will be set to indicate what caused the error.
.It Dv FTS_DOT
A file named
-.Ql \&.
+.Dq \&.
or
-.Ql ..
+.Dq ..
which was not specified as a file name to
.Fn fts_open
(see
@@ -167,9 +175,9 @@ 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
+.Dv FTSENT
structure will be unchanged from when
-it was returned in pre-order, i.e. with the
+it was returned in pre-order, i.e., with the
.Fa fts_info
field set to
.Dv FTS_D .
@@ -221,18 +229,18 @@ The name of the file.
The length of the string referenced by
.Fa fts_name .
.It Fa fts_level
-The depth of the traversal, numbered from \-1 to N, where this file
+The depth of the traversal, numbered from -1 to N, where this file
was found.
The
-.Fa FTSENT
+.Dv FTSENT
structure representing the parent of the starting point (or root)
-of the traversal is numbered \-1, and the
-.Fa FTSENT
+of the traversal is numbered -1, and the
+.Dv FTSENT
structure for the root
itself is numbered 0.
.It Fa fts_errno
-Upon return of a
-.Fa FTSENT
+Upon return of an
+.Dv FTSENT
structure from the
.Fn fts_children
or
@@ -255,21 +263,21 @@ field are undefined.
.It Fa fts_number
This field is provided for the use of the application program and is
not modified by the
-.Nm fts
+.Nm
functions.
It is initialized to 0.
.It Fa fts_pointer
This field is provided for the use of the application program and is
not modified by the
-.Nm fts
+.Nm
functions.
It is initialized to
.Dv NULL .
.It Fa fts_parent
A pointer to the
-.Fa FTSENT
+.Dv FTSENT
structure referencing the file in the hierarchy
-immediately above the current file, i.e. the directory of which this
+immediately above the current file, i.e., the directory of which this
file is a member.
A parent structure for the initial entry point is provided as well,
however, only the
@@ -283,8 +291,9 @@ Upon return from the
.Fn fts_children
function, the
.Fa fts_link
-field points to the next structure in the NULL-terminated linked list of
-directory members.
+field points to the next structure in the
+.Dv NULL Ns -terminated
+linked list of directory members.
Otherwise, the contents of the
.Fa fts_link
field are undefined.
@@ -296,9 +305,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
+.Dv FTSENT
structure in the hierarchy that references the same file as the current
-.Fa FTSENT
+.Dv FTSENT
structure.
Otherwise, the contents of the
.Fa fts_cycle
@@ -316,15 +325,15 @@ Therefore, the
and
.Fa fts_accpath
fields are guaranteed to be
-.Dv NUL Ns -terminated
+.Dv NULL Ns -terminated
.Em only
for the file most recently returned by
.Fn fts_read .
To use these fields to reference any files represented by other
-.Fa FTSENT
+.Dv FTSENT
structures will require that the path buffer be modified using the
information contained in that
-.Fa FTSENT
+.Dv FTSENT
structure's
.Fa fts_pathlen
field.
@@ -334,8 +343,8 @@ are attempted.
The
.Fa fts_name
field is always
-.Dv NUL Ns -terminated.
-.Sh FTS_OPEN
+.Dv NULL Ns -terminated.
+.Ss FTS_OPEN
The
.Fn fts_open
function takes a pointer to an array of character pointers naming one
@@ -350,7 +359,9 @@ a number of options, at least one of which (either
or
.Dv FTS_PHYSICAL )
must be specified.
-The options are selected by
+The
+.Fa options
+are selected by
.Em OR Ns 'ing
the following values:
.Bl -tag -width "FTS_PHYSICAL"
@@ -361,13 +372,13 @@ followed immediately whether or not
is also specified.
.It Dv FTS_LOGICAL
This option causes the
-.Nm fts
+.Nm
routines to return
-.Fa FTSENT
+.Dv 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
+.Dv FTSENT
structures
are returned to the application are those referencing non-existent files.
Either
@@ -380,14 +391,14 @@ be provided to the
function.
.It Dv FTS_NOCHDIR
As a performance optimization, the
-.Nm fts
+.Nm
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.
The
.Dv FTS_NOCHDIR
option turns off this optimization, and the
-.Nm fts
+.Nm
functions will not change the current directory.
Note that applications should not themselves change their current directory
and try to access files unless
@@ -397,13 +408,13 @@ pathnames were provided as arguments to
.Fn fts_open .
.It Dv FTS_NOSTAT
By default, returned
-.Fa FTSENT
+.Dv FTSENT
structures reference file characteristic information (the
.Fa statp
field) for each file visited.
This option relaxes that requirement as a performance optimization,
allowing the
-.Nm fts
+.Nm
functions to set the
.Fa fts_info
field to
@@ -413,13 +424,13 @@ and leave the contents of the
field undefined.
.It Dv FTS_PHYSICAL
This option causes the
-.Nm fts
+.Nm
routines to return
-.Fa FTSENT
+.Dv FTSENT
structures for symbolic links themselves instead
of the target files they point to.
If this option is set,
-.Fa FTSENT
+.Dv FTSENT
structures for all symbolic links in the
hierarchy are returned to the application.
Either
@@ -434,18 +445,18 @@ function.
By default, unless they are specified as path arguments to
.Fn fts_open ,
any files named
-.Ql \&.
+.Dq \&.
or
-.Ql ..
+.Dq ..
encountered in the file hierarchy are ignored.
This option causes the
-.Nm fts
+.Nm
routines to return
-.Fa FTSENT
+.Dv FTSENT
structures for them.
.It Dv FTS_XDEV
This option prevents
-.Nm fts
+.Nm
from descending into directories that have a different device number
than the file from which the descent began.
.It Dv FTS_CHDIRROOT
@@ -456,13 +467,14 @@ starting a new one. The default is to change to the original
starting directory.
.El
.Pp
-The argument
-.Fn compar
+The
+.Fa compar
+argument
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
+.Dv 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
@@ -473,7 +485,7 @@ The
and
.Fa fts_pathlen
fields of the
-.Fa FTSENT
+.Dv FTSENT
structures may
.Em never
be used in this comparison.
@@ -487,18 +499,18 @@ the
.Fa fts_statp
field may not either.
If the
-.Fn compar
+.Fa compar
argument is
.Dv NULL ,
the directory traversal order is in the order listed in
.Fa path_argv
for the root paths, and in the order listed in the directory for
everything else.
-.Sh FTS_READ
+.Ss FTS_READ
The
.Fn fts_read
function returns a pointer to an
-.Fa FTSENT
+.Dv FTSENT
structure describing a file in
the hierarchy.
Directories (that are readable and do not cause cycles) are visited at
@@ -523,14 +535,14 @@ and sets
.Va errno
appropriately.
If an error related to a returned file occurs, a pointer to an
-.Fa FTSENT
+.Dv FTSENT
structure is returned, and
.Va errno
may or may not have been set (see
.Fa fts_info ) .
.Pp
The
-.Fa FTSENT
+.Dv FTSENT
structures returned by
.Fn fts_read
may be overwritten after a call to
@@ -541,24 +553,24 @@ 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
+.Dv FTSENT
structure has been returned by the function
.Fn fts_read
in post-order.
-.Sh FTS_CHILDREN
+.Ss FTS_CHILDREN
The
.Fn fts_children
function returns a pointer to an
-.Fa FTSENT
+.Dv FTSENT
structure describing the first entry in a NULL-terminated linked list of
the files in the directory represented by the
-.Fa FTSENT
+.Dv FTSENT
structure most recently returned by
.Fn fts_read .
The list is linked through the
.Fa fts_link
field of the
-.Fa FTSENT
+.Dv FTSENT
structure, and is ordered by the user-specified comparison function, if any.
Repeated calls to
.Fn fts_children
@@ -570,10 +582,10 @@ has not yet been called for a hierarchy,
.Fn fts_children
will return a pointer to the files in the logical directory specified to
.Fn fts_open ,
-i.e. the arguments specified to
+i.e., the arguments specified to
.Fn fts_open .
Otherwise, if the
-.Fa FTSENT
+.Dv FTSENT
structure most recently returned by
.Fn fts_read
is not a directory being visited in pre-order,
@@ -583,7 +595,7 @@ returns
.Dv NULL
and sets
.Va errno
-to zero.
+to 0.
If an error occurs,
.Fn fts_children
returns
@@ -593,7 +605,7 @@ and sets
appropriately.
.Pp
The
-.Fa FTSENT
+.Dv FTSENT
structures returned by
.Fn fts_children
may be overwritten after a call to
@@ -603,7 +615,7 @@ or
.Fn fts_read
on the same file hierarchy stream.
.Pp
-.Em Option
+.Fa option
may be set to the following value:
.Bl -tag -width FTS_NAMEONLY
.It Dv FTS_NAMEONLY
@@ -615,7 +627,7 @@ and
.Fa fts_namelen
fields.
.El
-.Sh FTS_SET
+.Ss FTS_SET
The function
.Fn fts_set
allows the user application to determine further processing for the
@@ -626,8 +638,8 @@ of the stream
The
.Fn fts_set
function
-returns 0 on success, and \-1 if an error occurs.
-.Em Option
+returns 0 on success or -1 if an error occurred.
+.Fa option
must be set to one of the following values:
.Bl -tag -width FTS_PHYSICAL
.It Dv FTS_AGAIN
@@ -685,7 +697,7 @@ The file may be one of those most recently returned by either
or
.Fn fts_read .
.El
-.Sh FTS_CLOSE
+.Ss FTS_CLOSE
The
.Fn fts_close
function closes a file hierarchy stream
@@ -697,7 +709,7 @@ was called to open
The
.Fn fts_close
function
-returns 0 on success, and \-1 if an error occurs.
+returns 0 on success or -1 if an error occurred.
.Sh ERRORS
The function
.Fn fts_open
@@ -741,7 +753,7 @@ may fail and set
as follows:
.Bl -tag -width Er
.It Bq Er EINVAL
-The options were invalid.
+The specified option is invalid.
.El
.Sh SEE ALSO
.Xr find 1 ,
@@ -750,7 +762,7 @@ The options were invalid.
.Xr qsort 3
.Sh STANDARDS
The
-.Nm fts
+.Nm
utility is expected to be included in a future
.St -p1003.1-88
revision.
diff --git a/lib/libc/gen/getbsize.3 b/lib/libc/gen/getbsize.3
index 2f15b02daeb..aefa6a120c6 100644
--- a/lib/libc/gen/getbsize.3
+++ b/lib/libc/gen/getbsize.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: getbsize.3,v 1.3 1999/05/23 14:10:59 aaron Exp $
+.\" $OpenBSD: getbsize.3,v 1.4 1999/05/29 16:08:55 aaron Exp $
.\"
.\" Copyright (c) 1993
.\" The Regents of the University of California. All rights reserved.
@@ -43,25 +43,28 @@
.Fn getbsize "int *headerlenp" "long *blocksizep"
.Sh DESCRIPTION
The
-.Nm getbsize
+.Fn getbsize
function determines the user's preferred block size based on the value of the
-.Dq BLOCKSIZE
+.Ev BLOCKSIZE
environment variable; see
.Xr environ 7
for details on its use and format.
.Pp
The
-.Nm getbsize
-function returns a pointer to a null-terminated string describing
+.Fn getbsize
+function returns a pointer to a
+.Dv NULL Ns -terminated
+string describing
the block size, something like
-.Dq 1K-blocks .
+.Qq 1K-blocks .
The memory referenced by
.Fa headerlenp
is filled in with the length of the string (not including the
-terminating null).
+terminating
+.Dv NULL ) .
The memory referenced by
.Fa blocksizep
-is filled in with block size, in bytes.
+is filled in with the block size, in bytes.
.Pp
If the user's block size is unreasonable, a warning message is
written to standard error and the returned information reflects
diff --git a/lib/libc/gen/getcap.3 b/lib/libc/gen/getcap.3
index f375a1b5020..19f9d4724aa 100644
--- a/lib/libc/gen/getcap.3
+++ b/lib/libc/gen/getcap.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: getcap.3,v 1.9 1999/05/27 14:12:54 aaron Exp $
+.\" $OpenBSD: getcap.3,v 1.10 1999/05/29 16:08:55 aaron Exp $
.\"
.\" Copyright (c) 1992, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -72,23 +72,26 @@
.Ft int
.Fn cgetclose "void"
.Sh DESCRIPTION
+The
.Fn cgetent
-extracts the capability rec
+function
+extracts the capability record
.Fa name
from the database specified by the
-.Dv NULL
-terminated file array
+.Dv NULL Ns -terminated
+file array
.Fa db_array
and returns a pointer to a
-.Xr malloc Ns \&'d
copy of it in
.Fa buf .
-.Nm cgetent
+.Fn cgetent
will first look for files ending in
-.Nm .db
+.Dq .db
(see
.Xr cap_mkdb 1 )
-before accessing the ASCII file.
+before accessing the
+.Tn ASCII
+version of the capability database.
.Fa buf
must be retained through all subsequent calls to
.Fn cgetmatch ,
@@ -101,23 +104,26 @@ but may then be
.Xr free Ns \&'d.
On success 0 is returned, 1 if the returned
record contains an unresolved
-.Nm tc
+.Ic tc
expansion,
\-1 if the requested record couldn't be found,
-\-2 if a system error was encountered (couldn't open/read a file, etc.) also
+\-2 if a system error occurred (couldn't open or read a file,
+for example) also
setting
.Va errno ,
and \-3 if a potential reference loop is detected (see
.Ic tc=
comments below).
.Pp
-.Nm cgetset
+.Fn cgetset
enables the addition of a character buffer containing a single capability
record entry
to the capability database.
-Conceptually, the entry is added as the first ``file'' in the database, and
+Conceptually, the entry is added as the first
+.Dq file
+in the database, and
is therefore searched first on the call to
-.Nm cgetent .
+.Fn cgetent .
The entry is passed in
.Fa ent .
If
@@ -125,20 +131,20 @@ If
is
.Dv NULL ,
the current entry is removed from the database.
-.Nm cgetset
-must precede the database traversal. It must be called before the
-.Nm cgetent
-call. If a sequential access is being performed (see below), it must be called
+.Fn cgetset
+must precede the database traversal. It must be called before
+.Fn cgetent .
+If a sequential access is being performed (see below), it must be called
before the first sequential access call (
-.Nm cgetfirst
+.Fn cgetfirst
or
-.Nm cgetnext
+.Fn cgetnext
), or be directly preceded by a
-.Nm cgetclose
+.Fn cgetclose
call.
-On success 0 is returned and \-1 on failure.
+On success 0 is returned and -1 on failure.
.Pp
-.Nm cgetmatch
+.Fn cgetmatch
will return 0 if
.Fa name
is one of the names of the capability record
@@ -146,7 +152,7 @@ is one of the names of the capability record
\-1 if
not.
.Pp
-.Nm cgetcap
+.Fn cgetcap
searches the capability record
.Fa buf
for the capability
@@ -155,21 +161,25 @@ with type
.Fa type .
A
.Fa type
-is specified using any single character. If a colon (`:') is used, an
+is specified using any single character. If a colon
+.Pq Sq \&:
+is used, an
untyped capability will be searched for (see below for explanation of
types). A pointer to the value of
.Fa cap
in
.Fa buf
-is returned on success,
+is returned on success or
.Dv NULL
if the requested capability couldn't be
-found. The end of the capability value is signaled by a `:' or
+found. The end of the capability value is signaled by a
+.Sq \&:
+or
.Tn ASCII
.Dv NUL
(see below for capability database syntax).
.Pp
-.Nm cgetnum
+.Fn cgetnum
retrieves the value of the numeric capability
.Fa cap
from the capability record pointed to by
@@ -178,17 +188,16 @@ The numeric value is returned in the
.Ft long
pointed to by
.Fa num .
-0 is returned on success, \-1 if the requested numeric capability couldn't
+On success 0 is returned, -1 if the requested numeric capability couldn't
be found.
.Pp
-.Nm cgetstr
+.Fn cgetstr
retrieves the value of the string capability
.Fa cap
from the capability record pointed to by
.Fa buf .
A pointer to a decoded,
-.Dv NUL
-terminated,
+.Dv NULL Ns -terminated ,
.Xr malloc Ns \&'d
copy of the string is returned in the
.Ft char *
@@ -196,72 +205,82 @@ pointed to by
.Fa str .
The number of characters in the decoded string not including the trailing
.Dv NUL
-is returned on success, \-1 if the requested string capability couldn't
+is returned on success, -1 if the requested string capability couldn't
be found, \-2 if a system error was encountered (storage allocation
failure).
.Pp
-.Nm cgetustr
+.Fn cgetustr
is identical to
-.Nm cgetstr
+.Fn cgetstr
except that it does not expand special characters, but rather returns each
character of the capability string literally.
.Pp
-.Nm cgetfirst ,
-.Nm cgetnext ,
+.Fn cgetfirst
+and
+.Fn cgetnext
comprise a function group that provides for sequential
access of the
-.Dv NULL
-pointer terminated array of file names,
+.Dv NULL Ns -terminated
+array of file names,
.Fa db_array .
-.Nm cgetfirst
+.Fn cgetfirst
returns the first record in the database and resets the access
to the first record.
-.Nm cgetnext
+.Fn cgetnext
returns the next record in the database with respect to the
record returned by the previous
-.Nm cgetfirst
+.Fn cgetfirst
or
-.Nm cgetnext
+.Fn cgetnext
call. If there is no such previous call, the first record in the database is
returned.
Each record is returned in a
.Xr malloc Ns \&'d
copy pointed to by
.Fa buf .
-.Ic Tc
+.Ic tc
expansion is done (see
.Ic tc=
comments below).
Upon completion of the database 0 is returned, 1 is returned upon successful
return of record with possibly more remaining (we haven't reached the end of
the database yet), 2 is returned if the record contains an unresolved
-.Nm tc
-expansion, \-1 is returned if an system error occurred, and \-2
+.Ic tc
+expansion, -1 is returned if an system error occurred, and \-2
is returned if a potential reference loop is detected (see
.Ic tc=
comments below).
Upon completion of database (0 return) the database is closed.
.Pp
-.Nm cgetclose
+.Fn cgetclose
closes the sequential access and frees any memory and file descriptors
being used. Note that it does not erase the buffer pushed by a call to
-.Nm cgetset .
-.Sh CAPABILITY DATABASE SYNTAX
+.Fn cgetset .
+.Ss Capability database syntax
Capability databases are normally
.Tn ASCII
and may be edited with standard
-text editors. Blank lines and lines beginning with a `#' are comments
-and are ignored. Lines ending with a `\|\e' indicate that the next line
-is a continuation of the current line; the `\|\e' and following newline
+text editors. Blank lines and lines beginning with a
+.Sq \&#
+are comments
+and ignored. Lines ending with a
+.Sq \|\e
+indicate that the next line
+is a continuation of the current line; the
+.Sq \|\e
+and following newline
are ignored. Long lines are usually continued onto several physical
-lines by ending each line except the last with a `\|\e'.
+lines by ending each line except the last with a
+.Sq \|\e .
.Pp
Capability databases consist of a series of records, one per logical
-line. Each record contains a variable number of `:'-separated fields
+line. Each record contains a variable number of
+colon-separated fields
(capabilities). Empty fields consisting entirely of white space
characters (spaces and tabs) are ignored.
.Pp
-The first capability of each record specifies its names, separated by `|'
+The first capability of each record specifies its names, separated by
+.Sq \&|
characters. These names are used to reference records in the database.
By convention, the last name is usually a comment and is not intended as
a lookup tag. For example, the
@@ -290,29 +309,48 @@ does not exist
.El
.Pp
Names consist of one or more characters. Names may contain any character
-except `:', but it's usually best to restrict them to the printable
-characters and avoid use of graphics like `#', `=', `%', `@', etc. Types
+except
+.Sq \&: ,
+but it's usually best to restrict them to the printable
+characters and avoid use of graphics like
+.Sq \&# ,
+.Sq \&= ,
+.Sq \&% ,
+.Sq \&@ ,
+etc. Types
are single characters used to separate capability names from their
-associated typed values. Types may be any character except a `:'.
-Typically, graphics like `#', `=', `%', etc. are used. Values may be any
-number of characters and may contain any character except `:'.
-.Sh CAPABILITY DATABASE SEMANTICS
+associated typed values. Types may be any character except a
+.Sq \&: .
+Typically, graphics like
+.Sq \&# ,
+.Sq \&= ,
+.Sq \&% ,
+etc. are used. Values may be any
+number of characters and may contain any character except
+.Sq \&: .
+.Ss Capability database semantics
Capability records describe a set of (name, value) bindings. Names may
have multiple values bound to them. Different values for a name are
distinguished by their
.Fa types .
-.Nm cgetcap
+.Fn cgetcap
will return a pointer to a value of a name given the capability name and
the type of the value.
.Pp
-The types `#' and `=' are conventionally used to denote numeric and
+The types
+.Sq \&#
+and
+.Sq \&=
+are conventionally used to denote numeric and
string typed values, but no restriction on those types is enforced. The
functions
-.Nm cgetnum
+.Fn cgetnum
and
-.Nm cgetstr
-can be used to implement the traditional syntax and semantics of `#'
-and `='.
+.Fn cgetstr
+can be used to implement the traditional syntax and semantics of
+.Sq \&#
+and
+.Sq \&= .
Typeless capabilities are typically used to denote boolean objects with
presence or absence indicating truth and false values respectively.
This interpretation is conveniently represented by:
@@ -326,7 +364,7 @@ is used to indicate that the record specified by
should be substituted for the
.Ic tc
capability.
-.Ic Tc
+.Ic tc
capabilities may interpolate records which also contain
.Ic tc
capabilities and more than one
@@ -356,45 +394,14 @@ These features combined with
.Ic tc
capabilities can be used to generate variations of other databases and
records by either adding new capabilities, overriding definitions with new
-definitions, or hiding following definitions via `@' capabilities.
-.Sh EXAMPLES
-.Bd -unfilled -offset indent
-example\||\|an example of binding multiple values to names:\e
- :foo%bar:foo^blah:foo@:\e
- :abc%xyz:abc^frap:abc$@:\e
- :tc=more:
-.Ed
-.Pp
-The capability foo has two values bound to it (bar of type `%' and blah of
-type `^') and any other value bindings are hidden. The capability abc
-also has two values bound but only a value of type `$' is prevented from
-being defined in the capability record more.
-.Pp
-.Bd -unfilled -offset indent
-file1:
- new\||\|new_record\||\|a modification of "old":\e
- :fript=bar:who-cares@:tc=old:blah:tc=extensions:
-file2:
- old\||\|old_record\||\|an old database record:\e
- :fript=foo:who-cares:glork#200:
-.Ed
-.Pp
-The records are extracted by calling
-.Nm cgetent
-with file1 preceding file2.
-In the capability record new in file1, fript=bar overrides the definition
-of fript=foo interpolated from the capability record old in file2,
-who-cares@ prevents the definition of any who-cares definitions in old
-from being seen, glork#200 is inherited from old, and blah and anything
-defined by the record extensions is added to those definitions in old.
-Note that the position of the fript=bar and who-cares@ definitions before
-tc=old is important here. If they were after, the definitions in old
-would take precedence.
-.Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS
+definitions, or hiding following definitions via
+.Sq \&@
+capabilities.
+.Ss cgetnum() and cgetstr() syntax and semantics
Two types are predefined by
-.Nm cgetnum
+.Fn cgetnum
and
-.Nm cgetstr :
+.Fn cgetstr :
.Bl -column "nameXnumber"
.Sm off
.It Em name No \&# Em number Ta numeric
@@ -444,7 +451,9 @@ of escape sequences:
\e\|\fInnn\fP (ASCII octal \fInnn\fP)
.El
.Pp
-A `\|\e' may be followed by up to three octal digits directly specifies
+A
+.Sq \|\e
+may be followed by up to three octal digits directly specifies
the numeric code for a character. The use of
.Tn ASCII
.Dv NUL Ns s ,
@@ -452,42 +461,83 @@ while easily
encoded, causes all sorts of problems and must be used with care since
.Dv NUL Ns s
are typically used to denote the end of strings; many applications
-use `\e\|200' to represent a
+use
+.Sq \e\|200
+to represent a
.Dv NUL .
+.Sh EXAMPLES
+.Bd -unfilled -offset indent
+example\||\|an example of binding multiple values to names:\e
+ :foo%bar:foo^blah:foo@:\e
+ :abc%xyz:abc^frap:abc$@:\e
+ :tc=more:
+.Ed
+.Pp
+The capability foo has two values bound to it (bar of type
+.Sq \&%
+and blah of
+type
+.Sq \&^ )
+and any other value bindings are hidden. The capability abc
+also has two values bound but only a value of type
+.Sq \&$
+is prevented from
+being defined in the capability record more.
+.Pp
+.Bd -unfilled -offset indent
+file1:
+ new\||\|new_record\||\|a modification of "old":\e
+ :fript=bar:who-cares@:tc=old:blah:tc=extensions:
+file2:
+ old\||\|old_record\||\|an old database record:\e
+ :fript=foo:who-cares:glork#200:
+.Ed
+.Pp
+The records are extracted by calling
+.Fn cgetent
+with file1 preceding file2.
+In the capability record new in file1, fript=bar overrides the definition
+of fript=foo interpolated from the capability record old in file2,
+who-cares@ prevents the definition of any who-cares definitions in old
+from being seen, glork#200 is inherited from old, and blah and anything
+defined by the record extensions is added to those definitions in old.
+Note that the position of the fript=bar and who-cares@ definitions before
+tc=old is important here. If they were after, the definitions in old
+would take precedence.
.Sh DIAGNOSTICS
-.Nm cgetent ,
-.Nm cgetset ,
-.Nm cgetmatch ,
-.Nm cgetnum ,
-.Nm cgetstr ,
-.Nm cgetustr ,
-.Nm cgetfirst ,
+.Fn cgetent ,
+.Fn cgetset ,
+.Fn cgetmatch ,
+.Fn cgetnum ,
+.Fn cgetstr ,
+.Fn cgetustr ,
+.Fn cgetfirst ,
and
-.Nm cgetnext
+.Fn cgetnext
return a value greater than or equal to 0 on success and a value less
than 0 on failure.
-.Nm cgetcap
+.Fn cgetcap
returns a character pointer on success and a
.Dv NULL
on failure.
.Pp
-.Nm cgetent ,
+.Fn cgetent
and
-.Nm cgetset
+.Fn cgetset
may fail and set
.Va errno
-for any of the errors specified for the library functions:
+for any of the errors specified for the library functions
.Xr fopen 3 ,
.Xr fclose 3 ,
.Xr open 2 ,
and
.Xr close 2 .
.Pp
-.Nm cgetent ,
-.Nm cgetset ,
-.Nm cgetstr ,
+.Fn cgetent ,
+.Fn cgetset ,
+.Fn cgetstr ,
and
-.Nm cgetustr
+.Fn cgetustr
may fail and set
.Va errno
as follows:
@@ -499,13 +549,15 @@ No memory to allocate.
.Xr cap_mkdb 1 ,
.Xr malloc 3
.Sh BUGS
-Colons (`:') can't be used in names, types, or values.
+Colon
+.Pq Sq \&:
+characters cannot be used in names, types, or values.
.Pp
There are no checks for
.Ic tc= name
loops in
-.Nm cgetent .
+.Fn cgetent .
.Pp
The buffer added to the database by a call to
-.Nm cgetset
+.Fn cgetset
is not unique to the database but is rather prepended to any database used.
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-23 22:35:38 +0000