version 1.1, 1993/05/18 07:37:53 |
version 1.15, 2003/04/16 13:34:36 |
|
|
.\" Copyright (c) 1992 The Regents of the University of California. |
.\" $NetBSD$ |
.\" All rights reserved. |
.\" |
|
.\" Copyright (c) 1992, 1993 |
|
.\" The Regents of the University of California. All rights reserved. |
.\" |
.\" |
.\" This code is derived from software contributed to Berkeley by |
.\" This code is derived from software contributed to Berkeley by |
.\" Casey Leedom of Lawrence Livermore National Laboratory. |
.\" Casey Leedom of Lawrence Livermore National Laboratory. |
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
.\" SUCH DAMAGE. |
.\" SUCH DAMAGE. |
.\" |
.\" |
.\" @(#)getcap.3 5.4 (Berkeley) 8/11/92 |
.\" @(#)getcap.3 8.4 (Berkeley) 5/13/94 |
.\" |
.\" |
.Dd "August 11, 1992" |
.Dd May 13, 1994 |
.Dt GETCAP 3 |
.Dt GETCAP 3 |
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm cgetent , |
.Nm cgetent , |
|
|
.Nm cgetnext , |
.Nm cgetnext , |
.Nm cgetclose |
.Nm cgetclose |
.Nd capability database access routines |
.Nd capability database access routines |
|
.Sh LIBRARY |
|
.Lb libc |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Fd #include <stdlib.h> |
.In stdlib.h |
.Ft int |
.Ft int |
.Fn cgetent "char **buf" "char **db_array" "char *name" |
.Fn cgetent "char **buf" "char **db_array" "const char *name" |
.Ft int |
.Ft int |
.Fn cgetset "char *ent" |
.Fn cgetset "const char *ent" |
.Ft int |
.Ft int |
.Fn cgetmatch "char *buf" "char *name" |
.Fn cgetmatch "const char *buf" "const char *name" |
.Ft char * |
.Ft char * |
.Fn cgetcap "char *buf" "char *cap" "char type" |
.Fn cgetcap "char *buf" "const char *cap" "int type" |
.Ft int |
.Ft int |
.Fn cgetnum "char *buf" "char *cap" "long *num" |
.Fn cgetnum "char *buf" "const char *cap" "long *num" |
.Ft int |
.Ft int |
.Fn cgetstr "char *buf" "char *cap" "char **str" |
.Fn cgetstr "char *buf" "const char *cap" "char **str" |
.Ft int |
.Ft int |
.Fn cgetustr "char *buf" "char *cap" "char **str" |
.Fn cgetustr "char *buf" "const char *cap" "char **str" |
.Ft int |
.Ft int |
.Fn cgetfirst "char **buf" "char **db_array" |
.Fn cgetfirst "char **buf" "char **db_array" |
.Ft int |
.Ft int |
|
|
.Ft int |
.Ft int |
.Fn cgetclose "void" |
.Fn cgetclose "void" |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
.Fn Cgetent |
.Fn cgetent |
extracts the capability rec |
extracts the capability |
.Fa name |
.Fa name |
from the database specified by the |
from the database specified by the |
.Dv NULL |
.Dv NULL |
terminated file array |
terminated file array |
.Fa db_array |
.Fa db_array |
and returns a pointer to a |
and returns a pointer to a |
.Xr malloc Ns \&'d |
.Xr malloc 3 Ns \&'d |
copy of it in |
copy of it in |
.Fa buf . |
.Fa buf . |
.Nm Cgetent |
.Fn cgetent |
will first look for files ending in |
will first look for files ending in |
.Nm .db |
.Pa .db |
(see |
(see |
.Xr cap_mkdb 1) |
.Xr cap_mkdb 1 ) |
before accessing the ASCII file. |
before accessing the |
.Fa Buf |
.Tn ASCII |
|
file. |
|
.Pp |
|
.Fa buf |
must be retained through all subsequent calls to |
must be retained through all subsequent calls to |
.Fn cgetmatch , |
.Fn cgetmatch , |
.Fn cgetcap , |
.Fn cgetcap , |
Line 98 must be retained through all subsequent |
|
Line 105 must be retained through all subsequent |
|
and |
and |
.Fn cgetustr , |
.Fn cgetustr , |
but may then be |
but may then be |
.Xr free Ns \&'d. |
.Xr free 3 Ns \&'d . |
On success 0 is returned, 1 if the returned |
.Pp |
record contains an unresolved |
On success 0 is returned, 1 if the returned record contains an unresolved |
.Nm tc |
.Qq tc |
expansion, |
expansion, \-1 if the requested record couldn't be found, \-2 if |
\-1 if the requested record couldn't be found, |
a system error was encountered (couldn't open/read a file, etc.) |
\-2 if a system error was encountered (couldn't open/read a file, etc.) also |
also setting |
setting |
.Va errno , |
.Va errno , |
|
and \-3 if a potential reference loop is detected (see |
and \-3 if a potential reference loop is detected (see |
.Ic tc= |
.Qq tc=name |
comments below). |
comments below). |
.Pp |
.Pp |
.Nm Cgetset |
.Fn cgetset |
enables the addition of a character buffer containing a single capability |
enables the addition of a character buffer containing a single capability |
record entry |
record entry to the capability database. |
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 ``file'' in the database, and |
is therefore searched first on the call to |
is therefore searched first on the call to |
.Nm cgetent . |
.Fn cgetent . |
The entry is passed in |
The entry is passed in |
.Fa ent . |
.Fa ent . |
If |
If |
.Fa ent |
.Fa ent |
is |
is |
.Dv NULL , |
.Dv NULL , |
the current entry is removed from the database. |
the current entry is removed from the database. |
.Nm Cgetset |
.Pp |
must precede the database traversal. It must be called before the |
.Fn cgetset |
.Nm cgetent |
must precede the database traversal. |
call. If a sequential access is being performed (see below), it must be called |
It must be called before the |
before the first sequential access call ( |
.Fn cgetent |
.Nm cgetfirst |
call. |
|
If a sequential access is being performed (see below), it must be called |
|
before the first sequential access call |
|
.Po |
|
.Fn cgetfirst |
or |
or |
.Nm cgetnext |
.Fn cgetnext |
), or be directly preceded by a |
.Pc , |
.Nm cgetclose |
or be directly preceded by a |
|
.Fn cgetclose |
call. |
call. |
On success 0 is returned and \-1 on failure. |
On success 0 is returned and \-1 on failure. |
.Pp |
.Pp |
.Nm Cgetmatch |
.Fn cgetmatch |
will return 0 if |
will return 0 if |
.Fa name |
.Fa name |
is one of the names of the capability record |
is one of the names of the capability record |
.Fa buf , |
.Fa buf , |
\-1 if |
\-1 if not. |
not. |
|
.Pp |
.Pp |
.Nm Cgetcap |
.Fn cgetcap |
searches the capability record |
searches the capability record |
.Fa buf |
.Fa buf |
for the capability |
for the capability |
|
|
.Fa type . |
.Fa type . |
A |
A |
.Fa type |
.Fa type |
is specified using any single character. If a colon (`:') is used, an |
is specified using any single character. |
untyped capability will be searched for (see below for explanation of |
If a colon (`:') is used, an untyped capability will be searched |
types). A pointer to the value of |
for (see below for explanation of types). |
|
A pointer to the value of |
.Fa cap |
.Fa cap |
in |
in |
.Fa buf |
.Fa buf |
is returned on success, |
is returned on success, |
.Dv NULL |
.Dv NULL |
if the requested capability couldn't be |
if the requested capability couldn't be found. |
found. The end of the capability value is signaled by a `:' or |
The end of the capability value is signaled by a `:' or |
.Tn ASCII |
.Tn ASCII |
.Dv NUL |
.Dv NUL |
(see below for capability database syntax). |
(see below for capability database syntax). |
.Pp |
.Pp |
.Nm Cgetnum |
.Fn cgetnum |
retrieves the value of the numeric capability |
retrieves the value of the numeric capability |
.Fa cap |
.Fa cap |
from the capability record pointed to by |
from the capability record pointed to by |
Line 178 The numeric value is returned in the |
|
Line 188 The numeric value is returned in the |
|
.Ft long |
.Ft long |
pointed to by |
pointed to by |
.Fa num . |
.Fa num . |
0 is returned on success, \-1 if the requested numeric capability couldn't |
0 is returned on success, |
be found. |
\-1 if the requested numeric capability couldn't be found. |
.Pp |
.Pp |
.Nm Cgetstr |
.Fn cgetstr |
retrieves the value of the string capability |
retrieves the value of the string capability |
.Fa cap |
.Fa cap |
from the capability record pointed to by |
from the capability record pointed to by |
Line 189 from the capability record pointed to by |
|
Line 199 from the capability record pointed to by |
|
A pointer to a decoded, |
A pointer to a decoded, |
.Dv NUL |
.Dv NUL |
terminated, |
terminated, |
.Xr malloc Ns \&'d |
.Xr malloc 3 Ns \&'d |
copy of the string is returned in the |
copy of the string is returned in the |
.Ft char * |
.Ft char * |
pointed to by |
pointed to by |
Line 200 is returned on success, \-1 if the reque |
|
Line 210 is returned on success, \-1 if the reque |
|
be found, \-2 if a system error was encountered (storage allocation |
be found, \-2 if a system error was encountered (storage allocation |
failure). |
failure). |
.Pp |
.Pp |
.Nm Cgetustr |
.Fn cgetustr |
is identical to |
is identical to |
.Nm cgetstr |
.Fn cgetstr |
except that it does not expand special characters, but rather returns each |
except that it does not expand special characters, but rather returns each |
character of the capability string literally. |
character of the capability string literally. |
.Pp |
.Pp |
.Nm Cgetfirst , |
.Fn cgetfirst , |
.Nm cgetnext , |
.Fn cgetnext , |
comprise a function group that provides for sequential |
comprise a function group that provides for sequential access of the |
access of the |
|
.Dv NULL |
.Dv NULL |
pointer terminated array of file names, |
pointer terminated array of file names, |
.Fa db_array . |
.Fa db_array . |
.Nm Cgetfirst |
.Fn cgetfirst |
returns the first record in the database and resets the access |
returns the first record in the database and resets the access |
to the first record. |
to the first record. |
.Nm Cgetnext |
.Fn cgetnext |
returns the next record in the database with respect to the |
returns the next record in the database with respect to the |
record returned by the previous |
record returned by the previous |
.Nm cgetfirst |
.Fn cgetfirst |
or |
or |
.Nm cgetnext |
.Fn cgetnext |
call. If there is no such previous call, the first record in the database is |
call. |
returned. |
If there is no such previous call, |
|
the first record in the database is returned. |
Each record is returned in a |
Each record is returned in a |
.Xr malloc Ns \&'d |
.Xr malloc 3 Ns \&'d |
copy pointed to by |
copy pointed to by |
.Fa buf . |
.Fa buf . |
.Ic Tc |
.Qq tc |
expansion is done (see |
expansion is done (see |
.Ic tc= |
.Qq tc=name |
comments below). |
comments below). |
|
.Pp |
Upon completion of the database 0 is returned, 1 is returned upon successful |
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 |
the database yet), 2 is returned if the record contains an unresolved |
.Nm tc |
.Qq tc |
expansion, \-1 is returned if an system error occured, and \-2 |
expansion, \-1 is returned if an system error occurred, and \-2 |
is returned if a potential reference loop is detected (see |
is returned if a potential reference loop is detected (see |
.Ic tc= |
.Qq tc=name |
comments below). |
comments below). |
Upon completion of database (0 return) the database is closed. |
Upon completion of database (0 return) the database is closed. |
.Pp |
.Pp |
.Nm Cgetclose |
.Fn cgetclose |
closes the sequential access and frees any memory and file descriptors |
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 |
being used. |
.Nm cgetset . |
Note that it does not erase the buffer pushed by a call to |
|
.Fn cgetset . |
.Sh CAPABILITY DATABASE SYNTAX |
.Sh CAPABILITY DATABASE SYNTAX |
Capability databases are normally |
Capability databases are normally |
.Tn ASCII |
.Tn ASCII |
and may be edited with standard |
and may be edited with standard text editors. |
text editors. Blank lines and lines beginning with a `#' are comments |
Blank lines and lines beginning with a `#' are comments and are ignored. |
and are ignored. Lines ending with a `\|\e' indicate that the next line |
Lines ending with a `\|\e' indicate that the next line is a continuation |
is a continuation of the current line; the `\|\e' and following newline |
of the current line; the `\|\e' and following newline are ignored. |
are ignored. Long lines are usually continued onto several physical |
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 `\|\e'. |
.Pp |
.Pp |
Capability databases consist of a series of records, one per logical |
Capability databases consist of a series of records, one per logical line. |
line. Each record contains a variable number of `:'-separated fields |
Each record contains a variable number of `:'-separated fields (capabilities). |
(capabilities). Empty fields consisting entirely of white space |
Empty fields consisting entirely of white space |
characters (spaces and tabs) are ignored. |
characters (spaces and tabs) are ignored. |
.Pp |
.Pp |
The first capability of each record specifies its names, separated by `|' |
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 |
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 |
.Em vt100 |
record from the |
record from the |
.Nm termcap |
.Pa termcap |
database begins: |
database begins: |
.Pp |
.Pp |
.Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:" |
.Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:" |
|
|
does not exist |
does not exist |
.El |
.El |
.Pp |
.Pp |
Names consist of one or more characters. Names may contain any character |
Names consist of one or more characters. |
except `:', but it's usually best to restrict them to the printable |
Names may contain any character except `:', but it's usually best |
characters and avoid use of graphics like `#', `=', `%', `@', etc. Types |
to restrict them to the printable characters and avoid use of |
are single characters used to separate capability names from their |
graphics like `#', `=', `%', `@', etc. |
associated typed values. Types may be any character except a `:'. |
.Pp |
Typically, graphics like `#', `=', `%', etc. are used. Values may be any |
Types are single characters used to separate capability names from |
number of characters and may contain any character except `:'. |
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 |
.Sh CAPABILITY DATABASE SEMANTICS |
Capability records describe a set of (name, value) bindings. Names may |
Capability records describe a set of (name, value) bindings. |
have multiple values bound to them. Different values for a name are |
Names may have multiple values bound to them. |
distinguished by their |
Different values for a name are distinguished by their |
.Fa types . |
.Fa types . |
.Nm Cgetcap |
.Fn cgetcap |
will return a pointer to a value of a name given the capability name and |
will return a pointer to a value of a name given the capability name and |
the type of the value. |
the type of the value. |
.Pp |
.Pp |
The types `#' and `=' are conventionally used to denote numeric and |
The types `#' and `=' are conventionally used to denote numeric and |
string typed values, but no restriction on those types is enforced. The |
string typed values, but no restriction on those types is enforced. |
functions |
The functions |
.Nm cgetnum |
.Fn cgetnum |
and |
and |
.Nm cgetstr |
.Fn cgetstr |
can be used to implement the traditional syntax and semantics of `#' |
can be used to implement the traditional syntax and semantics of `#' and `='. |
and `='. |
|
Typeless capabilities are typically used to denote boolean objects with |
Typeless capabilities are typically used to denote boolean objects with |
presence or absence indicating truth and false values respectively. |
presence or absence indicating truth and false values respectively. |
This interpretation is conveniently represented by: |
This interpretation is conveniently represented by: |
Line 320 This interpretation is conveniently repr |
|
Line 336 This interpretation is conveniently repr |
|
.Dl "(getcap(buf, name, ':') != NULL)" |
.Dl "(getcap(buf, name, ':') != NULL)" |
.Pp |
.Pp |
A special capability, |
A special capability, |
.Ic tc= name , |
.Qq tc=name , |
is used to indicate that the record specified by |
is used to indicate that the record specified by |
.Fa name |
.Fa name |
should be substituted for the |
should be substituted for the |
.Ic tc |
.Qq tc |
capability. |
capability. |
.Ic Tc |
.Qq tc |
capabilities may interpolate records which also contain |
capabilities may interpolate records which also contain |
.Ic tc |
.Qq tc |
capabilities and more than one |
capabilities and more than one |
.Ic tc |
.Qq tc |
capability may be used in a record. A |
capability may be used in a record. |
.Ic tc |
A |
expansion scope (i.e., where the argument is searched for) contains the |
.Qq tc |
|
expansion scope (i.e. where the argument is searched for) contains the |
file in which the |
file in which the |
.Ic tc |
.Qq tc |
is declared and all subsequent files in the file array. |
is declared and all subsequent files in the file array. |
.Pp |
.Pp |
When a database is searched for a capability record, the first matching |
When a database is searched for a capability record, the first matching |
record in the search is returned. When an record is scanned for a |
record in the search is returned. |
capability, the first matching capability is returned; the capability |
When a record is scanned for a capability, the first matching |
.Ic :nameT@: |
capability is returned; the capability |
|
.Qq :nameT@: |
will hide any following definition of a value of type |
will hide any following definition of a value of type |
.Em T |
.Em T |
for |
for |
.Fa name ; |
.Fa name ; |
and the capability |
and the capability |
.Ic :name@: |
.Qq :name@: |
will prevent any following values of |
will prevent any following values of |
.Fa name |
.Fa name |
from being seen. |
from being seen. |
.Pp |
.Pp |
These features combined with |
These features combined with |
.Ic tc |
.Qq tc |
capabilities can be used to generate variations of other databases and |
capabilities can be used to generate variations of other databases and |
records by either adding new capabilities, overriding definitions with new |
records by either adding new capabilities, overriding definitions with new |
definitions, or hiding following definitions via `@' capabilities. |
definitions, or hiding following definitions via `@' capabilities. |
Line 365 example\||\|an example of binding multip |
|
Line 383 example\||\|an example of binding multip |
|
:tc=more: |
:tc=more: |
.Ed |
.Ed |
.Pp |
.Pp |
The capability foo has two values bound to it (bar of type `%' and blah of |
The capability |
type `^') and any other value bindings are hidden. The capability abc |
.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 |
also has two values bound but only a value of type `$' is prevented from |
being defined in the capability record more. |
being defined in the capability record more. |
.Pp |
.Pp |
|
|
.Ed |
.Ed |
.Pp |
.Pp |
The records are extracted by calling |
The records are extracted by calling |
.Nm cgetent |
.Fn cgetent |
with file1 preceding file2. |
with |
In the capability record new in file1, fript=bar overrides the definition |
.Fa file1 |
of fript=foo interpolated from the capability record old in file2, |
preceding |
who-cares@ prevents the definition of any who-cares definitions in old |
.Fa file2 . |
from being seen, glork#200 is inherited from old, and blah and anything |
In the capability record |
defined by the record extensions is added to those definitions in old. |
.Em new |
Note that the position of the fript=bar and who-cares@ definitions before |
in |
tc=old is important here. If they were after, the definitions in old |
.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. |
would take precedence. |
.Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS |
.Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS |
Two types are predefined by |
Two types are predefined by |
.Nm cgetnum |
.Fn cgetnum |
and |
and |
.Nm cgetstr : |
.Fn cgetstr : |
.Bl -column "nameXnumber" |
.Bl -column "nameXnumber" |
.Sm off |
.Sm off |
.It Em name No \&# Em number Ta numeric |
.It Em name No \&# Em number Ta numeric |
|
|
.Em number |
.Em number |
.It Em name No = Em string Ta "string capability" |
.It Em name No = Em string Ta "string capability" |
.Em name |
.Em name |
has value |
has value |
.Em string |
.Em string |
.It Em name No \&#@ Ta "the numeric capability" |
.It Em name No \&#@ Ta "the numeric capability" |
.Em name |
.Em name |
Line 426 Otherwise, if the number starts with a |
|
Line 482 Otherwise, if the number starts with a |
|
it is interpreted as an octal number. |
it is interpreted as an octal number. |
Otherwise the number is interpreted as a decimal number. |
Otherwise the number is interpreted as a decimal number. |
.Pp |
.Pp |
String capability values may contain any character. Non-printable |
String capability values may contain any character. |
|
Non-printable |
.Dv ASCII |
.Dv ASCII |
codes, new lines, and colons may be conveniently represented by the use |
codes, new lines, and colons may be conveniently represented by the use |
of escape sequences: |
of escape sequences: |
.Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)" |
.Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)" |
^X ('\fIX\fP' & 037) control-\fIX\fP |
^X ('\fIX\fP' \*[Am] 037) control-\fIX\fP |
\e\|b, \e\|B (ASCII 010) backspace |
\e\|b, \e\|B (ASCII 010) backspace |
\e\|t, \e\|T (ASCII 011) tab |
\e\|t, \e\|T (ASCII 011) tab |
\e\|n, \e\|N (ASCII 012) line feed (newline) |
\e\|n, \e\|N (ASCII 012) line feed (newline) |
Line 445 of escape sequences: |
|
Line 502 of escape sequences: |
|
.El |
.El |
.Pp |
.Pp |
A `\|\e' may be followed by up to three octal digits directly specifies |
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 |
.Tn ASCII |
.Dv NUL Ns s , |
.Dv NUL Ns s , |
while easily |
while easily |
Line 455 are typically used to denote the end of |
|
Line 513 are typically used to denote the end of |
|
use `\e\|200' to represent a |
use `\e\|200' to represent a |
.Dv NUL . |
.Dv NUL . |
.Sh DIAGNOSTICS |
.Sh DIAGNOSTICS |
.Nm Cgetent , |
.Fn cgetent , |
.Nm cgetset , |
.Fn cgetset , |
.Nm cgetmatch , |
.Fn cgetmatch , |
.Nm cgetnum , |
.Fn cgetnum , |
.Nm cgetstr , |
.Fn cgetstr , |
.Nm cgetustr , |
.Fn cgetustr , |
.Nm cgetfirst , |
.Fn cgetfirst , |
and |
and |
.Nm cgetnext |
.Fn cgetnext |
return a a value greater than or equal to 0 on success and a value less |
return a value greater than or equal to 0 on success and a value less |
than 0 on failure. |
than 0 on failure. |
.Nm Cgetcap |
.Fn cgetcap |
returns a character pointer on success and a |
returns a character pointer on success and a |
.Dv NULL |
.Dv NULL |
on failure. |
on failure. |
.Pp |
.Pp |
.Nm Cgetent , |
.Fn cgetent , |
and |
and |
.Nm cgetseq |
.Fn cgetseq |
may fail and set |
may fail and set |
.Va errno |
.Va errno |
for any of the errors specified for the library functions: |
for any of the errors specified for the library functions: |
.Xr fopen 2 , |
.Xr fopen 3 , |
.Xr fclose 2 , |
.Xr fclose 3 , |
.Xr open 2 , |
.Xr open 2 , |
and |
and |
.Xr close 2 . |
.Xr close 2 . |
.Pp |
.Pp |
.Nm Cgetent , |
.Fn cgetent , |
.Nm cgetset , |
.Fn cgetset , |
.Nm cgetstr , |
.Fn cgetstr , |
and |
and |
.Nm cgetustr |
.Fn cgetustr |
may fail and set |
may fail and set |
.Va errno |
.Va errno |
as follows: |
as follows: |
.Bl -tag -width Er |
.Bl -tag -width Er |
.It Bq Er ENOMEM |
.It Bq Er ENOMEM |
Line 502 No memory to allocate. |
|
Line 560 No memory to allocate. |
|
Colons (`:') can't be used in names, types, or values. |
Colons (`:') can't be used in names, types, or values. |
.Pp |
.Pp |
There are no checks for |
There are no checks for |
.Ic tc= name |
.Qq tc=name |
loops in |
loops in |
.Nm cgetent . |
.Fn cgetent . |
.Pp |
.Pp |
The buffer added to the database by a call to |
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. |
is not unique to the database but is rather prepended to any database used. |