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