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