lib/libc/gen/getcap.3

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