374 lines
9.2 KiB
Groff
374 lines
9.2 KiB
Groff
.\" $NetBSD: cgetcap.3,v 1.8 2012/04/22 10:13:52 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1992, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" Casey Leedom of Lawrence Livermore National Laboratory.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 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. 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.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)getcap.3 8.4 (Berkeley) 5/13/94
|
|
.\"
|
|
.Dd April 5, 2012
|
|
.Dt CGETCAP 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cgetent ,
|
|
.Nm cgetset ,
|
|
.Nm cgetmatch ,
|
|
.Nm cgetcap ,
|
|
.Nm cgetnum ,
|
|
.Nm cgetstr ,
|
|
.Nm cgetustr ,
|
|
.Nm cgetfirst ,
|
|
.Nm cgetnext ,
|
|
.Nm cgetclose ,
|
|
.Nm cexpandtc
|
|
.Nd capability database access routines
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In stdlib.h
|
|
.Ft int
|
|
.Fn cgetent "char **buf" "const char * const *db_array" "const char *name"
|
|
.Ft int
|
|
.Fn cgetset "const char *ent"
|
|
.Ft int
|
|
.Fn cgetmatch "const char *buf" "const char *name"
|
|
.Ft char *
|
|
.Fn cgetcap "char *buf" "const char *cap" "int type"
|
|
.Ft int
|
|
.Fn cgetnum "char *buf" "const char *cap" "long *num"
|
|
.Ft int
|
|
.Fn cgetstr "char *buf" "const char *cap" "char **str"
|
|
.Ft int
|
|
.Fn cgetustr "char *buf" "const char *cap" "char **str"
|
|
.Ft int
|
|
.Fn cgetfirst "char **buf" "const char * const *db_array"
|
|
.Ft int
|
|
.Fn cgetnext "char **buf" "const char * const *db_array"
|
|
.Ft int
|
|
.Fn cgetclose "void"
|
|
.Ft void
|
|
.Fn csetexpandtc "int expandtc"
|
|
.Sh DESCRIPTION
|
|
.Fn cgetent
|
|
extracts the capability
|
|
.Fa name
|
|
from the database specified by the
|
|
.Dv NULL
|
|
terminated file array
|
|
.Fa db_array
|
|
and returns a pointer to a
|
|
.Xr malloc 3 Ap d
|
|
copy of it in
|
|
.Fa buf .
|
|
.Fn cgetent
|
|
will first look for files ending in
|
|
.Pa .db
|
|
(see
|
|
.Xr cap_mkdb 1 )
|
|
before accessing the
|
|
.Tn ASCII
|
|
file.
|
|
.Pp
|
|
.Fa buf
|
|
must be retained through all subsequent calls to
|
|
.Fn cgetmatch ,
|
|
.Fn cgetcap ,
|
|
.Fn cgetnum ,
|
|
.Fn cgetstr ,
|
|
and
|
|
.Fn cgetustr ,
|
|
but may then be
|
|
.Xr free 3 Ap d .
|
|
.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
|
|
.Qq tc=name
|
|
comments below).
|
|
.Pp
|
|
.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
|
|
.Dq file
|
|
in the database, and
|
|
is therefore searched first on the call to
|
|
.Fn cgetent .
|
|
The entry is passed in
|
|
.Fa ent .
|
|
If
|
|
.Fa ent
|
|
is
|
|
.Dv NULL ,
|
|
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
|
|
.Fn cgetnext
|
|
.Pc ,
|
|
or be directly preceded by a
|
|
.Fn cgetclose
|
|
call.
|
|
On success 0 is returned and \-1 on failure.
|
|
.Pp
|
|
.Fn cgetmatch
|
|
will return 0 if
|
|
.Fa name
|
|
is one of the names of the capability record
|
|
.Fa buf ,
|
|
\-1 if not.
|
|
.Pp
|
|
.Fn cgetcap
|
|
searches the capability record
|
|
.Fa buf
|
|
for the capability
|
|
.Fa cap
|
|
with type
|
|
.Fa type .
|
|
A
|
|
.Fa type
|
|
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,
|
|
.Dv NULL
|
|
if the requested capability couldn't be found.
|
|
The end of the capability value is signaled by a
|
|
.Sq \&: .
|
|
See
|
|
.Xr capfile 5
|
|
for a description of the capability syntax.
|
|
.Pp
|
|
.Fn cgetnum
|
|
retrieves the value of the numeric capability
|
|
.Fa cap
|
|
from the capability record pointed to by
|
|
.Fa buf .
|
|
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.
|
|
.Pp
|
|
.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,
|
|
.Xr malloc 3 Ap d
|
|
copy of the string is returned in the
|
|
.Ft char *
|
|
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
|
|
be found, \-2 if a system error was encountered (storage allocation
|
|
failure).
|
|
.Pp
|
|
.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
|
|
.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 .
|
|
.Fn cgetfirst
|
|
returns the first record in the database and resets the access
|
|
to the first record.
|
|
.Fn cgetnext
|
|
returns the next record in the database with respect to the
|
|
record returned by the previous
|
|
.Fn cgetfirst
|
|
or
|
|
.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 Ap d
|
|
copy pointed to by
|
|
.Fa buf .
|
|
.Qq tc
|
|
expansion is done (see
|
|
.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
|
|
the database yet), 2 is returned if the record contains an unresolved
|
|
.Qq tc
|
|
expansion, \-1 is returned if an system error occurred, and \-2
|
|
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
|
|
.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 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 .
|
|
.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
|
|
.Sq #
|
|
and
|
|
.Sq =
|
|
are conventionally used to denote numeric and
|
|
string typed values, but no restriction on those types is enforced.
|
|
The functions
|
|
.Fn cgetnum
|
|
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:
|
|
.Pp
|
|
.Dl "(getcap(buf, name, ':') != NULL)"
|
|
.Pp
|
|
A special capability,
|
|
.Qq tc=name ,
|
|
is used to indicate that the record specified by
|
|
.Fa name
|
|
should be substituted for the
|
|
.Qq tc
|
|
capability.
|
|
.Qq tc
|
|
capabilities may interpolate records which also contain
|
|
.Qq tc
|
|
capabilities and more than one
|
|
.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
|
|
.Qq tc
|
|
is declared and all subsequent files in the file array.
|
|
.Pp
|
|
.Fn csetexpandtc
|
|
can be used to control if
|
|
.Qq tc
|
|
expansion is performed or not.
|
|
.Sh DIAGNOSTICS
|
|
.Fn cgetent ,
|
|
.Fn cgetset ,
|
|
.Fn cgetmatch ,
|
|
.Fn cgetnum ,
|
|
.Fn cgetstr ,
|
|
.Fn cgetustr ,
|
|
.Fn cgetfirst ,
|
|
and
|
|
.Fn cgetnext
|
|
return a value greater than or equal to 0 on success and a value less
|
|
than 0 on failure.
|
|
.Fn cgetcap
|
|
returns a character pointer on success and a
|
|
.Dv NULL
|
|
on failure.
|
|
.Pp
|
|
.Fn cgetclose ,
|
|
.Fn cgetent ,
|
|
.Fn cgetfirst ,
|
|
and
|
|
.Fn cgetnext
|
|
may fail and set
|
|
.Va errno
|
|
for any of the errors specified for the library functions:
|
|
.Xr fopen 3 ,
|
|
.Xr fclose 3 ,
|
|
.Xr open 2 ,
|
|
and
|
|
.Xr close 2 .
|
|
.Pp
|
|
.Fn cgetent ,
|
|
.Fn cgetset ,
|
|
.Fn cgetstr ,
|
|
and
|
|
.Fn cgetustr
|
|
may fail and set
|
|
.Va errno
|
|
as follows:
|
|
.Bl -tag -width Er
|
|
.It Bq Er ENOMEM
|
|
No memory to allocate.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr cap_mkdb 1 ,
|
|
.Xr malloc 3 ,
|
|
.Xr capfile 5
|
|
.Sh BUGS
|
|
There are no checks for
|
|
.Qq tc=name
|
|
loops in
|
|
.Fn cgetent .
|
|
.Pp
|
|
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.
|