| getcap.3 (21ac7f5f2339dc171db79389cf28fb800acc8dea) | getcap.3 (662909a7800d5634772b89ca1509765dda837508) |
|---|---|
| 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 --- 18 unchanged lines hidden (view full) --- 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.\" | 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 --- 18 unchanged lines hidden (view full) --- 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.3 (Berkeley) 4/19/94 | 35.\" @(#)getcap.3 8.4 (Berkeley) 5/13/94 |
| 36.\" | 36.\" |
| 37.Dd "April 19, 1994" | 37.Dd "May 13, 1994" |
| 38.Dt GETCAP 3 39.Os 40.Sh NAME 41.Nm cgetent , 42.Nm cgetset , 43.Nm cgetmatch , 44.Nm cgetcap , 45.Nm cgetnum , --- 32 unchanged lines hidden (view full) --- 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 Ns \&'d 84copy of it in 85.Fa buf . | 38.Dt GETCAP 3 39.Os 40.Sh NAME 41.Nm cgetent , 42.Nm cgetset , 43.Nm cgetmatch , 44.Nm cgetcap , 45.Nm cgetnum , --- 32 unchanged lines hidden (view full) --- 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 Ns \&'d 84copy of it in 85.Fa buf . |
| 86The 87.Fn cgetent 88function will first look for files ending in | 86.Nm Cgetent 87will first look for files ending in |
| 89.Nm .db 90(see 91.Xr cap_mkdb 1) 92before accessing the ASCII file. 93.Fa Buf 94must be retained through all subsequent calls to 95.Fn cgetmatch , 96.Fn cgetcap , 97.Fn cgetnum , 98.Fn cgetstr , 99and 100.Fn cgetustr , 101but may then be | 88.Nm .db 89(see 90.Xr cap_mkdb 1) 91before accessing the ASCII file. 92.Fa Buf 93must be retained through all subsequent calls to 94.Fn cgetmatch , 95.Fn cgetcap , 96.Fn cgetnum , 97.Fn cgetstr , 98and 99.Fn cgetustr , 100but may then be |
| 102.Xr free 3 Ns \&'d. | 101.Xr free Ns \&'d. |
| 103On success 0 is returned, 1 if the returned 104record contains an unresolved 105.Nm tc 106expansion, 107\-1 if the requested record couldn't be found, 108\-2 if a system error was encountered (couldn't open/read a file, etc.) also 109setting 110.Va errno , 111and \-3 if a potential reference loop is detected (see 112.Ic tc= 113comments below). 114.Pp | 102On success 0 is returned, 1 if the returned 103record contains an unresolved 104.Nm tc 105expansion, 106\-1 if the requested record couldn't be found, 107\-2 if a system error was encountered (couldn't open/read a file, etc.) also 108setting 109.Va errno , 110and \-3 if a potential reference loop is detected (see 111.Ic tc= 112comments below). 113.Pp |
| 115The 116.Fn cgetset 117function enables the addition of a character buffer containing a single capability | 114.Nm Cgetset 115enables the addition of a character buffer containing a single capability |
| 118record entry 119to the capability database. 120Conceptually, the entry is added as the first ``file'' in the database, and 121is therefore searched first on the call to | 116record entry 117to the capability database. 118Conceptually, the entry is added as the first ``file'' in the database, and 119is therefore searched first on the call to |
| 122.Fn cgetent . | 120.Nm cgetent . |
| 123The entry is passed in 124.Fa ent . 125If 126.Fa ent 127is 128.Dv NULL , 129the current entry is removed from the database. | 121The entry is passed in 122.Fa ent . 123If 124.Fa ent 125is 126.Dv NULL , 127the current entry is removed from the database. |
| 130A call to 131.Fn cgetset | 128.Nm Cgetset |
| 132must precede the database traversal. It must be called before the | 129must precede the database traversal. It must be called before the |
| 133.Fn cgetent | 130.Nm cgetent |
| 134call. If a sequential access is being performed (see below), it must be called 135before the first sequential access call ( | 131call. If a sequential access is being performed (see below), it must be called 132before the first sequential access call ( |
| 136.Fn cgetfirst | 133.Nm cgetfirst |
| 137or | 134or |
| 138.Fn cgetnext | 135.Nm cgetnext |
| 139), or be directly preceded by a | 136), or be directly preceded by a |
| 140.Fn cgetclose | 137.Nm cgetclose |
| 141call. 142On success 0 is returned and \-1 on failure. 143.Pp | 138call. 139On success 0 is returned and \-1 on failure. 140.Pp |
| 144The 145.Fn cgetmatch 146function will return 0 if | 141.Nm Cgetmatch 142will return 0 if |
| 147.Fa name 148is one of the names of the capability record 149.Fa buf , 150\-1 if 151not. 152.Pp | 143.Fa name 144is one of the names of the capability record 145.Fa buf , 146\-1 if 147not. 148.Pp |
| 153The 154.Fn cgetcap 155function searches the capability record | 149.Nm Cgetcap 150searches the capability record |
| 156.Fa buf 157for the capability 158.Fa cap 159with type 160.Fa type . 161A 162.Fa type 163is specified using any single character. If a colon (`:') is used, an --- 5 unchanged lines hidden (view full) --- 169is returned on success, 170.Dv NULL 171if the requested capability couldn't be 172found. The end of the capability value is signaled by a `:' or 173.Tn ASCII 174.Dv NUL 175(see below for capability database syntax). 176.Pp | 151.Fa buf 152for the capability 153.Fa cap 154with type 155.Fa type . 156A 157.Fa type 158is specified using any single character. If a colon (`:') is used, an --- 5 unchanged lines hidden (view full) --- 164is returned on success, 165.Dv NULL 166if the requested capability couldn't be 167found. The end of the capability value is signaled by a `:' or 168.Tn ASCII 169.Dv NUL 170(see below for capability database syntax). 171.Pp |
| 177The 178.Fn cgetnum 179function retrieves the value of the numeric capability | 172.Nm Cgetnum 173retrieves the value of the numeric capability |
| 180.Fa cap 181from the capability record pointed to by 182.Fa buf . 183The numeric value is returned in the 184.Ft long 185pointed to by 186.Fa num . 1870 is returned on success, \-1 if the requested numeric capability couldn't 188be found. 189.Pp | 174.Fa cap 175from the capability record pointed to by 176.Fa buf . 177The numeric value is returned in the 178.Ft long 179pointed to by 180.Fa num . 1810 is returned on success, \-1 if the requested numeric capability couldn't 182be found. 183.Pp |
| 190The 191.Fn cgetstr 192function retrieves the value of the string capability | 184.Nm Cgetstr 185retrieves the value of the string capability |
| 193.Fa cap 194from the capability record pointed to by 195.Fa buf . 196A pointer to a decoded, 197.Dv NUL 198terminated, 199.Xr malloc Ns \&'d 200copy of the string is returned in the 201.Ft char * 202pointed to by 203.Fa str . 204The number of characters in the decoded string not including the trailing 205.Dv NUL 206is returned on success, \-1 if the requested string capability couldn't 207be found, \-2 if a system error was encountered (storage allocation 208failure). 209.Pp | 186.Fa cap 187from the capability record pointed to by 188.Fa buf . 189A pointer to a decoded, 190.Dv NUL 191terminated, 192.Xr malloc Ns \&'d 193copy of the string is returned in the 194.Ft char * 195pointed to by 196.Fa str . 197The number of characters in the decoded string not including the trailing 198.Dv NUL 199is returned on success, \-1 if the requested string capability couldn't 200be found, \-2 if a system error was encountered (storage allocation 201failure). 202.Pp |
| 210The 211.Fn cgetustr 212function is identical to 213.Fn cgetstr | 203.Nm Cgetustr 204is identical to 205.Nm cgetstr |
| 214except that it does not expand special characters, but rather returns each 215character of the capability string literally. 216.Pp | 206except that it does not expand special characters, but rather returns each 207character of the capability string literally. 208.Pp |
| 217The 218.Fn cgetfirst 219and 220.Fn cgetnext 221functions comprise a function group that provides for sequential | 209.Nm Cgetfirst , 210.Nm cgetnext , 211comprise a function group that provides for sequential |
| 222access of the 223.Dv NULL 224pointer terminated array of file names, 225.Fa db_array . | 212access of the 213.Dv NULL 214pointer terminated array of file names, 215.Fa db_array . |
| 226The 227.Fn cgetfirst 228function returns the first record in the database and resets the access | 216.Nm Cgetfirst 217returns the first record in the database and resets the access |
| 229to the first record. | 218to the first record. |
| 230The 231.Fn cgetnext 232function returns the next record in the database with respect to the | 219.Nm Cgetnext 220returns the next record in the database with respect to the |
| 233record returned by the previous | 221record returned by the previous |
| 234.Fn cgetfirst | 222.Nm cgetfirst |
| 235or | 223or |
| 236.Fn cgetnext | 224.Nm cgetnext |
| 237call. If there is no such previous call, the first record in the database is 238returned. 239Each record is returned in a 240.Xr malloc Ns \&'d 241copy pointed to by 242.Fa buf . 243.Ic Tc 244expansion is done (see --- 4 unchanged lines hidden (view full) --- 249the database yet), 2 is returned if the record contains an unresolved 250.Nm tc 251expansion, \-1 is returned if an system error occurred, and \-2 252is returned if a potential reference loop is detected (see 253.Ic tc= 254comments below). 255Upon completion of database (0 return) the database is closed. 256.Pp | 225call. If there is no such previous call, the first record in the database is 226returned. 227Each record is returned in a 228.Xr malloc Ns \&'d 229copy pointed to by 230.Fa buf . 231.Ic Tc 232expansion is done (see --- 4 unchanged lines hidden (view full) --- 237the database yet), 2 is returned if the record contains an unresolved 238.Nm tc 239expansion, \-1 is returned if an system error occurred, and \-2 240is returned if a potential reference loop is detected (see 241.Ic tc= 242comments below). 243Upon completion of database (0 return) the database is closed. 244.Pp |
| 257The 258.Fn cgetclose 259function closes the sequential access and frees any memory and file descriptors | 245.Nm Cgetclose 246closes the sequential access and frees any memory and file descriptors |
| 260being used. Note that it does not erase the buffer pushed by a call to | 247being used. Note that it does not erase the buffer pushed by a call to |
| 261.Fn cgetset . | 248.Nm cgetset . |
| 262.Sh CAPABILITY DATABASE SYNTAX 263Capability databases are normally 264.Tn ASCII 265and may be edited with standard 266text editors. Blank lines and lines beginning with a `#' are comments 267and are ignored. Lines ending with a `\|\e' indicate that the next line 268is a continuation of the current line; the `\|\e' and following newline 269are ignored. Long lines are usually continued onto several physical --- 39 unchanged lines hidden (view full) --- 309associated typed values. Types may be any character except a `:'. 310Typically, graphics like `#', `=', `%', etc. are used. Values may be any 311number of characters and may contain any character except `:'. 312.Sh CAPABILITY DATABASE SEMANTICS 313Capability records describe a set of (name, value) bindings. Names may 314have multiple values bound to them. Different values for a name are 315distinguished by their 316.Fa types . | 249.Sh CAPABILITY DATABASE SYNTAX 250Capability databases are normally 251.Tn ASCII 252and may be edited with standard 253text editors. Blank lines and lines beginning with a `#' are comments 254and are ignored. Lines ending with a `\|\e' indicate that the next line 255is a continuation of the current line; the `\|\e' and following newline 256are ignored. Long lines are usually continued onto several physical --- 39 unchanged lines hidden (view full) --- 296associated typed values. Types may be any character except a `:'. 297Typically, graphics like `#', `=', `%', etc. are used. Values may be any 298number of characters and may contain any character except `:'. 299.Sh CAPABILITY DATABASE SEMANTICS 300Capability records describe a set of (name, value) bindings. Names may 301have multiple values bound to them. Different values for a name are 302distinguished by their 303.Fa types . |
| 317The 318.Fn cgetcap 319function will return a pointer to a value of a name given the capability 320name and the type of the value. | 304.Nm Cgetcap 305will return a pointer to a value of a name given the capability name and 306the type of the value. |
| 321.Pp 322The types `#' and `=' are conventionally used to denote numeric and 323string typed values, but no restriction on those types is enforced. The 324functions | 307.Pp 308The types `#' and `=' are conventionally used to denote numeric and 309string typed values, but no restriction on those types is enforced. The 310functions |
| 325.Fn cgetnum | 311.Nm cgetnum |
| 326and | 312and |
| 327.Fn cgetstr | 313.Nm cgetstr |
| 328can be used to implement the traditional syntax and semantics of `#' 329and `='. 330Typeless capabilities are typically used to denote boolean objects with 331presence or absence indicating truth and false values respectively. 332This interpretation is conveniently represented by: 333.Pp 334.Dl "(getcap(buf, name, ':') != NULL)" 335.Pp --- 53 unchanged lines hidden (view full) --- 389 new\||\|new_record\||\|a modification of "old":\e 390 :fript=bar:who-cares@:tc=old:blah:tc=extensions: 391file2: 392 old\||\|old_record\||\|an old database record:\e 393 :fript=foo:who-cares:glork#200: 394.Ed 395.Pp 396The records are extracted by calling | 314can be used to implement the traditional syntax and semantics of `#' 315and `='. 316Typeless capabilities are typically used to denote boolean objects with 317presence or absence indicating truth and false values respectively. 318This interpretation is conveniently represented by: 319.Pp 320.Dl "(getcap(buf, name, ':') != NULL)" 321.Pp --- 53 unchanged lines hidden (view full) --- 375 new\||\|new_record\||\|a modification of "old":\e 376 :fript=bar:who-cares@:tc=old:blah:tc=extensions: 377file2: 378 old\||\|old_record\||\|an old database record:\e 379 :fript=foo:who-cares:glork#200: 380.Ed 381.Pp 382The records are extracted by calling |
| 397.Fn cgetent | 383.Nm cgetent |
| 398with file1 preceding file2. 399In the capability record new in file1, fript=bar overrides the definition 400of fript=foo interpolated from the capability record old in file2, 401who-cares@ prevents the definition of any who-cares definitions in old 402from being seen, glork#200 is inherited from old, and blah and anything 403defined by the record extensions is added to those definitions in old. 404Note that the position of the fript=bar and who-cares@ definitions before 405tc=old is important here. If they were after, the definitions in old 406would take precedence. 407.Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS 408Two types are predefined by | 384with file1 preceding file2. 385In the capability record new in file1, fript=bar overrides the definition 386of fript=foo interpolated from the capability record old in file2, 387who-cares@ prevents the definition of any who-cares definitions in old 388from being seen, glork#200 is inherited from old, and blah and anything 389defined by the record extensions is added to those definitions in old. 390Note that the position of the fript=bar and who-cares@ definitions before 391tc=old is important here. If they were after, the definitions in old 392would take precedence. 393.Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS 394Two types are predefined by |
| 409.Fn cgetnum | 395.Nm cgetnum |
| 410and | 396and |
| 411.Fn cgetstr : | 397.Nm cgetstr : |
| 412.Bl -column "nameXnumber" 413.Sm off 414.It Em name No \&# Em number Ta numeric 415capability 416.Em name 417has value 418.Em number 419.It Em name No = Em string Ta "string capability" --- 20 unchanged lines hidden (view full) --- 440it is interpreted as an octal number. 441Otherwise the number is interpreted as a decimal number. 442.Pp 443String capability values may contain any character. Non-printable 444.Dv ASCII 445codes, new lines, and colons may be conveniently represented by the use 446of escape sequences: 447.Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)" | 398.Bl -column "nameXnumber" 399.Sm off 400.It Em name No \&# Em number Ta numeric 401capability 402.Em name 403has value 404.Em number 405.It Em name No = Em string Ta "string capability" --- 20 unchanged lines hidden (view full) --- 426it is interpreted as an octal number. 427Otherwise the number is interpreted as a decimal number. 428.Pp 429String capability values may contain any character. Non-printable 430.Dv ASCII 431codes, new lines, and colons may be conveniently represented by the use 432of escape sequences: 433.Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)" |
| 448^X ('X' & 037) control-X | 434^X ('\fIX\fP' & 037) control-\fIX\fP |
| 449\e\|b, \e\|B (ASCII 010) backspace 450\e\|t, \e\|T (ASCII 011) tab 451\e\|n, \e\|N (ASCII 012) line feed (newline) 452\e\|f, \e\|F (ASCII 014) form feed 453\e\|r, \e\|R (ASCII 015) carriage return 454\e\|e, \e\|E (ASCII 027) escape 455\e\|c, \e\|C (:) colon 456\e\|\e (\e\|) back slash 457\e\|^ (^) caret | 435\e\|b, \e\|B (ASCII 010) backspace 436\e\|t, \e\|T (ASCII 011) tab 437\e\|n, \e\|N (ASCII 012) line feed (newline) 438\e\|f, \e\|F (ASCII 014) form feed 439\e\|r, \e\|R (ASCII 015) carriage return 440\e\|e, \e\|E (ASCII 027) escape 441\e\|c, \e\|C (:) colon 442\e\|\e (\e\|) back slash 443\e\|^ (^) caret |
| 458\e\|nnn (ASCII octal nnn) | 444\e\|\fInnn\fP (ASCII octal \fInnn\fP) |
| 459.El 460.Pp 461A `\|\e' may be followed by up to three octal digits directly specifies 462the numeric code for a character. The use of 463.Tn ASCII 464.Dv NUL Ns s , 465while easily 466encoded, causes all sorts of problems and must be used with care since 467.Dv NUL Ns s 468are typically used to denote the end of strings; many applications 469use `\e\|200' to represent a 470.Dv NUL . 471.Sh DIAGNOSTICS | 445.El 446.Pp 447A `\|\e' may be followed by up to three octal digits directly specifies 448the numeric code for a character. The use of 449.Tn ASCII 450.Dv NUL Ns s , 451while easily 452encoded, causes all sorts of problems and must be used with care since 453.Dv NUL Ns s 454are typically used to denote the end of strings; many applications 455use `\e\|200' to represent a 456.Dv NUL . 457.Sh DIAGNOSTICS |
| 472.Fn Cgetent , 473.Fn cgetset , 474.Fn cgetmatch , 475.Fn cgetnum , 476.Fn cgetstr , 477.Fn cgetustr , 478.Fn cgetfirst , | 458.Nm Cgetent , 459.Nm cgetset , 460.Nm cgetmatch , 461.Nm cgetnum , 462.Nm cgetstr , 463.Nm cgetustr , 464.Nm cgetfirst , |
| 479and | 465and |
| 480.Fn cgetnext | 466.Nm cgetnext |
| 481return a value greater than or equal to 0 on success and a value less 482than 0 on failure. | 467return a value greater than or equal to 0 on success and a value less 468than 0 on failure. |
| 483The 484.Fn cgetcap 485function returns a character pointer on success and a | 469.Nm Cgetcap 470returns a character pointer on success and a |
| 486.Dv NULL 487on failure. 488.Pp | 471.Dv NULL 472on failure. 473.Pp |
| 489The 490.Fn cgetent , | 474.Nm Cgetent , |
| 491and | 475and |
| 492.Fn cgetseq 493functions may fail and set | 476.Nm cgetseq 477may fail and set |
| 494.Va errno 495for any of the errors specified for the library functions: 496.Xr fopen 2 , 497.Xr fclose 2 , 498.Xr open 2 , 499and 500.Xr close 2 . 501.Pp | 478.Va errno 479for any of the errors specified for the library functions: 480.Xr fopen 2 , 481.Xr fclose 2 , 482.Xr open 2 , 483and 484.Xr close 2 . 485.Pp |
| 502The 503.Fn cgetent , 504.Fn cgetset , 505.Fn cgetstr , | 486.Nm Cgetent , 487.Nm cgetset , 488.Nm cgetstr , |
| 506and | 489and |
| 507.Fn cgetustr | 490.Nm cgetustr |
| 508may fail and set 509.Va errno 510as follows: 511.Bl -tag -width Er 512.It Bq Er ENOMEM 513No memory to allocate. 514.El 515.Sh SEE ALSO 516.Xr cap_mkdb 1 , 517.Xr malloc 3 518.Sh BUGS 519Colons (`:') can't be used in names, types, or values. 520.Pp 521There are no checks for 522.Ic tc= name 523loops in | 491may fail and set 492.Va errno 493as follows: 494.Bl -tag -width Er 495.It Bq Er ENOMEM 496No memory to allocate. 497.El 498.Sh SEE ALSO 499.Xr cap_mkdb 1 , 500.Xr malloc 3 501.Sh BUGS 502Colons (`:') can't be used in names, types, or values. 503.Pp 504There are no checks for 505.Ic tc= name 506loops in |
| 524.Fn cgetent . | 507.Nm cgetent . |
| 525.Pp 526The buffer added to the database by a call to | 508.Pp 509The buffer added to the database by a call to |
| 527.Fn cgetset | 510.Nm cgetset |
| 528is not unique to the database but is rather prepended to any database used. | 511is not unique to the database but is rather prepended to any database used. |