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