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