Annotation of src/lib/libc/gen/getcap.3, Revision 1.14
1.14 ! ross 1: .\" $NetBSD: getcap.3,v 1.13 2002/02/07 07:00:12 ross Exp $
1.4 cgd 2: .\"
3: .\" Copyright (c) 1992, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 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. All advertising materials mentioning features or use of this software
18: .\" must display the following acknowledgement:
19: .\" This product includes software developed by the University of
20: .\" California, Berkeley and its contributors.
21: .\" 4. Neither the name of the University nor the names of its contributors
22: .\" may be used to endorse or promote products derived from this software
23: .\" without specific prior written permission.
24: .\"
25: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
26: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35: .\" SUCH DAMAGE.
36: .\"
1.6 perry 37: .\" @(#)getcap.3 8.4 (Berkeley) 5/13/94
1.1 cgd 38: .\"
1.7 perry 39: .Dd May 13, 1994
1.10 fair 40: .Dt GETCAP 3
1.1 cgd 41: .Os
42: .Sh NAME
43: .Nm cgetent ,
44: .Nm cgetset ,
45: .Nm cgetmatch ,
46: .Nm cgetcap ,
47: .Nm cgetnum ,
48: .Nm cgetstr ,
49: .Nm cgetustr ,
50: .Nm cgetfirst ,
51: .Nm cgetnext ,
52: .Nm cgetclose
53: .Nd capability database access routines
1.8 perry 54: .Sh LIBRARY
55: .Lb libc
1.1 cgd 56: .Sh SYNOPSIS
1.13 ross 57: .Fd #include \*[Lt]stdlib.h\*[Gt]
1.1 cgd 58: .Ft int
1.11 kleink 59: .Fn cgetent "char **buf" "char **db_array" "const char *name"
1.1 cgd 60: .Ft int
1.11 kleink 61: .Fn cgetset "const char *ent"
1.1 cgd 62: .Ft int
1.11 kleink 63: .Fn cgetmatch "const char *buf" "const char *name"
1.1 cgd 64: .Ft char *
1.11 kleink 65: .Fn cgetcap "char *buf" "const char *cap" "int type"
1.1 cgd 66: .Ft int
1.11 kleink 67: .Fn cgetnum "char *buf" "const char *cap" "long *num"
1.1 cgd 68: .Ft int
1.11 kleink 69: .Fn cgetstr "char *buf" "const char *cap" "char **str"
1.1 cgd 70: .Ft int
1.11 kleink 71: .Fn cgetustr "char *buf" "const char *cap" "char **str"
1.1 cgd 72: .Ft int
73: .Fn cgetfirst "char **buf" "char **db_array"
74: .Ft int
75: .Fn cgetnext "char **buf" "char **db_array"
76: .Ft int
77: .Fn cgetclose "void"
78: .Sh DESCRIPTION
1.10 fair 79: .Fn cgetent
1.6 perry 80: extracts the capability
1.1 cgd 81: .Fa name
82: from the database specified by the
83: .Dv NULL
84: terminated file array
85: .Fa db_array
86: and returns a pointer to a
1.9 fair 87: .Xr malloc 3 Ns \&'d
1.1 cgd 88: copy of it in
1.10 fair 89: .Fa buf .
90: .Fn cgetent
91: will first look for files ending in
92: .Pa .db
1.1 cgd 93: (see
1.9 fair 94: .Xr cap_mkdb 1 )
1.10 fair 95: before accessing the
96: .Tn ASCII
97: file.
98: .Pp
99: .Fa buf
1.1 cgd 100: must be retained through all subsequent calls to
101: .Fn cgetmatch ,
102: .Fn cgetcap ,
103: .Fn cgetnum ,
104: .Fn cgetstr ,
105: and
106: .Fn cgetustr ,
107: but may then be
1.12 wiz 108: .Xr free 3 Ns \&'d .
1.10 fair 109: .Pp
110: On success 0 is returned, 1 if the returned record contains an unresolved
111: .Qq tc
112: expansion, \-1 if the requested record couldn't be found, \-2 if
113: a system error was encountered (couldn't open/read a file, etc.)
114: also setting
115: .Va errno ,
1.1 cgd 116: and \-3 if a potential reference loop is detected (see
1.10 fair 117: .Qq tc=name
1.1 cgd 118: comments below).
119: .Pp
1.10 fair 120: .Fn cgetset
1.1 cgd 121: enables the addition of a character buffer containing a single capability
1.10 fair 122: record entry to the capability database.
1.1 cgd 123: Conceptually, the entry is added as the first ``file'' in the database, and
1.10 fair 124: is therefore searched first on the call to
125: .Fn cgetent .
126: The entry is passed in
1.1 cgd 127: .Fa ent .
1.10 fair 128: If
129: .Fa ent
1.1 cgd 130: is
131: .Dv NULL ,
1.10 fair 132: the current entry is removed from the database.
133: .Pp
134: .Fn cgetset
135: must precede the database traversal.
136: It must be called before the
137: .Fn cgetent
138: call.
139: If a sequential access is being performed (see below), it must be called
140: before the first sequential access call
141: .Po
142: .Fn cgetfirst
1.1 cgd 143: or
1.10 fair 144: .Fn cgetnext
145: .Pc ,
146: or be directly preceded by a
147: .Fn cgetclose
1.1 cgd 148: call.
149: On success 0 is returned and \-1 on failure.
150: .Pp
1.10 fair 151: .Fn cgetmatch
1.1 cgd 152: will return 0 if
153: .Fa name
154: is one of the names of the capability record
155: .Fa buf ,
1.10 fair 156: \-1 if not.
1.1 cgd 157: .Pp
1.10 fair 158: .Fn cgetcap
1.1 cgd 159: searches the capability record
160: .Fa buf
161: for the capability
162: .Fa cap
163: with type
164: .Fa type .
165: A
166: .Fa type
1.10 fair 167: is specified using any single character.
168: If a colon (`:') is used, an untyped capability will be searched
169: for (see below for explanation of types).
170: A pointer to the value of
1.1 cgd 171: .Fa cap
172: in
173: .Fa buf
174: is returned on success,
175: .Dv NULL
1.10 fair 176: if the requested capability couldn't be found.
177: The end of the capability value is signaled by a `:' or
1.1 cgd 178: .Tn ASCII
179: .Dv NUL
180: (see below for capability database syntax).
181: .Pp
1.10 fair 182: .Fn cgetnum
1.1 cgd 183: retrieves the value of the numeric capability
184: .Fa cap
185: from the capability record pointed to by
186: .Fa buf .
187: The numeric value is returned in the
188: .Ft long
189: pointed to by
190: .Fa num .
1.10 fair 191: 0 is returned on success,
192: \-1 if the requested numeric capability couldn't be found.
1.1 cgd 193: .Pp
1.10 fair 194: .Fn cgetstr
1.1 cgd 195: retrieves the value of the string capability
196: .Fa cap
197: from the capability record pointed to by
198: .Fa buf .
199: A pointer to a decoded,
200: .Dv NUL
201: terminated,
1.9 fair 202: .Xr malloc 3 Ns \&'d
1.1 cgd 203: copy of the string is returned in the
204: .Ft char *
205: pointed to by
206: .Fa str .
207: The number of characters in the decoded string not including the trailing
208: .Dv NUL
209: is returned on success, \-1 if the requested string capability couldn't
210: be found, \-2 if a system error was encountered (storage allocation
211: failure).
212: .Pp
1.10 fair 213: .Fn cgetustr
214: is identical to
215: .Fn cgetstr
1.1 cgd 216: except that it does not expand special characters, but rather returns each
217: character of the capability string literally.
218: .Pp
1.10 fair 219: .Fn cgetfirst ,
220: .Fn cgetnext ,
221: comprise a function group that provides for sequential access of the
1.1 cgd 222: .Dv NULL
223: pointer terminated array of file names,
224: .Fa db_array .
1.10 fair 225: .Fn cgetfirst
1.1 cgd 226: returns the first record in the database and resets the access
227: to the first record.
1.10 fair 228: .Fn cgetnext
1.1 cgd 229: returns the next record in the database with respect to the
230: record returned by the previous
1.10 fair 231: .Fn cgetfirst
1.1 cgd 232: or
1.10 fair 233: .Fn cgetnext
234: call.
235: If there is no such previous call,
236: the first record in the database is returned.
1.1 cgd 237: Each record is returned in a
1.10 fair 238: .Xr malloc 3 Ns \&'d
239: copy pointed to by
240: .Fa buf .
241: .Qq tc
1.1 cgd 242: expansion is done (see
1.10 fair 243: .Qq tc=name
1.1 cgd 244: comments below).
1.10 fair 245: .Pp
1.1 cgd 246: Upon completion of the database 0 is returned, 1 is returned upon successful
1.10 fair 247: return of record with possibly more remaining (we haven't reached the end of
1.1 cgd 248: the database yet), 2 is returned if the record contains an unresolved
1.10 fair 249: .Qq tc
1.3 jtc 250: expansion, \-1 is returned if an system error occurred, and \-2
1.10 fair 251: is returned if a potential reference loop is detected (see
252: .Qq tc=name
1.1 cgd 253: comments below).
254: Upon completion of database (0 return) the database is closed.
255: .Pp
1.10 fair 256: .Fn cgetclose
257: closes the sequential access and frees any memory and file descriptors
258: being used.
259: Note that it does not erase the buffer pushed by a call to
260: .Fn cgetset .
1.1 cgd 261: .Sh CAPABILITY DATABASE SYNTAX
262: Capability databases are normally
263: .Tn ASCII
1.10 fair 264: and may be edited with standard text editors.
265: Blank lines and lines beginning with a `#' are comments and are ignored.
266: Lines ending with a `\|\e' indicate that the next line is a continuation
267: of the current line; the `\|\e' and following newline are ignored.
268: Long lines are usually continued onto several physical
1.1 cgd 269: lines by ending each line except the last with a `\|\e'.
270: .Pp
1.10 fair 271: Capability databases consist of a series of records, one per logical line.
272: Each record contains a variable number of `:'-separated fields (capabilities).
273: Empty fields consisting entirely of white space
1.1 cgd 274: characters (spaces and tabs) are ignored.
275: .Pp
276: The first capability of each record specifies its names, separated by `|'
1.10 fair 277: characters.
278: These names are used to reference records in the database.
1.1 cgd 279: By convention, the last name is usually a comment and is not intended as
1.10 fair 280: a lookup tag.
281: For example, the
1.1 cgd 282: .Em vt100
283: record from the
1.10 fair 284: .Pa termcap
1.1 cgd 285: database begins:
286: .Pp
287: .Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:"
288: .Pp
289: giving four names that can be used to access the record.
290: .Pp
291: The remaining non-empty capabilities describe a set of (name, value)
292: bindings, consisting of a names optionally followed by a typed values:
293: .Bl -column "nameTvalue"
294: .It name Ta "typeless [boolean] capability"
295: .Em name No "is present [true]"
296: .It name Ns Em \&T Ns value Ta capability
297: .Pq Em name , \&T
298: has value
299: .Em value
300: .It name@ Ta "no capability" Em name No exists
301: .It name Ns Em T Ns \&@ Ta capability
302: .Pq Em name , T
303: does not exist
304: .El
305: .Pp
1.10 fair 306: Names consist of one or more characters.
307: Names may contain any character except `:', but it's usually best
308: to restrict them to the printable characters and avoid use of
309: graphics like `#', `=', `%', `@', etc.
310: .Pp
311: Types are single characters used to separate capability names from
312: their associated typed values.
313: Types may be any character except a `:'.
314: Typically, graphics like `#', `=', `%', etc. are used.
315: Values may be any number of characters and may contain any character except `:'.
1.1 cgd 316: .Sh CAPABILITY DATABASE SEMANTICS
1.10 fair 317: Capability records describe a set of (name, value) bindings.
318: Names may have multiple values bound to them.
319: Different values for a name are distinguished by their
1.1 cgd 320: .Fa types .
1.10 fair 321: .Fn cgetcap
1.1 cgd 322: will return a pointer to a value of a name given the capability name and
323: the type of the value.
324: .Pp
325: The types `#' and `=' are conventionally used to denote numeric and
1.10 fair 326: string typed values, but no restriction on those types is enforced.
327: The functions
328: .Fn cgetnum
1.1 cgd 329: and
1.10 fair 330: .Fn cgetstr
331: can be used to implement the traditional syntax and semantics of `#' and `='.
1.1 cgd 332: Typeless capabilities are typically used to denote boolean objects with
333: presence or absence indicating truth and false values respectively.
334: This interpretation is conveniently represented by:
335: .Pp
336: .Dl "(getcap(buf, name, ':') != NULL)"
337: .Pp
338: A special capability,
1.10 fair 339: .Qq tc=name ,
1.1 cgd 340: is used to indicate that the record specified by
341: .Fa name
342: should be substituted for the
1.10 fair 343: .Qq tc
1.1 cgd 344: capability.
1.10 fair 345: .Qq tc
1.1 cgd 346: capabilities may interpolate records which also contain
1.10 fair 347: .Qq tc
1.1 cgd 348: capabilities and more than one
1.10 fair 349: .Qq tc
350: capability may be used in a record.
351: A
352: .Qq tc
353: expansion scope (i.e. where the argument is searched for) contains the
1.1 cgd 354: file in which the
1.10 fair 355: .Qq tc
1.1 cgd 356: is declared and all subsequent files in the file array.
357: .Pp
358: When a database is searched for a capability record, the first matching
1.10 fair 359: record in the search is returned.
360: When a record is scanned for a capability, the first matching
361: capability is returned; the capability
362: .Qq :nameT@:
1.1 cgd 363: will hide any following definition of a value of type
364: .Em T
365: for
366: .Fa name ;
367: and the capability
1.10 fair 368: .Qq :name@:
1.1 cgd 369: will prevent any following values of
370: .Fa name
371: from being seen.
372: .Pp
373: These features combined with
1.10 fair 374: .Qq tc
1.1 cgd 375: capabilities can be used to generate variations of other databases and
376: records by either adding new capabilities, overriding definitions with new
377: definitions, or hiding following definitions via `@' capabilities.
378: .Sh EXAMPLES
379: .Bd -unfilled -offset indent
380: example\||\|an example of binding multiple values to names:\e
381: :foo%bar:foo^blah:foo@:\e
382: :abc%xyz:abc^frap:abc$@:\e
383: :tc=more:
384: .Ed
385: .Pp
1.10 fair 386: The capability
387: .Em foo
388: has two values bound to it
389: .Po
390: .Em bar
391: of type `%' and
392: .Em blah
393: of type `^'
394: .Pc
395: and any other value bindings are hidden.
396: The capability
397: .Em abc
1.1 cgd 398: also has two values bound but only a value of type `$' is prevented from
399: being defined in the capability record more.
400: .Pp
401: .Bd -unfilled -offset indent
402: file1:
403: new\||\|new_record\||\|a modification of "old":\e
404: :fript=bar:who-cares@:tc=old:blah:tc=extensions:
405: file2:
406: old\||\|old_record\||\|an old database record:\e
407: :fript=foo:who-cares:glork#200:
408: .Ed
409: .Pp
410: The records are extracted by calling
1.10 fair 411: .Fn cgetent
412: with
413: .Fa file1
414: preceding
415: .Fa file2 .
416: In the capability record
417: .Em new
418: in
419: .Fa file1 ,
420: .Qq fript=bar
421: overrides the definition of
422: .Qq fript=foo
423: interpolated from the capability record
424: .Em old
425: in
1.12 wiz 426: .Fa file2 ,
1.10 fair 427: .Qq who-cares@
428: prevents the definition of any who-cares definitions in
429: .Em old
430: from being seen,
431: .Qq glork#200
432: is inherited from
433: .Em old ,
434: and
435: .Em blah
436: and anything defined by the record extensions is added to those
437: definitions in
438: .Em old .
439: Note that the position of the
440: .Qq fript=bar
441: and
442: .Qq who-cares@
443: definitions before
444: .Qq tc=old
445: is important here.
446: If they were after, the definitions in
447: .Em old
1.1 cgd 448: would take precedence.
449: .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS
450: Two types are predefined by
1.10 fair 451: .Fn cgetnum
1.1 cgd 452: and
1.10 fair 453: .Fn cgetstr :
1.1 cgd 454: .Bl -column "nameXnumber"
455: .Sm off
456: .It Em name No \&# Em number Ta numeric
457: capability
458: .Em name
459: has value
460: .Em number
461: .It Em name No = Em string Ta "string capability"
462: .Em name
1.10 fair 463: has value
1.1 cgd 464: .Em string
465: .It Em name No \&#@ Ta "the numeric capability"
466: .Em name
467: does not exist
468: .It Em name No \&=@ Ta "the string capability"
469: .Em name
470: does not exist
471: .El
472: .Pp
473: Numeric capability values may be given in one of three numeric bases.
474: If the number starts with either
475: .Ql 0x
476: or
477: .Ql 0X
478: it is interpreted as a hexadecimal number (both upper and lower case a-f
479: may be used to denote the extended hexadecimal digits).
480: Otherwise, if the number starts with a
481: .Ql 0
482: it is interpreted as an octal number.
483: Otherwise the number is interpreted as a decimal number.
484: .Pp
1.10 fair 485: String capability values may contain any character.
486: Non-printable
1.1 cgd 487: .Dv ASCII
488: codes, new lines, and colons may be conveniently represented by the use
489: of escape sequences:
490: .Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)"
1.14 ! ross 491: ^X ('\fIX\fP' \*[Am] 037) control-\fIX\fP
1.1 cgd 492: \e\|b, \e\|B (ASCII 010) backspace
493: \e\|t, \e\|T (ASCII 011) tab
494: \e\|n, \e\|N (ASCII 012) line feed (newline)
495: \e\|f, \e\|F (ASCII 014) form feed
496: \e\|r, \e\|R (ASCII 015) carriage return
497: \e\|e, \e\|E (ASCII 027) escape
498: \e\|c, \e\|C (:) colon
499: \e\|\e (\e\|) back slash
500: \e\|^ (^) caret
501: \e\|\fInnn\fP (ASCII octal \fInnn\fP)
502: .El
503: .Pp
504: A `\|\e' may be followed by up to three octal digits directly specifies
1.10 fair 505: the numeric code for a character.
506: The use of
1.1 cgd 507: .Tn ASCII
508: .Dv NUL Ns s ,
509: while easily
510: encoded, causes all sorts of problems and must be used with care since
511: .Dv NUL Ns s
512: are typically used to denote the end of strings; many applications
513: use `\e\|200' to represent a
514: .Dv NUL .
515: .Sh DIAGNOSTICS
1.10 fair 516: .Fn cgetent ,
517: .Fn cgetset ,
518: .Fn cgetmatch ,
519: .Fn cgetnum ,
520: .Fn cgetstr ,
521: .Fn cgetustr ,
522: .Fn cgetfirst ,
1.1 cgd 523: and
1.10 fair 524: .Fn cgetnext
1.4 cgd 525: return a value greater than or equal to 0 on success and a value less
1.1 cgd 526: than 0 on failure.
1.10 fair 527: .Fn cgetcap
1.1 cgd 528: returns a character pointer on success and a
529: .Dv NULL
530: on failure.
531: .Pp
1.10 fair 532: .Fn cgetent ,
533: and
534: .Fn cgetseq
535: may fail and set
1.1 cgd 536: .Va errno
537: for any of the errors specified for the library functions:
1.10 fair 538: .Xr fopen 3 ,
539: .Xr fclose 3 ,
1.1 cgd 540: .Xr open 2 ,
1.10 fair 541: and
1.1 cgd 542: .Xr close 2 .
543: .Pp
1.10 fair 544: .Fn cgetent ,
545: .Fn cgetset ,
546: .Fn cgetstr ,
1.1 cgd 547: and
1.10 fair 548: .Fn cgetustr
549: may fail and set
550: .Va errno
1.1 cgd 551: as follows:
552: .Bl -tag -width Er
553: .It Bq Er ENOMEM
554: No memory to allocate.
555: .El
556: .Sh SEE ALSO
557: .Xr cap_mkdb 1 ,
558: .Xr malloc 3
559: .Sh BUGS
560: Colons (`:') can't be used in names, types, or values.
561: .Pp
562: There are no checks for
1.10 fair 563: .Qq tc=name
1.1 cgd 564: loops in
1.10 fair 565: .Fn cgetent .
1.1 cgd 566: .Pp
1.10 fair 567: The buffer added to the database by a call to
568: .Fn cgetset
1.1 cgd 569: is not unique to the database but is rather prepended to any database used.
CVSweb <webmaster@jp.NetBSD.org>