1 .\" Copyright (c) 1992, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Casey Leedom of Lawrence Livermore National Laboratory.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" @(#)getcap.3 8.4 (Berkeley) 5/13/94
36 .\" $FreeBSD: src/lib/libc/gen/getcap.3,v 1.12.2.7 2003/03/13 18:05:37 trhodes Exp $
37 .\" $DragonFly: src/lib/libc/gen/getcap.3,v 1.3 2007/02/10 22:04:12 swildner Exp $
53 .Nd capability database access routines
59 .Fn cgetent "char **buf" "char **db_array" "char *name"
61 .Fn cgetset "char *ent"
63 .Fn cgetmatch "char *buf" "char *name"
65 .Fn cgetcap "char *buf" "char *cap" "int type"
67 .Fn cgetnum "char *buf" "char *cap" "long *num"
69 .Fn cgetstr "char *buf" "char *cap" "char **str"
71 .Fn cgetustr "char *buf" "char *cap" "char **str"
73 .Fn cgetfirst "char **buf" "char **db_array"
75 .Fn cgetnext "char **buf" "char **db_array"
81 function extracts the capability
83 from the database specified by the
87 and returns a pointer to a
93 function will first look for files ending in
97 before accessing the ASCII file.
101 must be retained through all subsequent calls to
110 On success 0 is returned, 1 if the returned
111 record contains an unresolved
114 \-1 if the requested record couldn't be found,
115 \-2 if a system error was encountered (couldn't open/read a file, etc.) also
118 and \-3 if a potential reference loop is detected (see
124 function enables the addition of a character buffer containing a single capability
126 to the capability database.
127 Conceptually, the entry is added as the first ``file'' in the database, and
128 is therefore searched first on the call to
130 The entry is passed in
136 the current entry is removed from the database.
139 must precede the database traversal. It must be called before the
141 call. If a sequential access is being performed (see below), it must be called
142 before the first sequential access call
146 or be directly preceded by a
149 On success 0 is returned and \-1 on failure.
153 function will return 0 if
155 is one of the names of the capability record
162 function searches the capability record
170 is specified using any single character. If a colon (`:') is used, an
171 untyped capability will be searched for (see below for explanation of
172 types). A pointer to the value of
176 is returned on success,
178 if the requested capability couldn't be
179 found. The end of the capability value is signaled by a `:' or
182 (see below for capability database syntax).
186 function retrieves the value of the numeric capability
188 from the capability record pointed to by
190 The numeric value is returned in the
194 0 is returned on success, \-1 if the requested numeric capability couldn't
199 function retrieves the value of the string capability
201 from the capability record pointed to by
203 A pointer to a decoded,
207 copy of the string is returned in the
211 The number of characters in the decoded string not including the trailing
213 is returned on success, \-1 if the requested string capability couldn't
214 be found, \-2 if a system error was encountered (storage allocation
219 function is identical to
221 except that it does not expand special characters, but rather returns each
222 character of the capability string literally.
228 functions comprise a function group that provides for sequential
231 pointer terminated array of file names,
235 function returns the first record in the database and resets the access
239 function returns the next record in the database with respect to the
240 record returned by the previous
244 call. If there is no such previous call, the first record in the database is
246 Each record is returned in a
251 expansion is done (see
254 Upon completion of the database 0 is returned, 1 is returned upon successful
255 return of record with possibly more remaining (we haven't reached the end of
256 the database yet), 2 is returned if the record contains an unresolved
258 expansion, \-1 is returned if a system error occurred, and \-2
259 is returned if a potential reference loop is detected (see
262 Upon completion of database (0 return) the database is closed.
266 function closes the sequential access and frees any memory and file descriptors
267 being used. Note that it does not erase the buffer pushed by a call to
269 .Sh CAPABILITY DATABASE SYNTAX
270 Capability databases are normally
272 and may be edited with standard
273 text editors. Blank lines and lines beginning with a `#' are comments
274 and are ignored. Lines ending with a `\|\e' indicate that the next line
275 is a continuation of the current line; the `\|\e' and following newline
276 are ignored. Long lines are usually continued onto several physical
277 lines by ending each line except the last with a `\|\e'.
279 Capability databases consist of a series of records, one per logical
280 line. Each record contains a variable number of `:'-separated fields
281 (capabilities). Empty fields consisting entirely of white space
282 characters (spaces and tabs) are ignored.
284 The first capability of each record specifies its names, separated by `|'
285 characters. These names are used to reference records in the database.
286 By convention, the last name is usually a comment and is not intended as
287 a lookup tag. For example, the
293 .Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:"
295 giving four names that can be used to access the record.
297 The remaining non-empty capabilities describe a set of (name, value)
298 bindings, consisting of a names optionally followed by a typed value:
299 .Bl -column "nameTvalue"
300 .It name Ta "typeless [boolean] capability"
301 .Em name No "is present [true]"
302 .It name Ns Em \&T Ns value Ta capability
306 .It name@ Ta "no capability" Em name No exists
307 .It name Ns Em T Ns \&@ Ta capability
312 Names consist of one or more characters. Names may contain any character
313 except `:', but it's usually best to restrict them to the printable
314 characters and avoid use of graphics like `#', `=', `%', `@', etc. Types
315 are single characters used to separate capability names from their
316 associated typed values. Types may be any character except a `:'.
317 Typically, graphics like `#', `=', `%', etc. are used. Values may be any
318 number of characters and may contain any character except `:'.
319 .Sh CAPABILITY DATABASE SEMANTICS
320 Capability records describe a set of (name, value) bindings. Names may
321 have multiple values bound to them. Different values for a name are
322 distinguished by their
326 function will return a pointer to a value of a name given the capability
327 name and the type of the value.
329 The types `#' and `=' are conventionally used to denote numeric and
330 string typed values, but no restriction on those types is enforced. The
335 can be used to implement the traditional syntax and semantics of `#'
337 Typeless capabilities are typically used to denote boolean objects with
338 presence or absence indicating truth and false values respectively.
339 This interpretation is conveniently represented by:
341 .Dl "(getcap(buf, name, ':') != NULL)"
343 A special capability,
345 is used to indicate that the record specified by
347 should be substituted for the
351 capabilities may interpolate records which also contain
353 capabilities and more than one
355 capability may be used in a record. A
357 expansion scope (i.e., where the argument is searched for) contains the
360 is declared and all subsequent files in the file array.
362 When a database is searched for a capability record, the first matching
363 record in the search is returned. When a record is scanned for a
364 capability, the first matching capability is returned; the capability
366 will hide any following definition of a value of type
372 will prevent any following values of
376 These features combined with
378 capabilities can be used to generate variations of other databases and
379 records by either adding new capabilities, overriding definitions with new
380 definitions, or hiding following definitions via `@' capabilities.
382 .Bd -unfilled -offset indent
383 example\||\|an example of binding multiple values to names:\e
384 :foo%bar:foo^blah:foo@:\e
385 :abc%xyz:abc^frap:abc$@:\e
389 The capability foo has two values bound to it (bar of type `%' and blah of
390 type `^') and any other value bindings are hidden. The capability abc
391 also has two values bound but only a value of type `$' is prevented from
392 being defined in the capability record more.
394 .Bd -unfilled -offset indent
396 new\||\|new_record\||\|a modification of "old":\e
397 :fript=bar:who-cares@:tc=old:blah:tc=extensions:
399 old\||\|old_record\||\|an old database record:\e
400 :fript=foo:who-cares:glork#200:
403 The records are extracted by calling
405 with file1 preceding file2.
406 In the capability record new in file1, fript=bar overrides the definition
407 of fript=foo interpolated from the capability record old in file2,
408 who-cares@ prevents the definition of any who-cares definitions in old
409 from being seen, glork#200 is inherited from old, and blah and anything
410 defined by the record extensions is added to those definitions in old.
411 Note that the position of the fript=bar and who-cares@ definitions before
412 tc=old is important here. If they were after, the definitions in old
413 would take precedence.
414 .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS
415 Two types are predefined by
419 .Bl -column "nameXnumber"
421 .It Em name No \&# Em number Ta numeric
428 .It Em name No = Em string Ta "string capability"
434 .It Em name No \&#@ Ta "the numeric capability"
439 .It Em name No \&=@ Ta "the string capability"
445 Numeric capability values may be given in one of three numeric bases.
446 If the number starts with either
450 it is interpreted as a hexadecimal number (both upper and lower case a-f
451 may be used to denote the extended hexadecimal digits).
452 Otherwise, if the number starts with a
454 it is interpreted as an octal number.
455 Otherwise the number is interpreted as a decimal number.
457 String capability values may contain any character. Non-printable
459 codes, new lines, and colons may be conveniently represented by the use
461 .Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)"
462 ^X ('X' & 037) control-X
463 \e\|b, \e\|B (ASCII 010) backspace
464 \e\|t, \e\|T (ASCII 011) tab
465 \e\|n, \e\|N (ASCII 012) line feed (newline)
466 \e\|f, \e\|F (ASCII 014) form feed
467 \e\|r, \e\|R (ASCII 015) carriage return
468 \e\|e, \e\|E (ASCII 027) escape
469 \e\|c, \e\|C (:) colon
470 \e\|\e (\e\|) back slash
472 \e\|nnn (ASCII octal nnn)
475 A `\|\e' may be followed by up to three octal digits directly specifies
476 the numeric code for a character. The use of
480 encoded, causes all sorts of problems and must be used with care since
482 are typically used to denote the end of strings; many applications
483 use `\e\|200' to represent a
497 return a value greater than or equal to 0 on success and a value less
501 function returns a character pointer on success and a
509 functions may fail and set
511 for any of the errors specified for the library functions:
530 No memory to allocate.
536 Colons (`:') can't be used in names, types, or values.
538 There are no checks for
539 .Ic tc Ns = Ns Ic name
543 The buffer added to the database by a call to
545 is not unique to the database but is rather prepended to any database used.