GETCAP(3) BSD Programmer's Manual GETCAP(3)
c
\bcg
\bge
\bet
\bte
\ben
\bnt
\bt, c
\bcg
\bge
\bet
\bts
\bse
\bet
\bt, c
\bcg
\bge
\bet
\btm
\bma
\bat
\btc
\bch
\bh, c
\bcg
\bge
\bet
\btc
\bca
\bap
\bp, c
\bcg
\bge
\bet
\btn
\bnu
\bum
\bm, c
\bcg
\bge
\bet
\bts
\bst
\btr
\br, c
\bcg
\bge
\bet
\btu
\bus
\bst
\btr
\br,
c
\bcg
\bge
\bet
\btf
\bfi
\bir
\brs
\bst
\bt, c
\bcg
\bge
\bet
\btn
\bne
\bex
\bxt
\bt, c
\bcg
\bge
\bet
\btc
\bcl
\blo
\bos
\bse
\be - capability database access routines
S
\bSY
\bYN
\bNO
\bOP
\bPS
\bSI
\bIS
\bS
#
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bst
\btd
\bdl
\bli
\bib
\bb.
\b.h
\bh>
\b>
c
\bcg
\bge
\bet
\bte
\ben
\bnt
\bt(_
\bc_
\bh_
\ba_
\br _
\b*_
\b*_
\bb_
\bu_
\bf, _
\bc_
\bh_
\ba_
\br _
\b*_
\b*_
\bd_
\bb_
\b__
\ba_
\br_
\br_
\ba_
\by, _
\bc_
\bh_
\ba_
\br _
\b*_
\bn_
\ba_
\bm_
\be);
c
\bcg
\bge
\bet
\bts
\bse
\bet
\bt(_
\bc_
\bh_
\ba_
\br _
\b*_
\be_
\bn_
\bt);
c
\bcg
\bge
\bet
\btm
\bma
\bat
\btc
\bch
\bh(_
\bc_
\bh_
\ba_
\br _
\b*_
\bb_
\bu_
\bf, _
\bc_
\bh_
\ba_
\br _
\b*_
\bn_
\ba_
\bm_
\be);
c
\bcg
\bge
\bet
\btc
\bca
\bap
\bp(_
\bc_
\bh_
\ba_
\br _
\b*_
\bb_
\bu_
\bf, _
\bc_
\bh_
\ba_
\br _
\b*_
\bc_
\ba_
\bp, _
\bc_
\bh_
\ba_
\br _
\bt_
\by_
\bp_
\be);
c
\bcg
\bge
\bet
\btn
\bnu
\bum
\bm(_
\bc_
\bh_
\ba_
\br _
\b*_
\bb_
\bu_
\bf, _
\bc_
\bh_
\ba_
\br _
\b*_
\bc_
\ba_
\bp, _
\bl_
\bo_
\bn_
\bg _
\b*_
\bn_
\bu_
\bm);
c
\bcg
\bge
\bet
\bts
\bst
\btr
\br(_
\bc_
\bh_
\ba_
\br _
\b*_
\bb_
\bu_
\bf, _
\bc_
\bh_
\ba_
\br _
\b*_
\bc_
\ba_
\bp, _
\bc_
\bh_
\ba_
\br _
\b*_
\b*_
\bs_
\bt_
\br);
c
\bcg
\bge
\bet
\btu
\bus
\bst
\btr
\br(_
\bc_
\bh_
\ba_
\br _
\b*_
\bb_
\bu_
\bf, _
\bc_
\bh_
\ba_
\br _
\b*_
\bc_
\ba_
\bp, _
\bc_
\bh_
\ba_
\br _
\b*_
\b*_
\bs_
\bt_
\br);
c
\bcg
\bge
\bet
\btf
\bfi
\bir
\brs
\bst
\bt(_
\bc_
\bh_
\ba_
\br _
\b*_
\b*_
\bb_
\bu_
\bf, _
\bc_
\bh_
\ba_
\br _
\b*_
\b*_
\bd_
\bb_
\b__
\ba_
\br_
\br_
\ba_
\by);
c
\bcg
\bge
\bet
\btn
\bne
\bex
\bxt
\bt(_
\bc_
\bh_
\ba_
\br _
\b*_
\b*_
\bb_
\bu_
\bf, _
\bc_
\bh_
\ba_
\br _
\b*_
\b*_
\bd_
\bb_
\b__
\ba_
\br_
\br_
\ba_
\by);
c
\bcg
\bge
\bet
\btc
\bcl
\blo
\bos
\bse
\be(_
\bv_
\bo_
\bi_
\bd);
D
\bDE
\bES
\bSC
\bCR
\bRI
\bIP
\bPT
\bTI
\bIO
\bON
\bN
C
\bCg
\bge
\bet
\bte
\ben
\bnt
\bt() extracts the capability rec _
\bn_
\ba_
\bm_
\be from the database specified by
the NULL terminated file array _
\bd_
\bb_
\b__
\ba_
\br_
\br_
\ba_
\by and returns a pointer to a
malloc'd copy of it in _
\bb_
\bu_
\bf. C
\bCg
\bge
\bet
\bte
\ben
\bnt
\bt will first look for files ending in
.
\b.d
\bdb
\bb (see cap_mkdb(1)) before accessing the ASCII file. _
\bB_
\bu_
\bf must be re-
tained through all subsequent calls to c
\bcg
\bge
\bet
\btm
\bma
\bat
\btc
\bch
\bh(), c
\bcg
\bge
\bet
\btc
\bca
\bap
\bp(), c
\bcg
\bge
\bet
\btn
\bnu
\bum
\bm(),
c
\bcg
\bge
\bet
\bts
\bst
\btr
\br(), and c
\bcg
\bge
\bet
\btu
\bus
\bst
\btr
\br(), but may then be free'd. On success 0 is re-
turned, 1 if the returned record contains an unresolved t
\btc
\bc 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 _
\be_
\br_
\br_
\bn_
\bo, and -3 if
a potential reference loop is detected (see t
\btc
\bc=
\b= comments below).
C
\bCg
\bge
\bet
\bts
\bse
\bet
\bt 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 c
\bcg
\bge
\bet
\bte
\ben
\bnt
\bt. The entry is passed in _
\be_
\bn_
\bt. If _
\be_
\bn_
\bt
is NULL, the current entry is removed from the database. C
\bCg
\bge
\bet
\bts
\bse
\bet
\bt must
precede the database traversal. It must be called before the c
\bcg
\bge
\bet
\bte
\ben
\bnt
\bt
call. If a sequential access is being performed (see below), it must be
called before the first sequential access call ( c
\bcg
\bge
\bet
\btf
\bfi
\bir
\brs
\bst
\bt or c
\bcg
\bge
\bet
\btn
\bne
\bex
\bxt
\bt ),
or be directly preceded by a c
\bcg
\bge
\bet
\btc
\bcl
\blo
\bos
\bse
\be call. On success 0 is returned
C
\bCg
\bge
\bet
\btm
\bma
\bat
\btc
\bch
\bh will return 0 if _
\bn_
\ba_
\bm_
\be is one of the names of the capability
record _
\bb_
\bu_
\bf, -1 if not.
C
\bCg
\bge
\bet
\btc
\bca
\bap
\bp searches the capability record _
\bb_
\bu_
\bf for the capability _
\bc_
\ba_
\bp with
type _
\bt_
\by_
\bp_
\be. A _
\bt_
\by_
\bp_
\be 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 _
\bc_
\ba_
\bp in _
\bb_
\bu_
\bf 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).
C
\bCg
\bge
\bet
\btn
\bnu
\bum
\bm retrieves the value of the numeric capability _
\bc_
\ba_
\bp from the capa-
bility record pointed to by _
\bb_
\bu_
\bf. The numeric value is returned in the
_
\bl_
\bo_
\bn_
\bg pointed to by _
\bn_
\bu_
\bm. 0 is returned on success, -1 if the requested nu-
meric capability couldn't be found.
C
\bCg
\bge
\bet
\bts
\bst
\btr
\br retrieves the value of the string capability _
\bc_
\ba_
\bp from the capa-
bility record pointed to by _
\bb_
\bu_
\bf. A pointer to a decoded, NUL terminated,
malloc'd copy of the string is returned in the _
\bc_
\bh_
\ba_
\br _
\b* pointed to by _
\bs_
\bt_
\br.
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-
C
\bCg
\bge
\bet
\btu
\bus
\bst
\btr
\br is identical to c
\bcg
\bge
\bet
\bts
\bst
\btr
\br except that it does not expand special
characters, but rather returns each character of the capability string
C
\bCg
\bge
\bet
\btf
\bfi
\bir
\brs
\bst
\bt, c
\bcg
\bge
\bet
\btn
\bne
\bex
\bxt
\bt, comprise a function group that provides for sequen-
tial access of the NULL pointer terminated array of file names, _
\bd_
\bb_
\b__
\ba_
\br_
\br_
\ba_
\by.
C
\bCg
\bge
\bet
\btf
\bfi
\bir
\brs
\bst
\bt returns the first record in the database and resets the access
to the first record. C
\bCg
\bge
\bet
\btn
\bne
\bex
\bxt
\bt returns the next record in the database
with respect to the record returned by the previous c
\bcg
\bge
\bet
\btf
\bfi
\bir
\brs
\bst
\bt or c
\bcg
\bge
\bet
\btn
\bne
\bex
\bxt
\bt
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 _
\bb_
\bu_
\bf. T
\bTc
\bc expansion is done (see t
\btc
\bc=
\b= 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
t
\btc
\bc expansion, -1 is returned if an system error occured, and -2 is re-
turned if a potential reference loop is detected (see t
\btc
\bc=
\b= comments be-
low). Upon completion of database (0 return) the database is closed.
C
\bCg
\bge
\bet
\btc
\bcl
\blo
\bos
\bse
\be 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 c
\bcg
\bge
\bet
\bts
\bse
\bet
\bt.
C
\bCA
\bAP
\bPA
\bAB
\bBI
\bIL
\bLI
\bIT
\bTY
\bY D
\bDA
\bAT
\bTA
\bAB
\bBA
\bAS
\bSE
\bE S
\bSY
\bYN
\bNT
\bTA
\bAX
\bX
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 _
\bv_
\bt_
\b1_
\b0_
\b0 record from the t
\bte
\ber
\brm
\bmc
\bca
\bap
\bp database
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 _
\bn_
\ba_
\bm_
\be is present [true]
name_
\bTvalue capability (_
\bn_
\ba_
\bm_
\be, _
\bT) has value _
\bv_
\ba_
\bl_
\bu_
\be
name@ no capability _
\bn_
\ba_
\bm_
\be exists
name_
\bT@ capability (_
\bn_
\ba_
\bm_
\be, _
\bT) 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 `:'.
C
\bCA
\bAP
\bPA
\bAB
\bBI
\bIL
\bLI
\bIT
\bTY
\bY D
\bDA
\bAT
\bTA
\bAB
\bBA
\bAS
\bSE
\bE S
\bSE
\bEM
\bMA
\bAN
\bNT
\bTI
\bIC
\bCS
\bS
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 _
\bt_
\by_
\bp_
\be_
\bs. C
\bCg
\bge
\bet
\btc
\bca
\bap
\bp 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 c
\bcg
\bge
\bet
\btn
\bnu
\bum
\bm and c
\bcg
\bge
\bet
\bts
\bst
\btr
\br 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-
(getcap(buf, name, ':') != NULL)
A special capability, t
\btc
\bc=
\b= n
\bna
\bam
\bme
\be, is used to indicate that the record spec-
ified by _
\bn_
\ba_
\bm_
\be should be substituted for the t
\btc
\bc capability. T
\bTc
\bc capabili-
ties may interpolate records which also contain t
\btc
\bc capabilities and more
than one t
\btc
\bc capability may be used in a record. A t
\btc
\bc expansion scope
(i.e., where the argument is searched for) contains the file in which the
t
\btc
\bc 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
:
\b:n
\bna
\bam
\bme
\beT
\bT@
\b@:
\b: will hide any following definition of a value of type _
\bT for
_
\bn_
\ba_
\bm_
\be; and the capability :
\b:n
\bna
\bam
\bme
\be@
\b@:
\b: will prevent any following values of
_
\bn_
\ba_
\bm_
\be from being seen.
These features combined with t
\btc
\bc 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.
E
\bEX
\bXA
\bAM
\bMP
\bPL
\bLE
\bES
\bS
example|an example of binding multiple values to names:\
:abc%xyz:abc^frap:abc$@:\
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.
new|new_record|a modification of "old":\
:fript=bar:who-cares@:tc=old:blah:tc=extensions:
old|old_record|an old database record:\
:fript=foo:who-cares:glork#200:
The records are extracted by calling c
\bcg
\bge
\bet
\bte
\ben
\bnt
\bt 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
C
\bCG
\bGE
\bET
\bTN
\bNU
\bUM
\bM A
\bAN
\bND
\bD C
\bCG
\bGE
\bET
\bTS
\bST
\bTR
\bR S
\bSY
\bYN
\bNT
\bTA
\bAX
\bX A
\bAN
\bND
\bD S
\bSE
\bEM
\bMA
\bAN
\bNT
\bTI
\bIC
\bCS
\bS
Two types are predefined by c
\bcg
\bge
\bet
\btn
\bnu
\bum
\bm and c
\bcg
\bge
\bet
\bts
\bst
\btr
\br:
_
\bn_
\ba_
\bm_
\be#_
\bn_
\bu_
\bm_
\bb_
\be_
\br numeric capability _
\bn_
\ba_
\bm_
\be has value _
\bn_
\bu_
\bm_
\bb_
\be_
\br
_
\bn_
\ba_
\bm_
\be=_
\bs_
\bt_
\br_
\bi_
\bn_
\bg string capability _
\bn_
\ba_
\bm_
\be has value _
\bs_
\bt_
\br_
\bi_
\bn_
\bg
_
\bn_
\ba_
\bm_
\be#@ the numeric capability _
\bn_
\ba_
\bm_
\be does not exist
_
\bn_
\ba_
\bm_
\be=@ the string capability _
\bn_
\ba_
\bm_
\be 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-
String capability values may contain any character. Non-printable ASCII
codes, new lines, and colons may be conveniently represented by the use
^X ('_
\bX' & 037) control-_
\bX
\b, \B (ASCII 010) backspace
\n, \N (ASCII 012) line feed (newline)
\f, \F (ASCII 014) form feed
\r, \R (ASCII 015) carriage return
\e, \E (ASCII 027) escape
\_
\bn_
\bn_
\bn (ASCII octal _
\bn_
\bn_
\bn)
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.
D
\bDI
\bIA
\bAG
\bGN
\bNO
\bOS
\bST
\bTI
\bIC
\bCS
\bS
C
\bCg
\bge
\bet
\bte
\ben
\bnt
\bt, c
\bcg
\bge
\bet
\bts
\bse
\bet
\bt, c
\bcg
\bge
\bet
\btm
\bma
\bat
\btc
\bch
\bh, c
\bcg
\bge
\bet
\btn
\bnu
\bum
\bm, c
\bcg
\bge
\bet
\bts
\bst
\btr
\br, c
\bcg
\bge
\bet
\btu
\bus
\bst
\btr
\br, c
\bcg
\bge
\bet
\btf
\bfi
\bir
\brs
\bst
\bt, and
c
\bcg
\bge
\bet
\btn
\bne
\bex
\bxt
\bt return a a value greater than or equal to 0 on success and a
value less than 0 on failure. C
\bCg
\bge
\bet
\btc
\bca
\bap
\bp returns a character pointer on
success and a NULL on failure.
C
\bCg
\bge
\bet
\bte
\ben
\bnt
\bt, and c
\bcg
\bge
\bet
\bts
\bse
\beq
\bq may fail and set _
\be_
\br_
\br_
\bn_
\bo for any of the errors speci-
fied for the library functions: fopen(2), fclose(2), open(2), and
C
\bCg
\bge
\bet
\bte
\ben
\bnt
\bt, c
\bcg
\bge
\bet
\bts
\bse
\bet
\bt, c
\bcg
\bge
\bet
\bts
\bst
\btr
\br, and c
\bcg
\bge
\bet
\btu
\bus
\bst
\btr
\br may fail and set _
\be_
\br_
\br_
\bn_
\bo as fol-
[ENOMEM] No memory to allocate.
S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
Colons (`:') can't be used in names, types, or values.
There are no checks for t
\btc
\bc=
\b=n
\bna
\bam
\bme
\be loops in c
\bcg
\bge
\bet
\bte
\ben
\bnt
\bt.
The buffer added to the database by a call to c
\bcg
\bge
\bet
\bts
\bse
\bet
\bt is not unique to
the database but is rather prepended to any database used.
projects / unix-history / blob