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: src/lib/libc/gen/getcap.3,v 1.30 2007/02/11 18:14:49 maxim Exp $
  33 .\" $DragonFly: src/lib/libc/gen/getcap.3,v 1.4 2008/05/02 02:05:03 swildner Exp $
  34 .\"
  35 .Dd March 22, 2002
  36 .Dt GETCAP 3
  37 .Os
  38 .Sh NAME
  39 .Nm cgetent ,
  40 .Nm cgetset ,
  41 .Nm cgetmatch ,
  42 .Nm cgetcap ,
  43 .Nm cgetnum ,
  44 .Nm cgetstr ,
  45 .Nm cgetustr ,
  46 .Nm cgetfirst ,
  47 .Nm cgetnext ,
  48 .Nm cgetclose
  49 .Nd capability database access routines
  50 .Sh LIBRARY
  51 .Lb libc
  52 .Sh SYNOPSIS
  53 .In stdlib.h
  54 .Ft int
  55 .Fn cgetent "char **buf" "char **db_array" "const char *name"
  56 .Ft int
  57 .Fn cgetset "const char *ent"
  58 .Ft int
  59 .Fn cgetmatch "const char *buf" "const char *name"
  60 .Ft char *
  61 .Fn cgetcap "char *buf" "const char *cap" "int type"
  62 .Ft int
  63 .Fn cgetnum "char *buf" "const char *cap" "long *num"
  64 .Ft int
  65 .Fn cgetstr "char *buf" "const char *cap" "char **str"
  66 .Ft int
  67 .Fn cgetustr "char *buf" "const 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 The
  76 .Fn cgetent
  77 function extracts the capability
  78 .Fa name
  79 from the database specified by the
  80 .Dv NULL
  81 terminated file array
  82 .Fa db_array
  83 and returns a pointer to a
  84 .Xr malloc 3 Ns \&'d
  85 copy of it in
  86 .Fa buf .
  87 The
  88 .Fn cgetent
  89 function will first look for files ending in
  90 .Pa .db
  91 (see
  92 .Xr cap_mkdb 1 )
  93 before accessing the ASCII file.
  94 The
  95 .Fa buf
  96 argument
  97 must be retained through all subsequent calls to
  98 .Fn cgetmatch ,
  99 .Fn cgetcap ,
 100 .Fn cgetnum ,
 101 .Fn cgetstr ,
 102 and
 103 .Fn cgetustr ,
 104 but may then be
 105 .Xr free 3 Ns \&'d .
 106 On success 0 is returned, 1 if the returned
 107 record contains an unresolved
 108 .Ic tc
 109 expansion,
 110 \-1 if the requested record could not be found,
 111 \-2 if a system error was encountered (could not open/read a file, etc.) also
 112 setting
 113 .Va errno ,
 114 and \-3 if a potential reference loop is detected (see
 115 .Ic tc=
 116 comments below).
 117 .Pp
 118 The
 119 .Fn cgetset
 120 function enables the addition of a character buffer containing a single capability
 121 record entry
 122 to the capability database.
 123 Conceptually, the entry is added as the first ``file'' in the database, and
 124 is therefore searched first on the call to
 125 .Fn cgetent .
 126 The entry is passed in
 127 .Fa ent .
 128 If
 129 .Fa ent
 130 is
 131 .Dv NULL ,
 132 the current entry is removed from the database.
 133 A call to
 134 .Fn cgetset
 135 must precede the database traversal.
 136 It must be called before the
 137 .Fn cgetent
 138 call.
 139 If a sequential access is being performed (see below), it must be called
 140 before the first sequential access call
 141 .Fn ( cgetfirst
 142 or
 143 .Fn cgetnext ) ,
 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 .Bl -column "nameTvalue"
 310 .It name Ta "typeless [boolean] capability"
 311 .Em name No "is present [true]"
 312 .It name Ns Em \&T Ns value Ta capability
 313 .Pq Em name , \&T
 314 has value
 315 .Em value
 316 .It name@ Ta "no capability" Em name No exists
 317 .It name Ns Em T Ns \&@ Ta capability
 318 .Pq Em name , T
 319 does not exist
 320 .El
 321 .Pp
 322 Names consist of one or more characters.
 323 Names may contain any character
 324 except `:', but it is usually best to restrict them to the printable
 325 characters and avoid use of graphics like `#', `=', `%', `@', etc.
 326 Types
 327 are single characters used to separate capability names from their
 328 associated typed values.
 329 Types may be any character except a `:'.
 330 Typically, graphics like `#', `=', `%', etc.\& are used.
 331 Values may be any
 332 number of characters and may contain any character except `:'.
 333 .Sh CAPABILITY DATABASE SEMANTICS
 334 Capability records describe a set of (name, value) bindings.
 335 Names may have multiple values bound to them.
 336 Different values for a name are
 337 distinguished by their
 338 .Fa types .
 339 The
 340 .Fn cgetcap
 341 function will return a pointer to a value of a name given the capability
 342 name and the type of the value.
 343 .Pp
 344 The types `#' and `=' are conventionally used to denote numeric and
 345 string typed values, but no restriction on those types is enforced.
 346 The
 347 functions
 348 .Fn cgetnum
 349 and
 350 .Fn cgetstr
 351 can be used to implement the traditional syntax and semantics of `#'
 352 and `='.
 353 Typeless capabilities are typically used to denote boolean objects with
 354 presence or absence indicating truth and false values respectively.
 355 This interpretation is conveniently represented by:
 356 .Pp
 357 .Dl "(getcap(buf, name, ':') != NULL)"
 358 .Pp
 359 A special capability,
 360 .Ic tc= name ,
 361 is used to indicate that the record specified by
 362 .Fa name
 363 should be substituted for the
 364 .Ic tc
 365 capability.
 366 .Ic Tc
 367 capabilities may interpolate records which also contain
 368 .Ic tc
 369 capabilities and more than one
 370 .Ic tc
 371 capability may be used in a record.
 372 A
 373 .Ic tc
 374 expansion scope (i.e., where the argument is searched for) contains the
 375 file in which the
 376 .Ic tc
 377 is declared and all subsequent files in the file array.
 378 .Pp
 379 When a database is searched for a capability record, the first matching
 380 record in the search is returned.
 381 When a record is scanned for a
 382 capability, the first matching capability is returned; the capability
 383 .Ic :nameT@:
 384 will hide any following definition of a value of type
 385 .Em T
 386 for
 387 .Fa name ;
 388 and the capability
 389 .Ic :name@:
 390 will prevent any following values of
 391 .Fa name
 392 from being seen.
 393 .Pp
 394 These features combined with
 395 .Ic tc
 396 capabilities can be used to generate variations of other databases and
 397 records by either adding new capabilities, overriding definitions with new
 398 definitions, or hiding following definitions via `@' capabilities.
 399 .Sh EXAMPLES
 400 .Bd -unfilled -offset indent
 401 example\||\|an example of binding multiple values to names:\e
 402         :foo%bar:foo^blah:foo@:\e
 403         :abc%xyz:abc^frap:abc$@:\e
 404         :tc=more:
 405 .Ed
 406 .Pp
 407 The capability foo has two values bound to it (bar of type `%' and blah of
 408 type `^') and any other value bindings are hidden.
 409 The capability abc
 410 also has two values bound but only a value of type `$' is prevented from
 411 being defined in the capability record more.
 412 .Bd -unfilled -offset indent
 413 file1:
 414         new\||\|new_record\||\|a modification of "old":\e
 415                 :fript=bar:who-cares@:tc=old:blah:tc=extensions:
 416 file2:
 417         old\||\|old_record\||\|an old database record:\e
 418                 :fript=foo:who-cares:glork#200:
 419 .Ed
 420 .Pp
 421 The records are extracted by calling
 422 .Fn cgetent
 423 with file1 preceding file2.
 424 In the capability record new in file1, fript=bar overrides the definition
 425 of fript=foo interpolated from the capability record old in file2,
 426 who-cares@ prevents the definition of any who-cares definitions in old
 427 from being seen, glork#200 is inherited from old, and blah and anything
 428 defined by the record extensions is added to those definitions in old.
 429 Note that the position of the fript=bar and who-cares@ definitions before
 430 tc=old is important here.
 431 If they were after, the definitions in old
 432 would take precedence.
 433 .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS
 434 Two types are predefined by
 435 .Fn cgetnum
 436 and
 437 .Fn cgetstr :
 438 .Bl -column "nameXnumber"
 439 .Sm off
 440 .It Em name No \&# Em number Ta numeric
 441 .Sm on
 442 capability
 443 .Em name
 444 has value
 445 .Em number
 446 .Sm off
 447 .It Em name No = Em string Ta "string capability"
 448 .Sm on
 449 .Em name
 450 has value
 451 .Em string
 452 .Sm off
 453 .It Em name No \&#@ Ta "the numeric capability"
 454 .Sm on
 455 .Em name
 456 does not exist
 457 .Sm off
 458 .It Em name No \&=@ Ta "the string capability"
 459 .Sm on
 460 .Em name
 461 does not exist
 462 .El
 463 .Pp
 464 Numeric capability values may be given in one of three numeric bases.
 465 If the number starts with either
 466 .Ql 0x
 467 or
 468 .Ql 0X
 469 it is interpreted as a hexadecimal number (both upper and lower case a-f
 470 may be used to denote the extended hexadecimal digits).
 471 Otherwise, if the number starts with a
 472 .Ql 0
 473 it is interpreted as an octal number.
 474 Otherwise the number is interpreted as a decimal number.
 475 .Pp
 476 String capability values may contain any character.
 477 Non-printable
 478 .Dv ASCII
 479 codes, new lines, and colons may be conveniently represented by the use
 480 of escape sequences:
 481 .Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)"
 482 ^X      ('X' & 037)     control-X
 483 \e\|b, \e\|B    (ASCII 010)     backspace
 484 \e\|t, \e\|T    (ASCII 011)     tab
 485 \e\|n, \e\|N    (ASCII 012)     line feed (newline)
 486 \e\|f, \e\|F    (ASCII 014)     form feed
 487 \e\|r, \e\|R    (ASCII 015)     carriage return
 488 \e\|e, \e\|E    (ASCII 027)     escape
 489 \e\|c, \e\|C    (:)     colon
 490 \e\|\e  (\e\|)  back slash
 491 \e\|^   (^)     caret
 492 \e\|nnn (ASCII octal nnn)
 493 .El
 494 .Pp
 495 A `\|\e' may be followed by up to three octal digits directly specifies
 496 the numeric code for a character.
 497 The use of
 498 .Tn ASCII
 499 .Dv NUL Ns s ,
 500 while easily
 501 encoded, causes all sorts of problems and must be used with care since
 502 .Dv NUL Ns s
 503 are typically used to denote the end of strings; many applications
 504 use `\e\|200' to represent a
 505 .Dv NUL .
 506 .Sh DIAGNOSTICS
 507 The
 508 .Fn cgetent ,
 509 .Fn cgetset ,
 510 .Fn cgetmatch ,
 511 .Fn cgetnum ,
 512 .Fn cgetstr ,
 513 .Fn cgetustr ,
 514 .Fn cgetfirst ,
 515 and
 516 .Fn cgetnext
 517 functions
 518 return a value greater than or equal to 0 on success and a value less
 519 than 0 on failure.
 520 The
 521 .Fn cgetcap
 522 function returns a character pointer on success and a
 523 .Dv NULL
 524 on failure.
 525 .Pp
 526 The
 527 .Fn cgetent ,
 528 and
 529 .Fn cgetset
 530 functions may fail and set
 531 .Va errno
 532 for any of the errors specified for the library functions:
 533 .Xr fopen 3 ,
 534 .Xr fclose 3 ,
 535 .Xr open 2 ,
 536 and
 537 .Xr close 2 .
 538 .Pp
 539 The
 540 .Fn cgetent ,
 541 .Fn cgetset ,
 542 .Fn cgetstr ,
 543 and
 544 .Fn cgetustr
 545 functions
 546 may fail and set
 547 .Va errno
 548 as follows:
 549 .Bl -tag -width Er
 550 .It Bq Er ENOMEM
 551 No memory to allocate.
 552 .El
 553 .Sh SEE ALSO
 554 .Xr cap_mkdb 1 ,
 555 .Xr malloc 3
 556 .Sh BUGS
 557 Colons (`:') cannot be used in names, types, or values.
 558 .Pp
 559 There are no checks for
 560 .Ic tc Ns = Ns Ic name
 561 loops in
 562 .Fn cgetent .
 563 .Pp
 564 The buffer added to the database by a call to
 565 .Fn cgetset
 566 is not unique to the database but is rather prepended to any database used.