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