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