1.\" $NetBSD: cgetcap.3,v 1.10 2022/12/04 01:29:32 uwe Exp $ 2.\" 3.\" Copyright (c) 1992, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Casey Leedom of Lawrence Livermore National Laboratory. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" @(#)getcap.3 8.4 (Berkeley) 5/13/94 34.\" 35.Dd April 5, 2012 36.Dt CGETCAP 3 37.Os 38.Sh NAME 39.Nm cgetent , 40.Nm cgetset , 41.Nm cgetmatch , 42.Nm cgetcap , 43.Nm cgetnum , 44.Nm cgetstr , 45.Nm cgetustr , 46.Nm cgetfirst , 47.Nm cgetnext , 48.Nm cgetclose , 49.Nm csetexpandtc 50.Nd capability database access routines 51.Sh LIBRARY 52.Lb libc 53.Sh SYNOPSIS 54.In stdlib.h 55.Ft int 56.Fn cgetent "char **buf" "const char * const *db_array" "const char *name" 57.Ft int 58.Fn cgetset "const char *ent" 59.Ft int 60.Fn cgetmatch "const char *buf" "const char *name" 61.Ft char * 62.Fn cgetcap "char *buf" "const char *cap" "int type" 63.Ft int 64.Fn cgetnum "char *buf" "const char *cap" "long *num" 65.Ft int 66.Fn cgetstr "char *buf" "const char *cap" "char **str" 67.Ft int 68.Fn cgetustr "char *buf" "const char *cap" "char **str" 69.Ft int 70.Fn cgetfirst "char **buf" "const char * const *db_array" 71.Ft int 72.Fn cgetnext "char **buf" "const char * const *db_array" 73.Ft int 74.Fn cgetclose "void" 75.Ft void 76.Fn csetexpandtc "int expandtc" 77.Sh DESCRIPTION 78.Fn cgetent 79extracts the capability 80.Fa name 81from the database specified by the 82.Dv NULL 83terminated file array 84.Fa db_array 85and returns a pointer to a 86.Xr malloc 3 Ap d 87copy of it in 88.Fa buf . 89.Fn cgetent 90will first look for files ending in 91.Pa .db 92(see 93.Xr cap_mkdb 1 ) 94before accessing the 95.Tn ASCII 96file. 97.Pp 98.Fa buf 99must be retained through all subsequent calls to 100.Fn cgetmatch , 101.Fn cgetcap , 102.Fn cgetnum , 103.Fn cgetstr , 104and 105.Fn cgetustr , 106but may then be 107.Xr free 3 Ap d . 108.Pp 109On success 0 is returned, 1 if the returned record contains an unresolved 110.Qq tc 111expansion, \-1 if the requested record couldn't be found, \-2 if 112a system error was encountered (couldn't open/read a file, etc.) 113also setting 114.Va errno , 115and \-3 if a potential reference loop is detected (see 116.Qq tc=name 117comments below). 118.Pp 119.Fn cgetset 120enables the addition of a character buffer containing a single capability 121record entry to the capability database. 122Conceptually, the entry is added as the first 123.Dq file 124in the database, and 125is therefore searched first on the call to 126.Fn cgetent . 127The entry is passed in 128.Fa ent . 129If 130.Fa ent 131is 132.Dv NULL , 133the current entry is removed from the database. 134.Pp 135.Fn cgetset 136must precede the database traversal. 137It must be called before the 138.Fn cgetent 139call. 140If a sequential access is being performed (see below), it must be called 141before the first sequential access call 142.Po 143.Fn cgetfirst 144or 145.Fn cgetnext 146.Pc , 147or be directly preceded by a 148.Fn cgetclose 149call. 150On success 0 is returned and \-1 on failure. 151.Pp 152.Fn cgetmatch 153will return 0 if 154.Fa name 155is one of the names of the capability record 156.Fa buf , 157\-1 if not. 158.Pp 159.Fn cgetcap 160searches the capability record 161.Fa buf 162for the capability 163.Fa cap 164with type 165.Fa type . 166A 167.Fa type 168is specified using any single character. 169If a colon 170.Pq Sq \&: 171is used, an untyped capability will be searched 172for (see below for explanation of types). 173A pointer to the value of 174.Fa cap 175in 176.Fa buf 177is returned on success, 178.Dv NULL 179if the requested capability couldn't be found. 180The end of the capability value is signaled by a 181.Sq \&: . 182See 183.Xr capfile 5 184for a description of the capability syntax. 185.Pp 186.Fn cgetnum 187retrieves the value of the numeric capability 188.Fa cap 189from the capability record pointed to by 190.Fa buf . 191The numeric value is returned in the 192.Ft long 193pointed to by 194.Fa num . 1950 is returned on success, 196\-1 if the requested numeric capability couldn't be found. 197.Pp 198.Fn cgetstr 199retrieves 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 Ap 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 217.Fn cgetustr 218is identical to 219.Fn cgetstr 220except that it does not expand special characters, but rather returns each 221character of the capability string literally. 222.Pp 223.Fn cgetfirst , 224.Fn cgetnext , 225comprise a function group that provides for sequential access of the 226.Dv NULL 227pointer terminated array of file names, 228.Fa db_array . 229.Fn cgetfirst 230returns the first record in the database and resets the access 231to the first record. 232.Fn cgetnext 233returns the next record in the database with respect to the 234record returned by the previous 235.Fn cgetfirst 236or 237.Fn cgetnext 238call. 239If there is no such previous call, 240the first record in the database is returned. 241Each record is returned in a 242.Xr malloc 3 Ap d 243copy pointed to by 244.Fa buf . 245.Qq tc 246expansion is done (see 247.Qq tc=name 248comments below). 249.Pp 250Upon completion of the database 0 is returned, 1 is returned upon successful 251return of record with possibly more remaining (we haven't reached the end of 252the database yet), 2 is returned if the record contains an unresolved 253.Qq tc 254expansion, \-1 is returned if an system error occurred, and \-2 255is returned if a potential reference loop is detected (see 256.Qq tc=name 257comments below). 258Upon completion of database (0 return) the database is closed. 259.Pp 260.Fn cgetclose 261closes the sequential access and frees any memory and file descriptors 262being used. 263Note that it does not erase the buffer pushed by a call to 264.Fn cgetset . 265.Sh CAPABILITY DATABASE SEMANTICS 266Capability records describe a set of (name, value) bindings. 267Names may have multiple values bound to them. 268Different values for a name are distinguished by their 269.Fa types . 270.Fn cgetcap 271will return a pointer to a value of a name given the capability name and 272the type of the value. 273.Pp 274The types 275.Sq # 276and 277.Sq = 278are conventionally used to denote numeric and 279string typed values, but no restriction on those types is enforced. 280The functions 281.Fn cgetnum 282and 283.Fn cgetstr 284can be used to implement the traditional syntax and semantics of 285.Sq # 286and 287.Sq = . 288Typeless capabilities are typically used to denote boolean objects with 289presence or absence indicating truth and false values respectively. 290This interpretation is conveniently represented by: 291.Pp 292.Dl "(getcap(buf, name, ':') != NULL)" 293.Pp 294A special capability, 295.Qq tc=name , 296is used to indicate that the record specified by 297.Fa name 298should be substituted for the 299.Qq tc 300capability. 301.Qq tc 302capabilities may interpolate records which also contain 303.Qq tc 304capabilities and more than one 305.Qq tc 306capability may be used in a record. 307A 308.Qq tc 309expansion scope (i.e. where the argument is searched for) contains the 310file in which the 311.Qq tc 312is declared and all subsequent files in the file array. 313.Pp 314.Fn csetexpandtc 315can be used to control if 316.Qq tc 317expansion is performed or not. 318.Sh RETURN VALUES 319.Fn cgetent , 320.Fn cgetset , 321.Fn cgetmatch , 322.Fn cgetnum , 323.Fn cgetstr , 324.Fn cgetustr , 325.Fn cgetfirst , 326and 327.Fn cgetnext 328return a value greater than or equal to 0 on success and a value less 329than 0 on failure. 330.Fn cgetcap 331returns a character pointer on success and a 332.Dv NULL 333on failure. 334.Pp 335.Fn cgetclose , 336.Fn cgetent , 337.Fn cgetfirst , 338and 339.Fn cgetnext 340may fail and set 341.Va errno 342for any of the errors specified for the library functions: 343.Xr fopen 3 , 344.Xr fclose 3 , 345.Xr open 2 , 346and 347.Xr close 2 . 348.Pp 349.Fn cgetent , 350.Fn cgetset , 351.Fn cgetstr , 352and 353.Fn cgetustr 354may fail and set 355.Va errno 356as follows: 357.Bl -tag -width Er 358.It Bq Er ENOMEM 359No memory to allocate. 360.El 361.Sh SEE ALSO 362.Xr cap_mkdb 1 , 363.Xr malloc 3 , 364.Xr capfile 5 365.Sh BUGS 366There are no checks for 367.Qq tc=name 368loops in 369.Fn cgetent . 370.Pp 371The buffer added to the database by a call to 372.Fn cgetset 373is not unique to the database but is rather prepended to any database used. 374