1GETCAP(3) 386BSD Programmer's Manual GETCAP(3) 2 3NNAAMMEE 4 ccggeetteenntt, ccggeettsseett, ccggeettmmaattcchh, ccggeettccaapp, ccggeettnnuumm, ccggeettssttrr, ccggeettuussttrr, 5 ccggeettffiirrsstt, ccggeettnneexxtt, ccggeettcclloossee - capability database access routines 6 7SSYYNNOOPPSSIISS 8 ##iinncclluuddee <<ssttddlliibb..hh>> 9 10 _i_n_t 11 ccggeetteenntt(_c_h_a_r **_b_u_f, _c_h_a_r **_d_b__a_r_r_a_y, _c_h_a_r *_n_a_m_e) 12 13 _i_n_t 14 ccggeettsseett(_c_h_a_r *_e_n_t) 15 16 _i_n_t 17 ccggeettmmaattcchh(_c_h_a_r *_b_u_f, _c_h_a_r *_n_a_m_e) 18 19 _c_h_a_r * 20 ccggeettccaapp(_c_h_a_r *_b_u_f, _c_h_a_r *_c_a_p, _c_h_a_r _t_y_p_e) 21 22 _i_n_t 23 ccggeettnnuumm(_c_h_a_r *_b_u_f, _c_h_a_r *_c_a_p, _l_o_n_g *_n_u_m) 24 25 _i_n_t 26 ccggeettssttrr(_c_h_a_r *_b_u_f, _c_h_a_r *_c_a_p, _c_h_a_r **_s_t_r) 27 28 _i_n_t 29 ccggeettuussttrr(_c_h_a_r *_b_u_f, _c_h_a_r *_c_a_p, _c_h_a_r **_s_t_r) 30 31 _i_n_t 32 ccggeettffiirrsstt(_c_h_a_r **_b_u_f, _c_h_a_r **_d_b__a_r_r_a_y) 33 34 _i_n_t 35 ccggeettnneexxtt(_c_h_a_r **_b_u_f, _c_h_a_r **_d_b__a_r_r_a_y) 36 37 _i_n_t 38 ccggeettcclloossee(_v_o_i_d) 39 40DDEESSCCRRIIPPTTIIOONN 41 CCggeetteenntt() extracts the capability rec _n_a_m_e from the database specified by 42 the NULL terminated file array _d_b__a_r_r_a_y and returns a pointer to a 43 malloc'd copy of it in _b_u_f. CCggeetteenntt will first look for files ending in 44 ..ddbb (see cap_mkdb(1)) before accessing the ASCII file. _B_u_f must be 45 retained through all subsequent calls to ccggeettmmaattcchh(), ccggeettccaapp(), 46 ccggeettnnuumm(), ccggeettssttrr(), and ccggeettuussttrr(), but may then be free'd. On success 47 0 is returned, 1 if the returned record contains an unresolved ttcc 48 expansion, -1 if the requested record couldn't be found, -2 if a system 49 error was encountered (couldn't open/read a file, etc.) also setting 50 _e_r_r_n_o, and -3 if a potential reference loop is detected (see ttcc== comments 51 below). 52 53 CCggeettsseett enables the addition of a character buffer containing a single 54 capability record entry to the capability database. Conceptually, the 55 entry is added as the first ``file'' in the database, and is therefore 56 searched first on the call to ccggeetteenntt. The entry is passed in _e_n_t. If _e_n_t 57 is NULL, the current entry is removed from the database. CCggeettsseett must 58 precede the database traversal. It must be called before the ccggeetteenntt 59 call. If a sequential access is being performed (see below), it must be 60 called before the first sequential access call ( ccggeettffiirrsstt or ccggeettnneexxtt ), 61 or be directly preceded by a ccggeettcclloossee call. On success 0 is returned 62 and -1 on failure. 63 64 CCggeettmmaattcchh will return 0 if _n_a_m_e is one of the names of the capability 65 record _b_u_f, -1 if not. 66 67 CCggeettccaapp searches the capability record _b_u_f for the capability _c_a_p with 68 type _t_y_p_e. A _t_y_p_e is specified using any single character. If a colon 69 (`:') is used, an untyped capability will be searched for (see below for 70 explanation of types). A pointer to the value of _c_a_p in _b_u_f is returned 71 on success, NULL if the requested capability couldn't be found. The end 72 of the capability value is signaled by a `:' or ASCII NUL (see below for 73 capability database syntax). 74 75 CCggeettnnuumm retrieves the value of the numeric capability _c_a_p from the 76 capability record pointed to by _b_u_f. The numeric value is returned in the 77 _l_o_n_g pointed to by _n_u_m. 0 is returned on success, -1 if the requested 78 numeric capability couldn't be found. 79 80 CCggeettssttrr retrieves the value of the string capability _c_a_p from the 81 capability record pointed to by _b_u_f. A pointer to a decoded, NUL 82 terminated, malloc'd copy of the string is returned in the _c_h_a_r * 83 pointed to by _s_t_r. The number of characters in the decoded string not 84 including the trailing NUL is returned on success, -1 if the requested 85 string capability couldn't be found, -2 if a system error was encountered 86 (storage allocation failure). 87 88 CCggeettuussttrr is identical to ccggeettssttrr except that it does not expand special 89 characters, but rather returns each character of the capability string 90 literally. 91 92 CCggeettffiirrsstt, ccggeettnneexxtt, comprise a function group that provides for 93 sequential access of the NULL pointer terminated array of file names, 94 _d_b__a_r_r_a_y. CCggeettffiirrsstt returns the first record in the database and resets 95 the access to the first record. CCggeettnneexxtt returns the next record in the 96 database with respect to the record returned by the previous ccggeettffiirrsstt or 97 ccggeettnneexxtt call. If there is no such previous call, the first record in 98 the database is returned. Each record is returned in a malloc'd copy 99 pointed to by _b_u_f. TTcc expansion is done (see ttcc== comments below). Upon 100 completion of the database 0 is returned, 1 is returned upon successful 101 return of record with possibly more remaining (we haven't reached the end 102 of the database yet), 2 is returned if the record contains an unresolved 103 ttcc expansion, -1 is returned if an system error occured, and -2 is 104 returned if a potential reference loop is detected (see ttcc== comments 105 below). Upon completion of database (0 return) the database is closed. 106 107 CCggeettcclloossee closes the sequential access and frees any memory and file 108 descriptors being used. Note that it does not erase the buffer pushed by 109 a call to ccggeettsseett. 110 111CCAAPPAABBIILLIITTYY DDAATTAABBAASSEE SSYYNNTTAAXX 112 Capability databases are normally ASCII and may be edited with standard 113 text editors. Blank lines and lines beginning with a `#' are comments 114 and are ignored. Lines ending with a `\' indicate that the next line is 115 a continuation of the current line; the `\' and following newline are 116 ignored. Long lines are usually continued onto several physical lines by 117 ending each line except the last with a `\'. 118 119 Capability databases consist of a series of records, one per logical 120 line. Each record contains a variable number of `:'-separated fields 121 (capabilities). Empty fields consisting entirely of white space 122 characters (spaces and tabs) are ignored. 123 124 The first capability of each record specifies its names, separated by `|' 125 characters. These names are used to reference records in the database. 126 By convention, the last name is usually a comment and is not intended as 127 a lookup tag. For example, the _v_t_1_0_0 record from the tteerrmmccaapp database 128 begins: 129 130 d0|vt100|vt100-am|vt100am|dec vt100: 131 132 133 giving four names that can be used to access the record. 134 135 The remaining non-empty capabilities describe a set of (name, value) 136 bindings, consisting of a names optionally followed by a typed values: 137 138 name typeless [boolean] capability _n_a_m_e is present [true] 139 name_Tvalue capability (_n_a_m_e, _T) has value _v_a_l_u_e 140 name@ no capability _n_a_m_e exists 141 name_T@ capability (_n_a_m_e, _T) does not exist 142 143 Names consist of one or more characters. Names may contain any character 144 except `:', but it's usually best to restrict them to the printable 145 characters and avoid use of graphics like `#', `=', `%', `@', etc. Types 146 are single characters used to separate capability names from their 147 associated typed values. Types may be any character except a `:'. 148 Typically, graphics like `#', `=', `%', etc. are used. Values may be any 149 number of characters and may contain any character except `:'. 150 151CCAAPPAABBIILLIITTYY DDAATTAABBAASSEE SSEEMMAANNTTIICCSS 152 Capability records describe a set of (name, value) bindings. Names may 153 have multiple values bound to them. Different values for a name are 154 distinguished by their _t_y_p_e_s. CCggeettccaapp will return a pointer to a value of 155 a name given the capability name and the type of the value. 156 157 The types `#' and `=' are conventionally used to denote numeric and 158 string typed values, but no restriction on those types is enforced. The 159 functions ccggeettnnuumm and ccggeettssttrr can be used to implement the traditional 160 syntax and semantics of `#' and `='. Typeless capabilities are typically 161 used to denote boolean objects with presence or absence indicating truth 162 and false values respectively. This interpretation is conveniently 163 represented by: 164 165 (getcap(buf, name, ':') != NULL) 166 167 A special capability, ttcc== nnaammee, is used to indicate that the record 168 specified by _n_a_m_e should be substituted for the ttcc capability. TTcc 169 capabilities may interpolate records which also contain ttcc capabilities 170 and more than one ttcc capability may be used in a record. A ttcc expansion 171 scope (i.e., where the argument is searched for) contains the file in 172 which the ttcc is declared and all subsequent files in the file array. 173 174 When a database is searched for a capability record, the first matching 175 record in the search is returned. When an record is scanned for a 176 capability, the first matching capability is returned; the capability 177 ::nnaammeeTT@@:: will hide any following definition of a value of type _T for 178 _n_a_m_e; and the capability ::nnaammee@@:: will prevent any following values of 179 _n_a_m_e from being seen. 180 181 These features combined with ttcc capabilities can be used to generate 182 variations of other databases and records by either adding new 183 capabilities, overriding definitions with new definitions, or hiding 184 following definitions via `@' capabilities. 185 186EEXXAAMMPPLLEESS 187 example|an example of binding multiple values to names:\ 188 :foo%bar:foo^blah:foo@:\ 189 :abc%xyz:abc^frap:abc$@:\ 190 :tc=more: 191 192 The capability foo has two values bound to it (bar of type `%' and blah 193 of type `^') and any other value bindings are hidden. The capability abc 194 also has two values bound but only a value of type `$' is prevented from 195 being defined in the capability record more. 196 197 198 file1: 199 new|new_record|a modification of "old":\ 200 :fript=bar:who-cares@:tc=old:blah:tc=extensions: 201 file2: 202 old|old_record|an old database record:\ 203 :fript=foo:who-cares:glork#200: 204 205 The records are extracted by calling ccggeetteenntt with file1 preceding file2. 206 In the capability record new in file1, fript=bar overrides the definition 207 of fript=foo interpolated from the capability record old in file2, who- 208 cares@ prevents the definition of any who-cares definitions in old from 209 being seen, glork#200 is inherited from old, and blah and anything 210 defined by the record extensions is added to those definitions in old. 211 Note that the position of the fript=bar and who-cares@ definitions before 212 tc=old is important here. If they were after, the definitions in old 213 would take precedence. 214 215CCGGEETTNNUUMM AANNDD CCGGEETTSSTTRR SSYYNNTTAAXX AANNDD SSEEMMAANNTTIICCSS 216 Two types are predefined by ccggeettnnuumm and ccggeettssttrr: 217 218 _n_a_m_e#_n_u_m_b_e_r numeric capability _n_a_m_e has value _n_u_m_b_e_r 219 _n_a_m_e=_s_t_r_i_n_g string capability _n_a_m_e has value _s_t_r_i_n_g 220 _n_a_m_e#@ the numeric capability _n_a_m_e does not exist 221 _n_a_m_e=@ the string capability _n_a_m_e does not exist 222 223 Numeric capability values may be given in one of three numeric bases. If 224 the number starts with either `0x' or `0X' it is interpreted as a 225 hexadecimal number (both upper and lower case a-f may be used to denote 226 the extended hexadecimal digits). Otherwise, if the number starts with a 227 `0' it is interpreted as an octal number. Otherwise the number is 228 interpreted as a decimal number. 229 230 String capability values may contain any character. Non-printable ASCII 231 codes, new lines, and colons may be conveniently represented by the use 232 of escape sequences: 233 234 ^X ('_X' & 037) control-_X 235 \b, \B (ASCII 010) backspace 236 \t, \T (ASCII 011) tab 237 \n, \N (ASCII 012) line feed (newline) 238 \f, \F (ASCII 014) form feed 239 \r, \R (ASCII 015) carriage return 240 \e, \E (ASCII 027) escape 241 \c, \C (:) colon 242 \\ (\) back slash 243 \^ (^) caret 244 \_n_n_n (ASCII octal _n_n_n) 245 246 A `\' may be followed by up to three octal digits directly specifies the 247 numeric code for a character. The use of ASCII NULs, while easily 248 encoded, causes all sorts of problems and must be used with care since 249 NULs are typically used to denote the end of strings; many applications 250 use `\200' to represent a NUL. 251 252DDIIAAGGNNOOSSTTIICCSS 253 CCggeetteenntt, ccggeettsseett, ccggeettmmaattcchh, ccggeettnnuumm, ccggeettssttrr, ccggeettuussttrr, ccggeettffiirrsstt, and 254 ccggeettnneexxtt return a a value greater than or equal to 0 on success and a 255 value less than 0 on failure. CCggeettccaapp returns a character pointer on 256 success and a NULL on failure. 257 258 CCggeetteenntt, and ccggeettsseeqq may fail and set _e_r_r_n_o for any of the errors 259 specified for the library functions: fopen(2), fclose(2), open(2), and 260 close(2). 261 262 CCggeetteenntt, ccggeettsseett, ccggeettssttrr, and ccggeettuussttrr may fail and set _e_r_r_n_o as 263 264 follows: 265 266 [ENOMEM] No memory to allocate. 267 268SSEEEE AALLSSOO 269 cap_mkdb(1), malloc(3) 270 271BBUUGGSS 272 Colons (`:') can't be used in names, types, or values. 273 274 There are no checks for ttcc==nnaammee loops in ccggeetteenntt. 275 276 The buffer added to the database by a call to ccggeettsseett is not unique to 277 the database but is rather prepended to any database used. 278 279BSD Experimental August 11, 1992 5 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331