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