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