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