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