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

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

CVSweb <webmaster@jp.NetBSD.org>