4.4BSD/usr/share/man/cat3/cgetmatch.0
GETCAP(3) BSD Programmer's Manual GETCAP(3)
NNAAMMEE
ccggeetteenntt, ccggeettsseett, ccggeettmmaattcchh, ccggeettccaapp, ccggeettnnuumm, ccggeettssttrr, ccggeettuussttrr,
ccggeettffiirrsstt, ccggeettnneexxtt, ccggeettcclloossee - capability database access routines
SSYYNNOOPPSSIISS
##iinncclluuddee <<ssttddlliibb..hh>>
_i_n_t
ccggeetteenntt(_c_h_a_r _*_*_b_u_f, _c_h_a_r _*_*_d_b___a_r_r_a_y, _c_h_a_r _*_n_a_m_e);
_i_n_t
ccggeettsseett(_c_h_a_r _*_e_n_t);
_i_n_t
ccggeettmmaattcchh(_c_h_a_r _*_b_u_f, _c_h_a_r _*_n_a_m_e);
_c_h_a_r _*
ccggeettccaapp(_c_h_a_r _*_b_u_f, _c_h_a_r _*_c_a_p, _c_h_a_r _t_y_p_e);
_i_n_t
ccggeettnnuumm(_c_h_a_r _*_b_u_f, _c_h_a_r _*_c_a_p, _l_o_n_g _*_n_u_m);
_i_n_t
ccggeettssttrr(_c_h_a_r _*_b_u_f, _c_h_a_r _*_c_a_p, _c_h_a_r _*_*_s_t_r);
_i_n_t
ccggeettuussttrr(_c_h_a_r _*_b_u_f, _c_h_a_r _*_c_a_p, _c_h_a_r _*_*_s_t_r);
_i_n_t
ccggeettffiirrsstt(_c_h_a_r _*_*_b_u_f, _c_h_a_r _*_*_d_b___a_r_r_a_y);
_i_n_t
ccggeettnneexxtt(_c_h_a_r _*_*_b_u_f, _c_h_a_r _*_*_d_b___a_r_r_a_y);
_i_n_t
ccggeettcclloossee(_v_o_i_d);
DDEESSCCRRIIPPTTIIOONN
CCggeetteenntt() extracts the capability rec _n_a_m_e from the database specified by
the NULL terminated file array _d_b___a_r_r_a_y and returns a pointer to a
malloc'd copy of it in _b_u_f. CCggeetteenntt will first look for files ending in
..ddbb (see cap_mkdb(1)) before accessing the ASCII file. _B_u_f must be re-
tained through all subsequent calls to ccggeettmmaattcchh(), ccggeettccaapp(), ccggeettnnuumm(),
ccggeettssttrr(), and ccggeettuussttrr(), but may then be free'd. On success 0 is re-
turned, 1 if the returned record contains an unresolved ttcc expansion, -1
if the requested record couldn't be found, -2 if a system error was en-
countered (couldn't open/read a file, etc.) also setting _e_r_r_n_o, and -3 if
a potential reference loop is detected (see ttcc== comments below).
CCggeettsseett 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 is therefore
searched first on the call to ccggeetteenntt. The entry is passed in _e_n_t. If _e_n_t
is NULL, the current entry is removed from the database. CCggeettsseett must
precede the database traversal. It must be called before the ccggeetteenntt
call. If a sequential access is being performed (see below), it must be
called before the first sequential access call ( ccggeettffiirrsstt or ccggeettnneexxtt ),
or be directly preceded by a ccggeettcclloossee call. On success 0 is returned
and -1 on failure.
CCggeettmmaattcchh will return 0 if _n_a_m_e is one of the names of the capability
record _b_u_f, -1 if not.
CCggeettccaapp searches the capability record _b_u_f for the capability _c_a_p with
type _t_y_p_e. A _t_y_p_e 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 _c_a_p in _b_u_f is returned
on success, NULL if the requested capability couldn't be found. The end
of the capability value is signaled by a `:' or ASCII NUL (see below for
capability database syntax).
CCggeettnnuumm retrieves the value of the numeric capability _c_a_p from the capa-
bility record pointed to by _b_u_f. The numeric value is returned in the
_l_o_n_g pointed to by _n_u_m. 0 is returned on success, -1 if the requested nu-
meric capability couldn't be found.
CCggeettssttrr retrieves the value of the string capability _c_a_p from the capa-
bility record pointed to by _b_u_f. A pointer to a decoded, NUL terminated,
malloc'd copy of the string is returned in the _c_h_a_r _* pointed to by _s_t_r.
The number of characters in the decoded string not including the trailing
NUL is returned on success, -1 if the requested string capability
couldn't be found, -2 if a system error was encountered (storage alloca-
tion failure).
CCggeettuussttrr is identical to ccggeettssttrr except that it does not expand special
characters, but rather returns each character of the capability string
literally.
CCggeettffiirrsstt, ccggeettnneexxtt, comprise a function group that provides for sequen-
tial access of the NULL pointer terminated array of file names, _d_b___a_r_r_a_y.
CCggeettffiirrsstt returns the first record in the database and resets the access
to the first record. CCggeettnneexxtt returns the next record in the database
with respect to the record returned by the previous ccggeettffiirrsstt or ccggeettnneexxtt
call. If there is no such previous call, the first record in the
database is returned. Each record is returned in a malloc'd copy point-
ed to by _b_u_f. TTcc expansion is done (see ttcc== comments below). Upon com-
pletion of the database 0 is returned, 1 is returned upon successful re-
turn 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
ttcc expansion, -1 is returned if an system error occured, and -2 is re-
turned if a potential reference loop is detected (see ttcc== comments be-
low). Upon completion of database (0 return) the database is closed.
CCggeettcclloossee closes the sequential access and frees any memory and file de-
scriptors being used. Note that it does not erase the buffer pushed by a
call to ccggeettsseett.
CCAAPPAABBIILLIITTYY DDAATTAABBAASSEE SSYYNNTTAAXX
Capability databases are normally 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 `\' indicate that the next line is
a continuation of the current line; the `\' and following newline are ig-
nored. Long lines are usually continued onto several physical lines by
ending each line except the last with a `\'.
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 charac-
ters (spaces and tabs) are ignored.
The first capability of each record specifies its names, separated by `|'
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 _v_t_1_0_0 record from the tteerrmmccaapp database
begins:
d0|vt100|vt100-am|vt100am|dec vt100:
giving four names that can be used to access the record.
The remaining non-empty capabilities describe a set of (name, value)
bindings, consisting of a names optionally followed by a typed values:
name typeless [boolean] capability _n_a_m_e is present [true]
name_Tvalue capability (_n_a_m_e, _T) has value _v_a_l_u_e
name@ no capability _n_a_m_e exists
name_T@ capability (_n_a_m_e, _T) does not exist
Names consist of one or more characters. Names may contain any character
except `:', but it's usually best to restrict them to the printable char-
acters 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 `:'.
CCAAPPAABBIILLIITTYY DDAATTAABBAASSEE SSEEMMAANNTTIICCSS
Capability records describe a set of (name, value) bindings. Names may
have multiple values bound to them. Different values for a name are dis-
tinguished by their _t_y_p_e_s. CCggeettccaapp will return a pointer to a value of a
name given the capability name and the type of the value.
The types `#' and `=' are conventionally used to denote numeric and
string typed values, but no restriction on those types is enforced. The
functions ccggeettnnuumm and ccggeettssttrr 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 rep-
resented by:
(getcap(buf, name, ':') != NULL)
A special capability, ttcc== nnaammee, is used to indicate that the record spec-
ified by _n_a_m_e should be substituted for the ttcc capability. TTcc capabili-
ties may interpolate records which also contain ttcc capabilities and more
than one ttcc capability may be used in a record. A ttcc expansion scope
(i.e., where the argument is searched for) contains the file in which the
ttcc is declared and all subsequent files in the file array.
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 capa-
bility, the first matching capability is returned; the capability
::nnaammeeTT@@:: will hide any following definition of a value of type _T for
_n_a_m_e; and the capability ::nnaammee@@:: will prevent any following values of
_n_a_m_e from being seen.
These features combined with ttcc capabilities can be used to generate
variations of other databases and records by either adding new capabili-
ties, overriding definitions with new definitions, or hiding following
definitions via `@' capabilities.
EEXXAAMMPPLLEESS
example|an example of binding multiple values to names:\
:foo%bar:foo^blah:foo@:\
:abc%xyz:abc^frap:abc$@:\
:tc=more:
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.
file1:
new|new_record|a modification of "old":\
:fript=bar:who-cares@:tc=old:blah:tc=extensions:
file2:
old|old_record|an old database record:\
:fript=foo:who-cares:glork#200:
The records are extracted by calling ccggeetteenntt 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 de-
fined 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.
CCGGEETTNNUUMM AANNDD CCGGEETTSSTTRR SSYYNNTTAAXX AANNDD SSEEMMAANNTTIICCSS
Two types are predefined by ccggeettnnuumm and ccggeettssttrr:
_n_a_m_e#_n_u_m_b_e_r numeric capability _n_a_m_e has value _n_u_m_b_e_r
_n_a_m_e=_s_t_r_i_n_g string capability _n_a_m_e has value _s_t_r_i_n_g
_n_a_m_e#@ the numeric capability _n_a_m_e does not exist
_n_a_m_e=@ the string capability _n_a_m_e does not exist
Numeric capability values may be given in one of three numeric bases. If
the number starts with either `0x' or `0X' it is interpreted as a hex-
adecimal number (both upper and lower case a-f may be used to denote the
extended hexadecimal digits). Otherwise, if the number starts with a `0'
it is interpreted as an octal number. Otherwise the number is interpret-
ed as a decimal number.
String capability values may contain any character. Non-printable ASCII
codes, new lines, and colons may be conveniently represented by the use
of escape sequences:
^X ('_X' & 037) control-_X
\b, \B (ASCII 010) backspace
\t, \T (ASCII 011) tab
\n, \N (ASCII 012) line feed (newline)
\f, \F (ASCII 014) form feed
\r, \R (ASCII 015) carriage return
\e, \E (ASCII 027) escape
\c, \C (:) colon
\\ (\) back slash
\^ (^) caret
\_n_n_n (ASCII octal _n_n_n)
A `\' may be followed by up to three octal digits directly specifies the
numeric code for a character. The use of ASCII NULs, while easily encod-
ed, causes all sorts of problems and must be used with care since NULs
are typically used to denote the end of strings; many applications use
`\200' to represent a NUL.
DDIIAAGGNNOOSSTTIICCSS
CCggeetteenntt, ccggeettsseett, ccggeettmmaattcchh, ccggeettnnuumm, ccggeettssttrr, ccggeettuussttrr, ccggeettffiirrsstt, and
ccggeettnneexxtt return a a value greater than or equal to 0 on success and a
value less than 0 on failure. CCggeettccaapp returns a character pointer on
success and a NULL on failure.
CCggeetteenntt, and ccggeettsseeqq may fail and set _e_r_r_n_o for any of the errors speci-
fied for the library functions: fopen(2), fclose(2), open(2), and
close(2).
CCggeetteenntt, ccggeettsseett, ccggeettssttrr, and ccggeettuussttrr may fail and set _e_r_r_n_o as fol-
lows:
[ENOMEM] No memory to allocate.
SSEEEE AALLSSOO
cap_mkdb(1), malloc(3)
BBUUGGSS
Colons (`:') can't be used in names, types, or values.
There are no checks for ttcc==nnaammee loops in ccggeetteenntt.
The buffer added to the database by a call to ccggeettsseett is not unique to
the database but is rather prepended to any database used.
4.4BSD June 4, 1993 5