Commit | Line | Data |
---|---|---|
74155b62 KB |
1 | .\" Copyright (c) 1992, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
a1dc6928 KB |
3 | .\" |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" Casey Leedom of Lawrence Livermore National Laboratory. | |
6 | .\" | |
7 | .\" %sccs.include.redist.roff% | |
8 | .\" | |
653ba8b6 | 9 | .\" @(#)getcap.3 8.2 (Berkeley) %G% |
a1dc6928 KB |
10 | .\" |
11 | .Dd "" | |
12 | .Dt GETCAP 3 | |
13 | .Os | |
14 | .Sh NAME | |
15 | .Nm cgetent , | |
16 | .Nm cgetset , | |
17 | .Nm cgetmatch , | |
18 | .Nm cgetcap , | |
19 | .Nm cgetnum , | |
20 | .Nm cgetstr , | |
21 | .Nm cgetustr , | |
22 | .Nm cgetfirst , | |
23 | .Nm cgetnext , | |
24 | .Nm cgetclose | |
25 | .Nd capability database access routines | |
26 | .Sh SYNOPSIS | |
27 | .Fd #include <stdlib.h> | |
28 | .Ft int | |
29 | .Fn cgetent "char **buf" "char **db_array" "char *name" | |
30 | .Ft int | |
31 | .Fn cgetset "char *ent" | |
32 | .Ft int | |
33 | .Fn cgetmatch "char *buf" "char *name" | |
34 | .Ft char * | |
35 | .Fn cgetcap "char *buf" "char *cap" "char type" | |
36 | .Ft int | |
37 | .Fn cgetnum "char *buf" "char *cap" "long *num" | |
38 | .Ft int | |
39 | .Fn cgetstr "char *buf" "char *cap" "char **str" | |
40 | .Ft int | |
41 | .Fn cgetustr "char *buf" "char *cap" "char **str" | |
42 | .Ft int | |
43 | .Fn cgetfirst "char **buf" "char **db_array" | |
44 | .Ft int | |
45 | .Fn cgetnext "char **buf" "char **db_array" | |
46 | .Ft int | |
47 | .Fn cgetclose "void" | |
48 | .Sh DESCRIPTION | |
49 | .Fn Cgetent | |
50 | extracts the capability rec | |
51 | .Fa name | |
7e44f1ef CL |
52 | from the database specified by the |
53 | .Dv NULL | |
54 | terminated file array | |
a1dc6928 KB |
55 | .Fa db_array |
56 | and returns a pointer to a | |
7e44f1ef | 57 | .Xr malloc Ns \&'d |
a1dc6928 | 58 | copy of it in |
c49bb0ed EA |
59 | .Fa buf . |
60 | .Nm Cgetent | |
61 | will first look for files ending in | |
62 | .Nm .db | |
63 | (see | |
64 | .Xr cap_mkdb 1) | |
65 | before accessing the ASCII file. | |
a1dc6928 KB |
66 | .Fa Buf |
67 | must be retained through all subsequent calls to | |
68 | .Fn cgetmatch , | |
69 | .Fn cgetcap , | |
70 | .Fn cgetnum , | |
71 | .Fn cgetstr , | |
72 | and | |
73 | .Fn cgetustr , | |
74 | but may then be | |
7e44f1ef | 75 | .Xr free Ns \&'d. |
c49bb0ed EA |
76 | On success 0 is returned, 1 if the returned |
77 | record contains an unresolved | |
78 | .Nm tc | |
79 | expansion, | |
80 | \-1 if the requested record couldn't be found, | |
a1dc6928 KB |
81 | \-2 if a system error was encountered (couldn't open/read a file, etc.) also |
82 | setting | |
83 | .Va errno , | |
84 | and \-3 if a potential reference loop is detected (see | |
7e44f1ef | 85 | .Ic tc= |
a1dc6928 KB |
86 | comments below). |
87 | .Pp | |
88 | .Nm Cgetset | |
89 | enables the addition of a character buffer containing a single capability | |
90 | record entry | |
91 | to the capability database. | |
92 | Conceptually, the entry is added as the first ``file'' in the database, and | |
93 | is therefore searched first on the call to | |
94 | .Nm cgetent . | |
95 | The entry is passed in | |
96 | .Fa ent . | |
97 | If | |
98 | .Fa ent | |
7e44f1ef CL |
99 | is |
100 | .Dv NULL , | |
60cb1750 EA |
101 | the current entry is removed from the database. |
102 | .Nm Cgetset | |
103 | must precede the database traversal. It must be called before the | |
104 | .Nm cgetent | |
105 | call. If a sequential access is being performed (see below), it must be called | |
106 | before the first sequential access call ( | |
107 | .Nm cgetfirst | |
108 | or | |
109 | .Nm cgetnext | |
110 | ), or be directly preceded by a | |
111 | .Nm cgetclose | |
112 | call. | |
a1dc6928 KB |
113 | On success 0 is returned and \-1 on failure. |
114 | .Pp | |
115 | .Nm Cgetmatch | |
116 | will return 0 if | |
117 | .Fa name | |
118 | is one of the names of the capability record | |
119 | .Fa buf , | |
120 | \-1 if | |
121 | not. | |
122 | .Pp | |
123 | .Nm Cgetcap | |
124 | searches the capability record | |
125 | .Fa buf | |
126 | for the capability | |
127 | .Fa cap | |
128 | with type | |
129 | .Fa type . | |
130 | A | |
131 | .Fa type | |
132 | is specified using any single character. If a colon (`:') is used, an | |
133 | untyped capability will be searched for (see below for explanation of | |
134 | types). A pointer to the value of | |
135 | .Fa cap | |
136 | in | |
137 | .Fa buf | |
7e44f1ef CL |
138 | is returned on success, |
139 | .Dv NULL | |
140 | if the requested capability couldn't be | |
141 | found. The end of the capability value is signaled by a `:' or | |
142 | .Tn ASCII | |
143 | .Dv NUL | |
a1dc6928 KB |
144 | (see below for capability database syntax). |
145 | .Pp | |
146 | .Nm Cgetnum | |
147 | retrieves the value of the numeric capability | |
148 | .Fa cap | |
149 | from the capability record pointed to by | |
150 | .Fa buf . | |
151 | The numeric value is returned in the | |
152 | .Ft long | |
153 | pointed to by | |
154 | .Fa num . | |
155 | 0 is returned on success, \-1 if the requested numeric capability couldn't | |
156 | be found. | |
157 | .Pp | |
158 | .Nm Cgetstr | |
159 | retrieves the value of the string capability | |
160 | .Fa cap | |
161 | from the capability record pointed to by | |
162 | .Fa buf . | |
7e44f1ef CL |
163 | A pointer to a decoded, |
164 | .Dv NUL | |
165 | terminated, | |
166 | .Xr malloc Ns \&'d | |
a1dc6928 KB |
167 | copy of the string is returned in the |
168 | .Ft char * | |
169 | pointed to by | |
170 | .Fa str . | |
171 | The number of characters in the decoded string not including the trailing | |
7e44f1ef CL |
172 | .Dv NUL |
173 | is returned on success, \-1 if the requested string capability couldn't | |
a1dc6928 KB |
174 | be found, \-2 if a system error was encountered (storage allocation |
175 | failure). | |
176 | .Pp | |
177 | .Nm Cgetustr | |
178 | is identical to | |
179 | .Nm cgetstr | |
180 | except that it does not expand special characters, but rather returns each | |
181 | character of the capability string literally. | |
182 | .Pp | |
183 | .Nm Cgetfirst , | |
184 | .Nm cgetnext , | |
a1dc6928 | 185 | comprise a function group that provides for sequential |
7e44f1ef CL |
186 | access of the |
187 | .Dv NULL | |
188 | pointer terminated array of file names, | |
a1dc6928 KB |
189 | .Fa db_array . |
190 | .Nm Cgetfirst | |
191 | returns the first record in the database and resets the access | |
192 | to the first record. | |
193 | .Nm Cgetnext | |
194 | returns the next record in the database with respect to the | |
195 | record returned by the previous | |
196 | .Nm cgetfirst | |
197 | or | |
198 | .Nm cgetnext | |
199 | call. If there is no such previous call, the first record in the database is | |
200 | returned. | |
a1dc6928 | 201 | Each record is returned in a |
7e44f1ef | 202 | .Xr malloc Ns \&'d |
a1dc6928 KB |
203 | copy pointed to by |
204 | .Fa buf . | |
7e44f1ef | 205 | .Ic Tc |
a1dc6928 | 206 | expansion is done (see |
7e44f1ef | 207 | .Ic tc= |
a1dc6928 KB |
208 | comments below). |
209 | Upon completion of the database 0 is returned, 1 is returned upon successful | |
210 | return of record with possibly more remaining (we haven't reached the end of | |
c49bb0ed EA |
211 | the database yet), 2 is returned if the record contains an unresolved |
212 | .Nm tc | |
213 | expansion, \-1 is returned if an system error occured, and \-2 | |
a1dc6928 | 214 | is returned if a potential reference loop is detected (see |
7e44f1ef | 215 | .Ic tc= |
a1dc6928 KB |
216 | comments below). |
217 | Upon completion of database (0 return) the database is closed. | |
60cb1750 EA |
218 | .Pp |
219 | .Nm Cgetclose | |
220 | closes the sequential access and frees any memory and file descriptors | |
221 | being used. Note that it does not erase the buffer pushed by a call to | |
222 | .Nm cgetset . | |
a1dc6928 | 223 | .Sh CAPABILITY DATABASE SYNTAX |
7e44f1ef CL |
224 | Capability databases are normally |
225 | .Tn ASCII | |
226 | and may be edited with standard | |
a1dc6928 KB |
227 | text editors. Blank lines and lines beginning with a `#' are comments |
228 | and are ignored. Lines ending with a `\|\e' indicate that the next line | |
229 | is a continuation of the current line; the `\|\e' and following newline | |
230 | are ignored. Long lines are usually continued onto several physical | |
231 | lines by ending each line except the last with a `\|\e'. | |
232 | .Pp | |
233 | Capability databases consist of a series of records, one per logical | |
234 | line. Each record contains a variable number of `:'-separated fields | |
235 | (capabilities). Empty fields consisting entirely of white space | |
236 | characters (spaces and tabs) are ignored. | |
237 | .Pp | |
238 | The first capability of each record specifies its names, separated by `|' | |
239 | characters. These names are used to reference records in the database. | |
240 | By convention, the last name is usually a comment and is not intended as | |
241 | a lookup tag. For example, the | |
7e44f1ef | 242 | .Em vt100 |
a1dc6928 KB |
243 | record from the |
244 | .Nm termcap | |
245 | database begins: | |
246 | .Pp | |
247 | .Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:" | |
248 | .Pp | |
249 | giving four names that can be used to access the record. | |
250 | .Pp | |
251 | The remaining non-empty capabilities describe a set of (name, value) | |
252 | bindings, consisting of a names optionally followed by a typed values: | |
7e44f1ef CL |
253 | .Bl -column "nameTvalue" |
254 | .It name Ta "typeless [boolean] capability" | |
255 | .Em name No "is present [true]" | |
256 | .It name Ns Em \&T Ns value Ta capability | |
257 | .Pq Em name , \&T | |
258 | has value | |
259 | .Em value | |
260 | .It name@ Ta "no capability" Em name No exists | |
261 | .It name Ns Em T Ns \&@ Ta capability | |
262 | .Pq Em name , T | |
263 | does not exist | |
264 | .El | |
a1dc6928 KB |
265 | .Pp |
266 | Names consist of one or more characters. Names may contain any character | |
267 | except `:', but it's usually best to restrict them to the printable | |
268 | characters and avoid use of graphics like `#', `=', `%', `@', etc. Types | |
269 | are single characters used to separate capability names from their | |
270 | associated typed values. Types may be any character except a `:'. | |
271 | Typically, graphics like `#', `=', `%', etc. are used. Values may be any | |
272 | number of characters and may contain any character except `:'. | |
273 | .Sh CAPABILITY DATABASE SEMANTICS | |
274 | Capability records describe a set of (name, value) bindings. Names may | |
275 | have multiple values bound to them. Different values for a name are | |
276 | distinguished by their | |
277 | .Fa types . | |
278 | .Nm Cgetcap | |
279 | will return a pointer to a value of a name given the capability name and | |
280 | the type of the value. | |
281 | .Pp | |
282 | The types `#' and `=' are conventionally used to denote numeric and | |
283 | string typed values, but no restriction on those types is enforced. The | |
284 | functions | |
285 | .Nm cgetnum | |
286 | and | |
287 | .Nm cgetstr | |
288 | can be used to implement the traditional syntax and semantics of `#' | |
289 | and `='. | |
290 | Typeless capabilities are typically used to denote boolean objects with | |
291 | presence or absence indicating truth and false values respectively. | |
292 | This interpretation is conveniently represented by: | |
293 | .Pp | |
294 | .Dl "(getcap(buf, name, ':') != NULL)" | |
295 | .Pp | |
296 | A special capability, | |
7e44f1ef | 297 | .Ic tc= name , |
a1dc6928 KB |
298 | is used to indicate that the record specified by |
299 | .Fa name | |
300 | should be substituted for the | |
7e44f1ef | 301 | .Ic tc |
a1dc6928 | 302 | capability. |
7e44f1ef | 303 | .Ic Tc |
a1dc6928 | 304 | capabilities may interpolate records which also contain |
7e44f1ef | 305 | .Ic tc |
a1dc6928 | 306 | capabilities and more than one |
7e44f1ef | 307 | .Ic tc |
a1dc6928 | 308 | capability may be used in a record. A |
7e44f1ef | 309 | .Ic tc |
a1dc6928 KB |
310 | expansion scope (i.e., where the argument is searched for) contains the |
311 | file in which the | |
7e44f1ef | 312 | .Ic tc |
a1dc6928 KB |
313 | is declared and all subsequent files in the file array. |
314 | .Pp | |
315 | When a database is searched for a capability record, the first matching | |
653ba8b6 | 316 | record in the search is returned. When a record is scanned for a |
a1dc6928 | 317 | capability, the first matching capability is returned; the capability |
7e44f1ef | 318 | .Ic :nameT@: |
a1dc6928 | 319 | will hide any following definition of a value of type |
7e44f1ef | 320 | .Em T |
a1dc6928 KB |
321 | for |
322 | .Fa name ; | |
323 | and the capability | |
7e44f1ef | 324 | .Ic :name@: |
a1dc6928 KB |
325 | will prevent any following values of |
326 | .Fa name | |
327 | from being seen. | |
328 | .Pp | |
329 | These features combined with | |
7e44f1ef | 330 | .Ic tc |
a1dc6928 KB |
331 | capabilities can be used to generate variations of other databases and |
332 | records by either adding new capabilities, overriding definitions with new | |
333 | definitions, or hiding following definitions via `@' capabilities. | |
334 | .Sh EXAMPLES | |
335 | .Bd -unfilled -offset indent | |
336 | example\||\|an example of binding multiple values to names:\e | |
337 | :foo%bar:foo^blah:foo@:\e | |
338 | :abc%xyz:abc^frap:abc$@:\e | |
339 | :tc=more: | |
340 | .Ed | |
341 | .Pp | |
342 | The capability foo has two values bound to it (bar of type `%' and blah of | |
343 | type `^') and any other value bindings are hidden. The capability abc | |
344 | also has two values bound but only a value of type `$' is prevented from | |
345 | being defined in the capability record more. | |
346 | .Pp | |
347 | .Bd -unfilled -offset indent | |
348 | file1: | |
349 | new\||\|new_record\||\|a modification of "old":\e | |
350 | :fript=bar:who-cares@:tc=old:blah:tc=extensions: | |
351 | file2: | |
352 | old\||\|old_record\||\|an old database record:\e | |
353 | :fript=foo:who-cares:glork#200: | |
354 | .Ed | |
355 | .Pp | |
356 | The records are extracted by calling | |
357 | .Nm cgetent | |
358 | with file1 preceding file2. | |
359 | In the capability record new in file1, fript=bar overrides the definition | |
360 | of fript=foo interpolated from the capability record old in file2, | |
361 | who-cares@ prevents the definition of any who-cares definitions in old | |
362 | from being seen, glork#200 is inherited from old, and blah and anything | |
363 | defined by the record extensions is added to those definitions in old. | |
364 | Note that the position of the fript=bar and who-cares@ definitions before | |
365 | tc=old is important here. If they were after, the definitions in old | |
366 | would take precedence. | |
367 | .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS | |
368 | Two types are predefined by | |
369 | .Nm cgetnum | |
370 | and | |
371 | .Nm cgetstr : | |
7e44f1ef CL |
372 | .Bl -column "nameXnumber" |
373 | .Sm off | |
374 | .It Em name No \&# Em number Ta numeric | |
375 | capability | |
376 | .Em name | |
377 | has value | |
378 | .Em number | |
379 | .It Em name No = Em string Ta "string capability" | |
380 | .Em name | |
381 | has value | |
382 | .Em string | |
383 | .It Em name No \&#@ Ta "the numeric capability" | |
384 | .Em name | |
385 | does not exist | |
386 | .It Em name No \&=@ Ta "the string capability" | |
387 | .Em name | |
388 | does not exist | |
389 | .El | |
a1dc6928 KB |
390 | .Pp |
391 | Numeric capability values may be given in one of three numeric bases. | |
392 | If the number starts with either | |
7e44f1ef | 393 | .Ql 0x |
a1dc6928 | 394 | or |
7e44f1ef | 395 | .Ql 0X |
a1dc6928 KB |
396 | it is interpreted as a hexadecimal number (both upper and lower case a-f |
397 | may be used to denote the extended hexadecimal digits). | |
398 | Otherwise, if the number starts with a | |
7e44f1ef | 399 | .Ql 0 |
a1dc6928 KB |
400 | it is interpreted as an octal number. |
401 | Otherwise the number is interpreted as a decimal number. | |
402 | .Pp | |
7e44f1ef CL |
403 | String capability values may contain any character. Non-printable |
404 | .Dv ASCII | |
a1dc6928 KB |
405 | codes, new lines, and colons may be conveniently represented by the use |
406 | of escape sequences: | |
7e44f1ef | 407 | .Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)" |
a1dc6928 KB |
408 | ^X ('\fIX\fP' & 037) control-\fIX\fP |
409 | \e\|b, \e\|B (ASCII 010) backspace | |
410 | \e\|t, \e\|T (ASCII 011) tab | |
411 | \e\|n, \e\|N (ASCII 012) line feed (newline) | |
412 | \e\|f, \e\|F (ASCII 014) form feed | |
413 | \e\|r, \e\|R (ASCII 015) carriage return | |
414 | \e\|e, \e\|E (ASCII 027) escape | |
415 | \e\|c, \e\|C (:) colon | |
416 | \e\|\e (\e\|) back slash | |
417 | \e\|^ (^) caret | |
418 | \e\|\fInnn\fP (ASCII octal \fInnn\fP) | |
7e44f1ef | 419 | .El |
a1dc6928 KB |
420 | .Pp |
421 | A `\|\e' may be followed by up to three octal digits directly specifies | |
7e44f1ef CL |
422 | the numeric code for a character. The use of |
423 | .Tn ASCII | |
424 | .Dv NUL Ns s , | |
425 | while easily | |
a1dc6928 | 426 | encoded, causes all sorts of problems and must be used with care since |
7e44f1ef CL |
427 | .Dv NUL Ns s |
428 | are typically used to denote the end of strings; many applications | |
429 | use `\e\|200' to represent a | |
430 | .Dv NUL . | |
a1dc6928 KB |
431 | .Sh DIAGNOSTICS |
432 | .Nm Cgetent , | |
433 | .Nm cgetset , | |
434 | .Nm cgetmatch , | |
435 | .Nm cgetnum , | |
436 | .Nm cgetstr , | |
437 | .Nm cgetustr , | |
438 | .Nm cgetfirst , | |
439 | and | |
440 | .Nm cgetnext | |
653ba8b6 | 441 | return a value greater than or equal to 0 on success and a value less |
a1dc6928 KB |
442 | than 0 on failure. |
443 | .Nm Cgetcap | |
7e44f1ef CL |
444 | returns a character pointer on success and a |
445 | .Dv NULL | |
446 | on failure. | |
a1dc6928 KB |
447 | .Pp |
448 | .Nm Cgetent , | |
449 | and | |
450 | .Nm cgetseq | |
451 | may fail and set | |
452 | .Va errno | |
453 | for any of the errors specified for the library functions: | |
454 | .Xr fopen 2 , | |
455 | .Xr fclose 2 , | |
456 | .Xr open 2 , | |
457 | and | |
458 | .Xr close 2 . | |
459 | .Pp | |
460 | .Nm Cgetent , | |
461 | .Nm cgetset , | |
462 | .Nm cgetstr , | |
463 | and | |
464 | .Nm cgetustr | |
465 | may fail and set | |
466 | .Va errno | |
467 | as follows: | |
468 | .Bl -tag -width Er | |
469 | .It Bq Er ENOMEM | |
470 | No memory to allocate. | |
471 | .El | |
472 | .Sh SEE ALSO | |
c49bb0ed | 473 | .Xr cap_mkdb 1 , |
a1dc6928 KB |
474 | .Xr malloc 3 |
475 | .Sh BUGS | |
476 | Colons (`:') can't be used in names, types, or values. | |
477 | .Pp | |
478 | There are no checks for | |
7e44f1ef | 479 | .Ic tc= name |
a1dc6928 KB |
480 | loops in |
481 | .Nm cgetent . | |
60cb1750 EA |
482 | .Pp |
483 | The buffer added to the database by a call to | |
484 | .Nm cgetset | |
485 | is not unique to the database but is rather prepended to any database used. |