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