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