.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the University of
-.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\" SUCH DAMAGE.
.\"
.\" @(#)getcap.3 8.4 (Berkeley) 5/13/94
-.\" $FreeBSD: src/lib/libc/gen/getcap.3,v 1.23 2002/12/30 21:18:02 schweikh Exp $
+.\" $FreeBSD: src/lib/libc/gen/getcap.3,v 1.30 2007/02/11 18:14:49 maxim Exp $
.\"
-.Dd May 13, 1994
+.Dd March 22, 2002
.Dt GETCAP 3
.Os
.Sh NAME
.Sh SYNOPSIS
.In stdlib.h
.Ft int
-.Fn cgetent "char **buf" "char **db_array" "char *name"
+.Fn cgetent "char **buf" "char **db_array" "const char *name"
.Ft int
-.Fn cgetset "char *ent"
+.Fn cgetset "const char *ent"
.Ft int
-.Fn cgetmatch "char *buf" "char *name"
+.Fn cgetmatch "const char *buf" "const char *name"
.Ft char *
-.Fn cgetcap "char *buf" "char *cap" "int type"
+.Fn cgetcap "char *buf" "const char *cap" "int type"
.Ft int
-.Fn cgetnum "char *buf" "char *cap" "long *num"
+.Fn cgetnum "char *buf" "const char *cap" "long *num"
.Ft int
-.Fn cgetstr "char *buf" "char *cap" "char **str"
+.Fn cgetstr "char *buf" "const char *cap" "char **str"
.Ft int
-.Fn cgetustr "char *buf" "char *cap" "char **str"
+.Fn cgetustr "char *buf" "const char *cap" "char **str"
.Ft int
.Fn cgetfirst "char **buf" "char **db_array"
.Ft int
record contains an unresolved
.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
+\-1 if the requested record could not be found,
+\-2 if a system error was encountered (could not open/read a file, etc.) also
setting
.Va errno ,
and \-3 if a potential reference loop is detected (see
the current entry is removed from the database.
A call to
.Fn cgetset
-must precede the database traversal. It must be called before the
+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
+call.
+If a sequential access is being performed (see below), it must be called
before the first sequential access call
.Fn ( cgetfirst
or
.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 (`:') is used, an
untyped capability will be searched for (see below for explanation of
-types). A pointer to the value 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 could not be
+found.
+The end of the capability value is signaled by a `:' or
.Tn ASCII
.Dv NUL
(see below for capability database syntax).
.Ft long
pointed to by
.Fa num .
-0 is returned on success, \-1 if the requested numeric capability couldn't
+0 is returned on success, \-1 if the requested numeric capability could not
be found.
.Pp
The
.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 could not
be found, \-2 if a system error was encountered (storage allocation
failure).
.Pp
.Fn cgetfirst
or
.Fn cgetnext
-call. If there is no such previous call, the first record in the database is
+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
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
+Upon completion of the database 0 is returned, 1 is returned upon successful
+return of record with possibly more remaining (we have not reached the end of
the database yet), 2 is returned if the record contains an unresolved
.Ic tc
expansion, \-1 is returned if a system error occurred, and \-2
The
.Fn cgetclose
function 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.
+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
+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
+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
+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
.Xr termcap 5
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
+Names consist of one or more characters.
+Names may contain any character
+except `:', but it is 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
+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
+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 .
The
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
+string typed values, but no restriction on those types is enforced.
+The
functions
.Fn cgetnum
and
.Ic tc
capabilities and more than one
.Ic tc
-capability may be used in a record. A
+capability may be used in a record.
+A
.Ic tc
expansion scope (i.e., where the argument is searched for) contains the
file in which the
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
+record in the search is returned.
+When a record is scanned for a
capability, the first matching capability is returned; the capability
.Ic :nameT@:
will hide any following definition of a value of type
.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
+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
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
+tc=old is important here.
+If they were after, the definitions in old
would take precedence.
.Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS
Two types are predefined by
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:
.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
The
.Fn cgetent ,
and
-.Fn cgetseq
+.Fn cgetset
functions may fail and set
.Va errno
for any of the errors specified for the library functions:
.Xr cap_mkdb 1 ,
.Xr malloc 3
.Sh BUGS
-Colons (`:') can't be used in names, types, or values.
+Colons (`:') cannot be used in names, types, or values.
.Pp
There are no checks for
.Ic tc Ns = Ns Ic name
projects / apple / libc.git / blobdiff