[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.8

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

CVSweb <webmaster@jp.NetBSD.org>