Fix a few bad .Xr's. Nuke rampant abuse of .Nm.
Clarify examples through the judicious use of .Qq and .Em.
This commit is contained in:
fair
parent
45f41278ec
commit
0047adf48c
@ -1,4 +1,4 @@
|
||||
.\" $NetBSD: getcap.3,v 1.9 1998/04/28 20:11:34 fair Exp $
|
||||
.\" $NetBSD: getcap.3,v 1.10 1998/04/29 19:12:09 fair Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 1992, 1993
|
||||
.\" The Regents of the University of California. All rights reserved.
|
||||
@ -37,7 +37,7 @@
|
||||
.\" @(#)getcap.3 8.4 (Berkeley) 5/13/94
|
||||
.\"
|
||||
.Dd May 13, 1994
|
||||
.Dt GETCAP 3
|
||||
.Dt GETCAP 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm cgetent ,
|
||||
@ -76,7 +76,7 @@
|
||||
.Ft int
|
||||
.Fn cgetclose "void"
|
||||
.Sh DESCRIPTION
|
||||
.Fn Cgetent
|
||||
.Fn cgetent
|
||||
extracts the capability
|
||||
.Fa name
|
||||
from the database specified by the
|
||||
@ -86,14 +86,17 @@ terminated file array
|
||||
and returns a pointer to a
|
||||
.Xr malloc 3 Ns \&'d
|
||||
copy of it in
|
||||
.Fa buf .
|
||||
.Nm Cgetent
|
||||
will first look for files ending in
|
||||
.Nm .db
|
||||
.Fa buf .
|
||||
.Fn cgetent
|
||||
will first look for files ending in
|
||||
.Pa .db
|
||||
(see
|
||||
.Xr cap_mkdb 1 )
|
||||
before accessing the ASCII file.
|
||||
.Fa Buf
|
||||
before accessing the
|
||||
.Tn ASCII
|
||||
file.
|
||||
.Pp
|
||||
.Fa buf
|
||||
must be retained through all subsequent calls to
|
||||
.Fn cgetmatch ,
|
||||
.Fn cgetcap ,
|
||||
@ -103,54 +106,56 @@ and
|
||||
.Fn cgetustr ,
|
||||
but may then be
|
||||
.Xr free 3 Ns \&'d.
|
||||
On success 0 is returned, 1 if the returned
|
||||
record contains an unresolved
|
||||
.Nm 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
|
||||
setting
|
||||
.Va errno ,
|
||||
.Pp
|
||||
On success 0 is returned, 1 if the returned record contains an unresolved
|
||||
.Qq 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 setting
|
||||
.Va errno ,
|
||||
and \-3 if a potential reference loop is detected (see
|
||||
.Ic tc=
|
||||
.Qq tc=name
|
||||
comments below).
|
||||
.Pp
|
||||
.Nm Cgetset
|
||||
.Fn cgetset
|
||||
enables the addition of a character buffer containing a single capability
|
||||
record entry
|
||||
to the capability database.
|
||||
record entry to the capability database.
|
||||
Conceptually, the entry is added as the first ``file'' in the database, and
|
||||
is therefore searched first on the call to
|
||||
.Nm cgetent .
|
||||
The entry is passed in
|
||||
is therefore searched first on the call to
|
||||
.Fn cgetent .
|
||||
The entry is passed in
|
||||
.Fa ent .
|
||||
If
|
||||
.Fa ent
|
||||
If
|
||||
.Fa ent
|
||||
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
|
||||
before the first sequential access call (
|
||||
.Nm cgetfirst
|
||||
the current entry is removed from the database.
|
||||
.Pp
|
||||
.Fn cgetset
|
||||
must precede the database traversal.
|
||||
It must be called before the
|
||||
.Fn cgetent
|
||||
call.
|
||||
If a sequential access is being performed (see below), it must be called
|
||||
before the first sequential access call
|
||||
.Po
|
||||
.Fn cgetfirst
|
||||
or
|
||||
.Nm cgetnext
|
||||
), or be directly preceded by a
|
||||
.Nm cgetclose
|
||||
.Fn cgetnext
|
||||
.Pc ,
|
||||
or be directly preceded by a
|
||||
.Fn cgetclose
|
||||
call.
|
||||
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
|
||||
.Fa buf ,
|
||||
\-1 if
|
||||
not.
|
||||
\-1 if not.
|
||||
.Pp
|
||||
.Nm Cgetcap
|
||||
.Fn cgetcap
|
||||
searches the capability record
|
||||
.Fa buf
|
||||
for the capability
|
||||
@ -159,21 +164,22 @@ with type
|
||||
.Fa type .
|
||||
A
|
||||
.Fa type
|
||||
is specified using any single character. If a colon (`:') is used, an
|
||||
untyped capability will be searched for (see below for explanation of
|
||||
types). A pointer to the value of
|
||||
is specified using any single character.
|
||||
If a colon (`:') 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,
|
||||
.Dv NULL
|
||||
if the requested capability couldn't be
|
||||
found. The end of the capability value is signaled by a `:' or
|
||||
if the requested capability couldn't be found.
|
||||
The end of the capability value is signaled by a `:' 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
|
||||
@ -182,10 +188,10 @@ 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
|
||||
be found.
|
||||
0 is returned on success,
|
||||
\-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
|
||||
@ -204,74 +210,78 @@ 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
|
||||
is identical to
|
||||
.Nm cgetstr
|
||||
.Fn cgetustr
|
||||
is identical to
|
||||
.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 ,
|
||||
comprise a function group that provides for sequential
|
||||
access of the
|
||||
.Fn cgetfirst ,
|
||||
.Fn cgetnext ,
|
||||
comprise a function group that provides for sequential access of the
|
||||
.Dv NULL
|
||||
pointer 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
|
||||
call. If there is no such previous call, the first record in the database is
|
||||
returned.
|
||||
.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 3 Ns \&'d
|
||||
copy pointed to by
|
||||
.Fa buf .
|
||||
.Ic Tc
|
||||
.Xr malloc 3 Ns \&'d
|
||||
copy pointed to by
|
||||
.Fa buf .
|
||||
.Qq tc
|
||||
expansion is done (see
|
||||
.Ic tc=
|
||||
.Qq tc=name
|
||||
comments below).
|
||||
.Pp
|
||||
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
|
||||
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
|
||||
.Qq tc
|
||||
expansion, \-1 is returned if an system error occurred, and \-2
|
||||
is returned if a potential reference loop is detected (see
|
||||
.Ic tc=
|
||||
is returned if a potential reference loop is detected (see
|
||||
.Qq tc=name
|
||||
comments below).
|
||||
Upon completion of database (0 return) the database is closed.
|
||||
.Pp
|
||||
.Nm 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 .
|
||||
.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
|
||||
.Fn cgetset .
|
||||
.Sh 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
|
||||
are ignored. Long lines are usually continued onto several physical
|
||||
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 are ignored.
|
||||
Long lines are usually continued onto several physical
|
||||
lines by ending each line except the last with a `\|\e'.
|
||||
.Pp
|
||||
Capability databases consist of a series of records, one per logical
|
||||
line. Each record contains a variable number of `:'-separated fields
|
||||
(capabilities). Empty fields consisting entirely of white space
|
||||
Capability databases consist of a series of records, one per logical line.
|
||||
Each record contains a variable number of `:'-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 `|'
|
||||
characters. These names are used to reference records in the database.
|
||||
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
|
||||
a lookup tag.
|
||||
For example, the
|
||||
.Em vt100
|
||||
record from the
|
||||
.Nm termcap
|
||||
.Pa termcap
|
||||
database begins:
|
||||
.Pp
|
||||
.Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:"
|
||||
@ -293,30 +303,32 @@ has value
|
||||
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
|
||||
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 `:'.
|
||||
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.
|
||||
.Pp
|
||||
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
|
||||
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
|
||||
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
|
||||
string typed values, but no restriction on those types is enforced. The
|
||||
functions
|
||||
.Nm cgetnum
|
||||
string typed values, but no restriction on those types is enforced.
|
||||
The functions
|
||||
.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 `#' and `='.
|
||||
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:
|
||||
@ -324,40 +336,42 @@ This interpretation is conveniently represented by:
|
||||
.Dl "(getcap(buf, name, ':') != NULL)"
|
||||
.Pp
|
||||
A special capability,
|
||||
.Ic tc= name ,
|
||||
.Qq tc=name ,
|
||||
is used to indicate that the record specified by
|
||||
.Fa name
|
||||
should be substituted for the
|
||||
.Ic tc
|
||||
.Qq tc
|
||||
capability.
|
||||
.Ic Tc
|
||||
.Qq tc
|
||||
capabilities may interpolate records which also contain
|
||||
.Ic tc
|
||||
.Qq tc
|
||||
capabilities and more than one
|
||||
.Ic tc
|
||||
capability may be used in a record. A
|
||||
.Ic tc
|
||||
expansion scope (i.e., where the argument is searched for) contains the
|
||||
.Qq tc
|
||||
capability may be used in a record.
|
||||
A
|
||||
.Qq tc
|
||||
expansion scope (i.e. where the argument is searched for) contains the
|
||||
file in which the
|
||||
.Ic tc
|
||||
.Qq tc
|
||||
is declared and all subsequent files in the file array.
|
||||
.Pp
|
||||
When a database is searched for a capability record, the first matching
|
||||
record in the search is returned. When a record is scanned for a
|
||||
capability, the first matching capability is returned; the capability
|
||||
.Ic :nameT@:
|
||||
record in the search is returned.
|
||||
When a record is scanned for a capability, the first matching
|
||||
capability is returned; the capability
|
||||
.Qq :nameT@:
|
||||
will hide any following definition of a value of type
|
||||
.Em T
|
||||
for
|
||||
.Fa name ;
|
||||
and the capability
|
||||
.Ic :name@:
|
||||
.Qq :name@:
|
||||
will prevent any following values of
|
||||
.Fa name
|
||||
from being seen.
|
||||
.Pp
|
||||
These features combined with
|
||||
.Ic tc
|
||||
.Qq 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.
|
||||
@ -369,8 +383,18 @@ example\||\|an example of binding multiple values to names:\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
|
||||
The capability
|
||||
.Em foo
|
||||
has two values bound to it
|
||||
.Po
|
||||
.Em bar
|
||||
of type `%' and
|
||||
.Em blah
|
||||
of type `^'
|
||||
.Pc
|
||||
and any other value bindings are hidden.
|
||||
The capability
|
||||
.Em abc
|
||||
also has two values bound but only a value of type `$' is prevented from
|
||||
being defined in the capability record more.
|
||||
.Pp
|
||||
@ -384,21 +408,49 @@ file2:
|
||||
.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
|
||||
.Fn cgetent
|
||||
with
|
||||
.Fa file1
|
||||
preceding
|
||||
.Fa file2 .
|
||||
In the capability record
|
||||
.Em new
|
||||
in
|
||||
.Fa file1 ,
|
||||
.Qq fript=bar
|
||||
overrides the definition of
|
||||
.Qq fript=foo
|
||||
interpolated from the capability record
|
||||
.Em old
|
||||
in
|
||||
.Fa file2,
|
||||
.Qq who-cares@
|
||||
prevents the definition of any who-cares definitions in
|
||||
.Em old
|
||||
from being seen,
|
||||
.Qq glork#200
|
||||
is inherited from
|
||||
.Em old ,
|
||||
and
|
||||
.Em blah
|
||||
and anything defined by the record extensions is added to those
|
||||
definitions in
|
||||
.Em old .
|
||||
Note that the position of the
|
||||
.Qq fript=bar
|
||||
and
|
||||
.Qq who-cares@
|
||||
definitions before
|
||||
.Qq tc=old
|
||||
is important here.
|
||||
If they were after, the definitions in
|
||||
.Em old
|
||||
would take precedence.
|
||||
.Sh 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
|
||||
@ -408,7 +460,7 @@ has value
|
||||
.Em number
|
||||
.It Em name No = Em string Ta "string capability"
|
||||
.Em name
|
||||
has value
|
||||
has value
|
||||
.Em string
|
||||
.It Em name No \&#@ Ta "the numeric capability"
|
||||
.Em name
|
||||
@ -430,7 +482,8 @@ Otherwise, if the number starts with a
|
||||
it is interpreted as an octal number.
|
||||
Otherwise the number is interpreted as a decimal number.
|
||||
.Pp
|
||||
String capability values may contain any character. Non-printable
|
||||
String capability values may contain any character.
|
||||
Non-printable
|
||||
.Dv ASCII
|
||||
codes, new lines, and colons may be conveniently represented by the use
|
||||
of escape sequences:
|
||||
@ -449,7 +502,8 @@ of escape sequences:
|
||||
.El
|
||||
.Pp
|
||||
A `\|\e' may be followed by up to three octal digits directly specifies
|
||||
the numeric code for a character. The use of
|
||||
the numeric code for a character.
|
||||
The use of
|
||||
.Tn ASCII
|
||||
.Dv NUL Ns s ,
|
||||
while easily
|
||||
@ -459,41 +513,41 @@ are typically used to denote the end of strings; many applications
|
||||
use `\e\|200' to represent a
|
||||
.Dv NUL .
|
||||
.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 ,
|
||||
and
|
||||
.Nm cgetseq
|
||||
may fail and set
|
||||
.Fn cgetent ,
|
||||
and
|
||||
.Fn cgetseq
|
||||
may fail and set
|
||||
.Va errno
|
||||
for any of the errors specified for the library functions:
|
||||
.Xr fopen 2 ,
|
||||
.Xr fclose 2 ,
|
||||
.Xr fopen 3 ,
|
||||
.Xr fclose 3 ,
|
||||
.Xr open 2 ,
|
||||
and
|
||||
and
|
||||
.Xr close 2 .
|
||||
.Pp
|
||||
.Nm Cgetent ,
|
||||
.Nm cgetset ,
|
||||
.Nm cgetstr ,
|
||||
.Fn cgetent ,
|
||||
.Fn cgetset ,
|
||||
.Fn cgetstr ,
|
||||
and
|
||||
.Nm cgetustr
|
||||
may fail and set
|
||||
.Va errno
|
||||
.Fn cgetustr
|
||||
may fail and set
|
||||
.Va errno
|
||||
as follows:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er ENOMEM
|
||||
@ -506,10 +560,10 @@ No memory to allocate.
|
||||
Colons (`:') can't be used in names, types, or values.
|
||||
.Pp
|
||||
There are no checks for
|
||||
.Ic tc= name
|
||||
.Qq tc=name
|
||||
loops in
|
||||
.Nm cgetent .
|
||||
.Fn cgetent .
|
||||
.Pp
|
||||
The buffer added to the database by a call to
|
||||
.Nm cgetset
|
||||
The buffer added to the database by a call to
|
||||
.Fn cgetset
|
||||
is not unique to the database but is rather prepended to any database used.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user