[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.1     ! cgd         1: .\" Copyright (c) 1992 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             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: .\"
        !            35: .\"    @(#)getcap.3    5.4 (Berkeley) 8/11/92
        !            36: .\"
        !            37: .Dd "August 11, 1992"
        !            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
        !            76: extracts the capability rec
        !            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
        !           239: expansion, \-1 is returned if an system error occured, and \-2
        !           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
        !           342: record in the search is returned.  When an record is scanned for a
        !           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
        !           467: return a a value greater than or equal to 0 on success and a value less
        !           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>