[BACK]Return to getcap.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / gen

Annotation of src/lib/libc/gen/getcap.3, Revision 1.1.1.2

1.1.1.1   cgd         1: .\" Copyright (c) 1992, 1993
                      2: .\"    The Regents of the University of California.  All rights reserved.
1.1       cgd         3: .\"
                      4: .\" This code is derived from software contributed to Berkeley by
                      5: .\" Casey Leedom of Lawrence Livermore National Laboratory.
                      6: .\"
                      7: .\" Redistribution and use in source and binary forms, with or without
                      8: .\" modification, are permitted provided that the following conditions
                      9: .\" are met:
                     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.
                     22: .\"
                     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
                     33: .\" SUCH DAMAGE.
                     34: .\"
1.1.1.2 ! perry      35: .\"    @(#)getcap.3    8.4 (Berkeley) 5/13/94
1.1       cgd        36: .\"
1.1.1.2 ! perry      37: .Dd "May 13, 1994"
1.1       cgd        38: .Dt GETCAP 3
                     39: .Os
                     40: .Sh NAME
                     41: .Nm cgetent ,
                     42: .Nm cgetset ,
                     43: .Nm cgetmatch ,
                     44: .Nm cgetcap ,
                     45: .Nm cgetnum ,
                     46: .Nm cgetstr ,
                     47: .Nm cgetustr ,
                     48: .Nm cgetfirst ,
                     49: .Nm cgetnext ,
                     50: .Nm cgetclose
                     51: .Nd capability database access routines
                     52: .Sh SYNOPSIS
                     53: .Fd #include <stdlib.h>
                     54: .Ft int
                     55: .Fn cgetent "char **buf" "char **db_array" "char *name"
                     56: .Ft int
                     57: .Fn cgetset "char *ent"
                     58: .Ft int
                     59: .Fn cgetmatch "char *buf" "char *name"
                     60: .Ft char *
                     61: .Fn cgetcap "char *buf" "char *cap" "char type"
                     62: .Ft int
                     63: .Fn cgetnum "char *buf" "char *cap" "long *num"
                     64: .Ft int
                     65: .Fn cgetstr "char *buf" "char *cap" "char **str"
                     66: .Ft int
                     67: .Fn cgetustr "char *buf" "char *cap" "char **str"
                     68: .Ft int
                     69: .Fn cgetfirst "char **buf" "char **db_array"
                     70: .Ft int
                     71: .Fn cgetnext "char **buf" "char **db_array"
                     72: .Ft int
                     73: .Fn cgetclose "void"
                     74: .Sh DESCRIPTION
                     75: .Fn Cgetent
1.1.1.2 ! perry      76: extracts the capability
1.1       cgd        77: .Fa name
                     78: from the database specified by the
                     79: .Dv NULL
                     80: terminated file array
                     81: .Fa db_array
                     82: and returns a pointer to a
                     83: .Xr malloc Ns \&'d
                     84: copy of it in
                     85: .Fa buf .
                     86: .Nm Cgetent
                     87: will first look for files ending in
                     88: .Nm .db
                     89: (see
                     90: .Xr cap_mkdb 1)
                     91: before accessing the ASCII file.
                     92: .Fa Buf
                     93: must be retained through all subsequent calls to
                     94: .Fn cgetmatch ,
                     95: .Fn cgetcap ,
                     96: .Fn cgetnum ,
                     97: .Fn cgetstr ,
                     98: and
                     99: .Fn cgetustr ,
                    100: but may then be
                    101: .Xr free Ns \&'d.
                    102: On success 0 is returned, 1 if the returned
                    103: record contains an unresolved
                    104: .Nm tc
                    105: expansion,
                    106: \-1 if the requested record couldn't be found,
                    107: \-2 if a system error was encountered (couldn't open/read a file, etc.) also
                    108: setting
                    109: .Va errno ,
                    110: and \-3 if a potential reference loop is detected (see
                    111: .Ic tc=
                    112: comments below).
                    113: .Pp
                    114: .Nm Cgetset
                    115: enables the addition of a character buffer containing a single capability
                    116: record entry
                    117: to the capability database.
                    118: Conceptually, the entry is added as the first ``file'' in the database, and
                    119: is therefore searched first on the call to
                    120: .Nm cgetent .
                    121: The entry is passed in
                    122: .Fa ent .
                    123: If
                    124: .Fa ent
                    125: is
                    126: .Dv NULL ,
                    127: the current entry is removed from the database.
                    128: .Nm Cgetset
                    129: must precede the database traversal.  It must be called before the
                    130: .Nm cgetent
                    131: call. If a sequential access is being performed (see below), it must be called
                    132: before the first sequential access call (
                    133: .Nm cgetfirst
                    134: or
                    135: .Nm cgetnext
                    136: ), or be directly preceded by a
                    137: .Nm cgetclose
                    138: call.
                    139: On success 0 is returned and \-1 on failure.
                    140: .Pp
                    141: .Nm Cgetmatch
                    142: will return 0 if
                    143: .Fa name
                    144: is one of the names of the capability record
                    145: .Fa buf ,
                    146: \-1 if
                    147: not.
                    148: .Pp
                    149: .Nm Cgetcap
                    150: searches the capability record
                    151: .Fa buf
                    152: for the capability
                    153: .Fa cap
                    154: with type
                    155: .Fa type .
                    156: A
                    157: .Fa type
                    158: is specified using any single character.  If a colon (`:') is used, an
                    159: untyped capability will be searched for (see below for explanation of
                    160: types).  A pointer to the value of
                    161: .Fa cap
                    162: in
                    163: .Fa buf
                    164: is returned on success,
                    165: .Dv NULL
                    166: if the requested capability couldn't be
                    167: found.  The end of the capability value is signaled by a `:' or
                    168: .Tn ASCII
                    169: .Dv NUL
                    170: (see below for capability database syntax).
                    171: .Pp
                    172: .Nm Cgetnum
                    173: retrieves the value of the numeric capability
                    174: .Fa cap
                    175: from the capability record pointed to by
                    176: .Fa buf .
                    177: The numeric value is returned in the
                    178: .Ft long
                    179: pointed to by
                    180: .Fa num .
                    181: 0 is returned on success, \-1 if the requested numeric capability couldn't
                    182: be found.
                    183: .Pp
                    184: .Nm Cgetstr
                    185: retrieves the value of the string capability
                    186: .Fa cap
                    187: from the capability record pointed to by
                    188: .Fa buf .
                    189: A pointer to a decoded,
                    190: .Dv NUL
                    191: terminated,
                    192: .Xr malloc Ns \&'d
                    193: copy of the string is returned in the
                    194: .Ft char *
                    195: pointed to by
                    196: .Fa str .
                    197: The number of characters in the decoded string not including the trailing
                    198: .Dv NUL
                    199: is returned on success, \-1 if the requested string capability couldn't
                    200: be found, \-2 if a system error was encountered (storage allocation
                    201: failure).
                    202: .Pp
                    203: .Nm Cgetustr
                    204: is identical to
                    205: .Nm cgetstr
                    206: except that it does not expand special characters, but rather returns each
                    207: character of the capability string literally.
                    208: .Pp
                    209: .Nm Cgetfirst ,
                    210: .Nm cgetnext ,
                    211: comprise a function group that provides for sequential
                    212: access of the
                    213: .Dv NULL
                    214: pointer terminated array of file names,
                    215: .Fa db_array .
                    216: .Nm Cgetfirst
                    217: returns the first record in the database and resets the access
                    218: to the first record.
                    219: .Nm Cgetnext
                    220: returns the next record in the database with respect to the
                    221: record returned by the previous
                    222: .Nm cgetfirst
                    223: or
                    224: .Nm cgetnext
                    225: call.  If there is no such previous call, the first record in the database is
                    226: returned.
                    227: Each record is returned in a
                    228: .Xr malloc Ns \&'d
                    229: copy pointed to by
                    230: .Fa buf .
                    231: .Ic Tc
                    232: expansion is done (see
                    233: .Ic tc=
                    234: comments below).
                    235: Upon completion of the database 0 is returned,  1 is returned upon successful
                    236: return of record with possibly more remaining (we haven't reached the end of
                    237: the database yet), 2 is returned if the record contains an unresolved
                    238: .Nm tc
1.1.1.1   cgd       239: expansion, \-1 is returned if an system error occurred, and \-2
1.1       cgd       240: is returned if a potential reference loop is detected (see
                    241: .Ic tc=
                    242: comments below).
                    243: Upon completion of database (0 return) the database is closed.
                    244: .Pp
                    245: .Nm Cgetclose
                    246: closes the sequential access and frees any memory and file descriptors
                    247: being used.  Note that it does not erase the buffer pushed by a call to
                    248: .Nm cgetset .
                    249: .Sh CAPABILITY DATABASE SYNTAX
                    250: Capability databases are normally
                    251: .Tn ASCII
                    252: and may be edited with standard
                    253: text editors.  Blank lines and lines beginning with a `#' are comments
                    254: and are ignored.  Lines ending with a `\|\e' indicate that the next line
                    255: is a continuation of the current line; the `\|\e' and following newline
                    256: are ignored.  Long lines are usually continued onto several physical
                    257: lines by ending each line except the last with a `\|\e'.
                    258: .Pp
                    259: Capability databases consist of a series of records, one per logical
                    260: line.  Each record contains a variable number of `:'-separated fields
                    261: (capabilities).  Empty fields consisting entirely of white space
                    262: characters (spaces and tabs) are ignored.
                    263: .Pp
                    264: The first capability of each record specifies its names, separated by `|'
                    265: characters.  These names are used to reference records in the database.
                    266: By convention, the last name is usually a comment and is not intended as
                    267: a lookup tag.  For example, the
                    268: .Em vt100
                    269: record from the
                    270: .Nm termcap
                    271: database begins:
                    272: .Pp
                    273: .Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:"
                    274: .Pp
                    275: giving four names that can be used to access the record.
                    276: .Pp
                    277: The remaining non-empty capabilities describe a set of (name, value)
                    278: bindings, consisting of a names optionally followed by a typed values:
                    279: .Bl -column "nameTvalue"
                    280: .It name Ta "typeless [boolean] capability"
                    281: .Em name No "is present [true]"
                    282: .It name Ns Em \&T Ns value Ta capability
                    283: .Pq Em name , \&T
                    284: has value
                    285: .Em value
                    286: .It name@ Ta "no capability" Em name No exists
                    287: .It name Ns Em T Ns \&@ Ta capability
                    288: .Pq Em name , T
                    289: does not exist
                    290: .El
                    291: .Pp
                    292: Names consist of one or more characters.  Names may contain any character
                    293: except `:', but it's usually best to restrict them to the printable
                    294: characters and avoid use of graphics like `#', `=', `%', `@', etc.  Types
                    295: are single characters used to separate capability names from their
                    296: associated typed values.  Types may be any character except a `:'.
                    297: Typically, graphics like `#', `=', `%', etc. are used.  Values may be any
                    298: number of characters and may contain any character except `:'.
                    299: .Sh CAPABILITY DATABASE SEMANTICS
                    300: Capability records describe a set of (name, value) bindings.  Names may
                    301: have multiple values bound to them.  Different values for a name are
                    302: distinguished by their
                    303: .Fa types .
                    304: .Nm Cgetcap
                    305: will return a pointer to a value of a name given the capability name and
                    306: the type of the value.
                    307: .Pp
                    308: The types `#' and `=' are conventionally used to denote numeric and
                    309: string typed values, but no restriction on those types is enforced.  The
                    310: functions
                    311: .Nm cgetnum
                    312: and
                    313: .Nm cgetstr
                    314: can be used to implement the traditional syntax and semantics of `#'
                    315: and `='.
                    316: Typeless capabilities are typically used to denote boolean objects with
                    317: presence or absence indicating truth and false values respectively.
                    318: This interpretation is conveniently represented by:
                    319: .Pp
                    320: .Dl "(getcap(buf, name, ':') != NULL)"
                    321: .Pp
                    322: A special capability,
                    323: .Ic tc= name ,
                    324: is used to indicate that the record specified by
                    325: .Fa name
                    326: should be substituted for the
                    327: .Ic tc
                    328: capability.
                    329: .Ic Tc
                    330: capabilities may interpolate records which also contain
                    331: .Ic tc
                    332: capabilities and more than one
                    333: .Ic tc
                    334: capability may be used in a record.  A
                    335: .Ic tc
                    336: expansion scope (i.e., where the argument is searched for) contains the
                    337: file in which the
                    338: .Ic tc
                    339: is declared and all subsequent files in the file array.
                    340: .Pp
                    341: When a database is searched for a capability record, the first matching
1.1.1.1   cgd       342: record in the search is returned.  When a record is scanned for a
1.1       cgd       343: capability, the first matching capability is returned; the capability
                    344: .Ic :nameT@:
                    345: will hide any following definition of a value of type
                    346: .Em T
                    347: for
                    348: .Fa name ;
                    349: and the capability
                    350: .Ic :name@:
                    351: will prevent any following values of
                    352: .Fa name
                    353: from being seen.
                    354: .Pp
                    355: These features combined with
                    356: .Ic tc
                    357: capabilities can be used to generate variations of other databases and
                    358: records by either adding new capabilities, overriding definitions with new
                    359: definitions, or hiding following definitions via `@' capabilities.
                    360: .Sh EXAMPLES
                    361: .Bd -unfilled -offset indent
                    362: example\||\|an example of binding multiple values to names:\e
                    363:        :foo%bar:foo^blah:foo@:\e
                    364:        :abc%xyz:abc^frap:abc$@:\e
                    365:        :tc=more:
                    366: .Ed
                    367: .Pp
                    368: The capability foo has two values bound to it (bar of type `%' and blah of
                    369: type `^') and any other value bindings are hidden.  The capability abc
                    370: also has two values bound but only a value of type `$' is prevented from
                    371: being defined in the capability record more.
                    372: .Pp
                    373: .Bd -unfilled -offset indent
                    374: file1:
                    375:        new\||\|new_record\||\|a modification of "old":\e
                    376:                :fript=bar:who-cares@:tc=old:blah:tc=extensions:
                    377: file2:
                    378:        old\||\|old_record\||\|an old database record:\e
                    379:                :fript=foo:who-cares:glork#200:
                    380: .Ed
                    381: .Pp
                    382: The records are extracted by calling
                    383: .Nm cgetent
                    384: with file1 preceding file2.
                    385: In the capability record new in file1, fript=bar overrides the definition
                    386: of fript=foo interpolated from the capability record old in file2,
                    387: who-cares@ prevents the definition of any who-cares definitions in old
                    388: from being seen, glork#200 is inherited from old, and blah and anything
                    389: defined by the record extensions is added to those definitions in old.
                    390: Note that the position of the fript=bar and who-cares@ definitions before
                    391: tc=old is important here.  If they were after, the definitions in old
                    392: would take precedence.
                    393: .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS
                    394: Two types are predefined by
                    395: .Nm cgetnum
                    396: and
                    397: .Nm cgetstr :
                    398: .Bl -column "nameXnumber"
                    399: .Sm off
                    400: .It Em name No \&# Em number Ta numeric
                    401: capability
                    402: .Em name
                    403: has value
                    404: .Em number
                    405: .It Em name No = Em string Ta "string capability"
                    406: .Em name
                    407: has value
                    408: .Em string
                    409: .It Em name No \&#@ Ta "the numeric capability"
                    410: .Em name
                    411: does not exist
                    412: .It Em name No \&=@ Ta "the string capability"
                    413: .Em name
                    414: does not exist
                    415: .El
                    416: .Pp
                    417: Numeric capability values may be given in one of three numeric bases.
                    418: If the number starts with either
                    419: .Ql 0x
                    420: or
                    421: .Ql 0X
                    422: it is interpreted as a hexadecimal number (both upper and lower case a-f
                    423: may be used to denote the extended hexadecimal digits).
                    424: Otherwise, if the number starts with a
                    425: .Ql 0
                    426: it is interpreted as an octal number.
                    427: Otherwise the number is interpreted as a decimal number.
                    428: .Pp
                    429: String capability values may contain any character.  Non-printable
                    430: .Dv ASCII
                    431: codes, new lines, and colons may be conveniently represented by the use
                    432: of escape sequences:
                    433: .Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)"
                    434: ^X     ('\fIX\fP' & 037)       control-\fIX\fP
                    435: \e\|b, \e\|B   (ASCII 010)     backspace
                    436: \e\|t, \e\|T   (ASCII 011)     tab
                    437: \e\|n, \e\|N   (ASCII 012)     line feed (newline)
                    438: \e\|f, \e\|F   (ASCII 014)     form feed
                    439: \e\|r, \e\|R   (ASCII 015)     carriage return
                    440: \e\|e, \e\|E   (ASCII 027)     escape
                    441: \e\|c, \e\|C   (:)     colon
                    442: \e\|\e (\e\|)  back slash
                    443: \e\|^  (^)     caret
                    444: \e\|\fInnn\fP  (ASCII octal \fInnn\fP)
                    445: .El
                    446: .Pp
                    447: A `\|\e' may be followed by up to three octal digits directly specifies
                    448: the numeric code for a character.  The use of
                    449: .Tn ASCII
                    450: .Dv NUL Ns s ,
                    451: while easily
                    452: encoded, causes all sorts of problems and must be used with care since
                    453: .Dv NUL Ns s
                    454: are typically used to denote the end of strings; many applications
                    455: use `\e\|200' to represent a
                    456: .Dv NUL .
                    457: .Sh DIAGNOSTICS
                    458: .Nm Cgetent ,
                    459: .Nm cgetset ,
                    460: .Nm cgetmatch ,
                    461: .Nm cgetnum ,
                    462: .Nm cgetstr ,
                    463: .Nm cgetustr ,
                    464: .Nm cgetfirst ,
                    465: and
                    466: .Nm cgetnext
1.1.1.1   cgd       467: return a value greater than or equal to 0 on success and a value less
1.1       cgd       468: than 0 on failure.
                    469: .Nm Cgetcap
                    470: returns a character pointer on success and a
                    471: .Dv NULL
                    472: on failure.
                    473: .Pp
                    474: .Nm Cgetent ,
                    475: and
                    476: .Nm cgetseq
                    477: may fail and set
                    478: .Va errno
                    479: for any of the errors specified for the library functions:
                    480: .Xr fopen 2 ,
                    481: .Xr fclose 2 ,
                    482: .Xr open 2 ,
                    483: and
                    484: .Xr close 2 .
                    485: .Pp
                    486: .Nm Cgetent ,
                    487: .Nm cgetset ,
                    488: .Nm cgetstr ,
                    489: and
                    490: .Nm cgetustr
                    491: may fail and set
                    492: .Va errno
                    493: as follows:
                    494: .Bl -tag -width Er
                    495: .It Bq Er ENOMEM
                    496: No memory to allocate.
                    497: .El
                    498: .Sh SEE ALSO
                    499: .Xr cap_mkdb 1 ,
                    500: .Xr malloc 3
                    501: .Sh BUGS
                    502: Colons (`:') can't be used in names, types, or values.
                    503: .Pp
                    504: There are no checks for
                    505: .Ic tc= name
                    506: loops in
                    507: .Nm cgetent .
                    508: .Pp
                    509: The buffer added to the database by a call to
                    510: .Nm cgetset
                    511: is not unique to the database but is rather prepended to any database used.

CVSweb <webmaster@jp.NetBSD.org>