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>
![[BACK]](/icons/back.gif){kind=icon}
Return to getcap.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / gen