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

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

CVSweb <webmaster@jp.NetBSD.org>