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