Commit | Line | Data |
---|---|---|
8bb980a3 C |
1 | GETCAP(3) BSD Programmer's Manual GETCAP(3) |
2 | ||
3 | N\bNA\bAM\bME\bE | |
4 | c\bcg\bge\bet\bte\ben\bnt\bt, c\bcg\bge\bet\bts\bse\bet\bt, c\bcg\bge\bet\btm\bma\bat\btc\bch\bh, c\bcg\bge\bet\btc\bca\bap\bp, c\bcg\bge\bet\btn\bnu\bum\bm, c\bcg\bge\bet\bts\bst\btr\br, c\bcg\bge\bet\btu\bus\bst\btr\br, | |
5 | c\bcg\bge\bet\btf\bfi\bir\brs\bst\bt, c\bcg\bge\bet\btn\bne\bex\bxt\bt, c\bcg\bge\bet\btc\bcl\blo\bos\bse\be - capability database access routines | |
6 | ||
7 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS | |
8 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdl\bli\bib\bb.\b.h\bh>\b> | |
9 | ||
10 | _\bi_\bn_\bt | |
11 | c\bcg\bge\bet\bte\ben\bnt\bt(_\bc_\bh_\ba_\br _\b*_\b*_\bb_\bu_\bf, _\bc_\bh_\ba_\br _\b*_\b*_\bd_\bb_\b__\ba_\br_\br_\ba_\by, _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be); | |
12 | ||
13 | _\bi_\bn_\bt | |
14 | c\bcg\bge\bet\bts\bse\bet\bt(_\bc_\bh_\ba_\br _\b*_\be_\bn_\bt); | |
15 | ||
16 | _\bi_\bn_\bt | |
17 | c\bcg\bge\bet\btm\bma\bat\btc\bch\bh(_\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be); | |
18 | ||
19 | _\bc_\bh_\ba_\br _\b* | |
20 | c\bcg\bge\bet\btc\bca\bap\bp(_\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bc_\bh_\ba_\br _\b*_\bc_\ba_\bp, _\bc_\bh_\ba_\br _\bt_\by_\bp_\be); | |
21 | ||
22 | _\bi_\bn_\bt | |
23 | c\bcg\bge\bet\btn\bnu\bum\bm(_\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bc_\bh_\ba_\br _\b*_\bc_\ba_\bp, _\bl_\bo_\bn_\bg _\b*_\bn_\bu_\bm); | |
24 | ||
25 | _\bi_\bn_\bt | |
26 | c\bcg\bge\bet\bts\bst\btr\br(_\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bc_\bh_\ba_\br _\b*_\bc_\ba_\bp, _\bc_\bh_\ba_\br _\b*_\b*_\bs_\bt_\br); | |
27 | ||
28 | _\bi_\bn_\bt | |
29 | c\bcg\bge\bet\btu\bus\bst\btr\br(_\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bc_\bh_\ba_\br _\b*_\bc_\ba_\bp, _\bc_\bh_\ba_\br _\b*_\b*_\bs_\bt_\br); | |
30 | ||
31 | _\bi_\bn_\bt | |
32 | c\bcg\bge\bet\btf\bfi\bir\brs\bst\bt(_\bc_\bh_\ba_\br _\b*_\b*_\bb_\bu_\bf, _\bc_\bh_\ba_\br _\b*_\b*_\bd_\bb_\b__\ba_\br_\br_\ba_\by); | |
33 | ||
34 | _\bi_\bn_\bt | |
35 | c\bcg\bge\bet\btn\bne\bex\bxt\bt(_\bc_\bh_\ba_\br _\b*_\b*_\bb_\bu_\bf, _\bc_\bh_\ba_\br _\b*_\b*_\bd_\bb_\b__\ba_\br_\br_\ba_\by); | |
36 | ||
37 | _\bi_\bn_\bt | |
38 | c\bcg\bge\bet\btc\bcl\blo\bos\bse\be(_\bv_\bo_\bi_\bd); | |
39 | ||
40 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN | |
41 | C\bCg\bge\bet\bte\ben\bnt\bt() extracts the capability rec _\bn_\ba_\bm_\be from the database specified by | |
42 | the NULL terminated file array _\bd_\bb_\b__\ba_\br_\br_\ba_\by and returns a pointer to a | |
43 | malloc'd copy of it in _\bb_\bu_\bf. C\bCg\bge\bet\bte\ben\bnt\bt will first look for files ending in | |
44 | .\b.d\bdb\bb (see cap_mkdb(1)) before accessing the ASCII file. _\bB_\bu_\bf must be re- | |
45 | tained through all subsequent calls to c\bcg\bge\bet\btm\bma\bat\btc\bch\bh(), c\bcg\bge\bet\btc\bca\bap\bp(), c\bcg\bge\bet\btn\bnu\bum\bm(), | |
46 | c\bcg\bge\bet\bts\bst\btr\br(), and c\bcg\bge\bet\btu\bus\bst\btr\br(), but may then be free'd. On success 0 is re- | |
47 | turned, 1 if the returned record contains an unresolved t\btc\bc expansion, -1 | |
48 | if the requested record couldn't be found, -2 if a system error was en- | |
49 | countered (couldn't open/read a file, etc.) also setting _\be_\br_\br_\bn_\bo, and -3 if | |
50 | a potential reference loop is detected (see t\btc\bc=\b= comments below). | |
51 | ||
52 | C\bCg\bge\bet\bts\bse\bet\bt enables the addition of a character buffer containing a single | |
53 | capability record entry to the capability database. Conceptually, the | |
54 | entry is added as the first ``file'' in the database, and is therefore | |
55 | searched first on the call to c\bcg\bge\bet\bte\ben\bnt\bt. The entry is passed in _\be_\bn_\bt. If _\be_\bn_\bt | |
56 | is NULL, the current entry is removed from the database. C\bCg\bge\bet\bts\bse\bet\bt must | |
57 | precede the database traversal. It must be called before the c\bcg\bge\bet\bte\ben\bnt\bt | |
58 | call. If a sequential access is being performed (see below), it must be | |
59 | called before the first sequential access call ( c\bcg\bge\bet\btf\bfi\bir\brs\bst\bt or c\bcg\bge\bet\btn\bne\bex\bxt\bt ), | |
60 | or be directly preceded by a c\bcg\bge\bet\btc\bcl\blo\bos\bse\be call. On success 0 is returned | |
61 | and -1 on failure. | |
62 | ||
63 | C\bCg\bge\bet\btm\bma\bat\btc\bch\bh will return 0 if _\bn_\ba_\bm_\be is one of the names of the capability | |
64 | record _\bb_\bu_\bf, -1 if not. | |
65 | ||
66 | ||
67 | C\bCg\bge\bet\btc\bca\bap\bp searches the capability record _\bb_\bu_\bf for the capability _\bc_\ba_\bp with | |
68 | type _\bt_\by_\bp_\be. A _\bt_\by_\bp_\be is specified using any single character. If a colon | |
69 | (`:') is used, an untyped capability will be searched for (see below for | |
70 | explanation of types). A pointer to the value of _\bc_\ba_\bp in _\bb_\bu_\bf is returned | |
71 | on success, NULL if the requested capability couldn't be found. The end | |
72 | of the capability value is signaled by a `:' or ASCII NUL (see below for | |
73 | capability database syntax). | |
74 | ||
75 | C\bCg\bge\bet\btn\bnu\bum\bm retrieves the value of the numeric capability _\bc_\ba_\bp from the capa- | |
76 | bility record pointed to by _\bb_\bu_\bf. The numeric value is returned in the | |
77 | _\bl_\bo_\bn_\bg pointed to by _\bn_\bu_\bm. 0 is returned on success, -1 if the requested nu- | |
78 | meric capability couldn't be found. | |
79 | ||
80 | C\bCg\bge\bet\bts\bst\btr\br retrieves the value of the string capability _\bc_\ba_\bp from the capa- | |
81 | bility record pointed to by _\bb_\bu_\bf. A pointer to a decoded, NUL terminated, | |
82 | malloc'd copy of the string is returned in the _\bc_\bh_\ba_\br _\b* pointed to by _\bs_\bt_\br. | |
83 | The number of characters in the decoded string not including the trailing | |
84 | NUL is returned on success, -1 if the requested string capability | |
85 | couldn't be found, -2 if a system error was encountered (storage alloca- | |
86 | tion failure). | |
87 | ||
88 | C\bCg\bge\bet\btu\bus\bst\btr\br is identical to c\bcg\bge\bet\bts\bst\btr\br except that it does not expand special | |
89 | characters, but rather returns each character of the capability string | |
90 | literally. | |
91 | ||
92 | C\bCg\bge\bet\btf\bfi\bir\brs\bst\bt, c\bcg\bge\bet\btn\bne\bex\bxt\bt, comprise a function group that provides for sequen- | |
93 | tial access of the NULL pointer terminated array of file names, _\bd_\bb_\b__\ba_\br_\br_\ba_\by. | |
94 | C\bCg\bge\bet\btf\bfi\bir\brs\bst\bt returns the first record in the database and resets the access | |
95 | to the first record. C\bCg\bge\bet\btn\bne\bex\bxt\bt returns the next record in the database | |
96 | with respect to the record returned by the previous c\bcg\bge\bet\btf\bfi\bir\brs\bst\bt or c\bcg\bge\bet\btn\bne\bex\bxt\bt | |
97 | call. If there is no such previous call, the first record in the | |
98 | database is returned. Each record is returned in a malloc'd copy point- | |
99 | ed to by _\bb_\bu_\bf. T\bTc\bc expansion is done (see t\btc\bc=\b= comments below). Upon com- | |
100 | pletion of the database 0 is returned, 1 is returned upon successful re- | |
101 | turn of record with possibly more remaining (we haven't reached the end | |
102 | of the database yet), 2 is returned if the record contains an unresolved | |
103 | t\btc\bc expansion, -1 is returned if an system error occured, and -2 is re- | |
104 | turned if a potential reference loop is detected (see t\btc\bc=\b= comments be- | |
105 | low). Upon completion of database (0 return) the database is closed. | |
106 | ||
107 | C\bCg\bge\bet\btc\bcl\blo\bos\bse\be closes the sequential access and frees any memory and file de- | |
108 | scriptors being used. Note that it does not erase the buffer pushed by a | |
109 | call to c\bcg\bge\bet\bts\bse\bet\bt. | |
110 | ||
111 | C\bCA\bAP\bPA\bAB\bBI\bIL\bLI\bIT\bTY\bY D\bDA\bAT\bTA\bAB\bBA\bAS\bSE\bE S\bSY\bYN\bNT\bTA\bAX\bX | |
112 | Capability databases are normally ASCII and may be edited with standard | |
113 | text editors. Blank lines and lines beginning with a `#' are comments | |
114 | and are ignored. Lines ending with a `\' indicate that the next line is | |
115 | a continuation of the current line; the `\' and following newline are ig- | |
116 | nored. Long lines are usually continued onto several physical lines by | |
117 | ending each line except the last with a `\'. | |
118 | ||
119 | Capability databases consist of a series of records, one per logical | |
120 | line. Each record contains a variable number of `:'-separated fields | |
121 | (capabilities). Empty fields consisting entirely of white space charac- | |
122 | ters (spaces and tabs) are ignored. | |
123 | ||
124 | The first capability of each record specifies its names, separated by `|' | |
125 | characters. These names are used to reference records in the database. | |
126 | By convention, the last name is usually a comment and is not intended as | |
127 | a lookup tag. For example, the _\bv_\bt_\b1_\b0_\b0 record from the t\bte\ber\brm\bmc\bca\bap\bp database | |
128 | begins: | |
129 | ||
130 | d0|vt100|vt100-am|vt100am|dec vt100: | |
131 | ||
132 | ||
133 | giving four names that can be used to access the record. | |
134 | ||
135 | The remaining non-empty capabilities describe a set of (name, value) | |
136 | bindings, consisting of a names optionally followed by a typed values: | |
137 | ||
138 | name typeless [boolean] capability _\bn_\ba_\bm_\be is present [true] | |
139 | name_\bTvalue capability (_\bn_\ba_\bm_\be, _\bT) has value _\bv_\ba_\bl_\bu_\be | |
140 | name@ no capability _\bn_\ba_\bm_\be exists | |
141 | name_\bT@ capability (_\bn_\ba_\bm_\be, _\bT) does not exist | |
142 | ||
143 | Names consist of one or more characters. Names may contain any character | |
144 | except `:', but it's usually best to restrict them to the printable char- | |
145 | acters and avoid use of graphics like `#', `=', `%', `@', etc. Types are | |
146 | single characters used to separate capability names from their associated | |
147 | typed values. Types may be any character except a `:'. Typically, | |
148 | graphics like `#', `=', `%', etc. are used. Values may be any number of | |
149 | characters and may contain any character except `:'. | |
150 | ||
151 | C\bCA\bAP\bPA\bAB\bBI\bIL\bLI\bIT\bTY\bY D\bDA\bAT\bTA\bAB\bBA\bAS\bSE\bE S\bSE\bEM\bMA\bAN\bNT\bTI\bIC\bCS\bS | |
152 | Capability records describe a set of (name, value) bindings. Names may | |
153 | have multiple values bound to them. Different values for a name are dis- | |
154 | tinguished by their _\bt_\by_\bp_\be_\bs. C\bCg\bge\bet\btc\bca\bap\bp will return a pointer to a value of a | |
155 | name given the capability name and the type of the value. | |
156 | ||
157 | The types `#' and `=' are conventionally used to denote numeric and | |
158 | string typed values, but no restriction on those types is enforced. The | |
159 | functions c\bcg\bge\bet\btn\bnu\bum\bm and c\bcg\bge\bet\bts\bst\btr\br can be used to implement the traditional | |
160 | syntax and semantics of `#' and `='. Typeless capabilities are typically | |
161 | used to denote boolean objects with presence or absence indicating truth | |
162 | and false values respectively. This interpretation is conveniently rep- | |
163 | resented by: | |
164 | ||
165 | (getcap(buf, name, ':') != NULL) | |
166 | ||
167 | A special capability, t\btc\bc=\b= n\bna\bam\bme\be, is used to indicate that the record spec- | |
168 | ified by _\bn_\ba_\bm_\be should be substituted for the t\btc\bc capability. T\bTc\bc capabili- | |
169 | ties may interpolate records which also contain t\btc\bc capabilities and more | |
170 | than one t\btc\bc capability may be used in a record. A t\btc\bc expansion scope | |
171 | (i.e., where the argument is searched for) contains the file in which the | |
172 | t\btc\bc is declared and all subsequent files in the file array. | |
173 | ||
174 | When a database is searched for a capability record, the first matching | |
175 | record in the search is returned. When an record is scanned for a capa- | |
176 | bility, the first matching capability is returned; the capability | |
177 | :\b:n\bna\bam\bme\beT\bT@\b@:\b: will hide any following definition of a value of type _\bT for | |
178 | _\bn_\ba_\bm_\be; and the capability :\b:n\bna\bam\bme\be@\b@:\b: will prevent any following values of | |
179 | _\bn_\ba_\bm_\be from being seen. | |
180 | ||
181 | These features combined with t\btc\bc capabilities can be used to generate | |
182 | variations of other databases and records by either adding new capabili- | |
183 | ties, overriding definitions with new definitions, or hiding following | |
184 | definitions via `@' capabilities. | |
185 | ||
186 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS | |
187 | example|an example of binding multiple values to names:\ | |
188 | :foo%bar:foo^blah:foo@:\ | |
189 | :abc%xyz:abc^frap:abc$@:\ | |
190 | :tc=more: | |
191 | ||
192 | The capability foo has two values bound to it (bar of type `%' and blah | |
193 | of type `^') and any other value bindings are hidden. The capability abc | |
194 | also has two values bound but only a value of type `$' is prevented from | |
195 | being defined in the capability record more. | |
196 | ||
197 | ||
198 | file1: | |
199 | new|new_record|a modification of "old":\ | |
200 | :fript=bar:who-cares@:tc=old:blah:tc=extensions: | |
201 | file2: | |
202 | old|old_record|an old database record:\ | |
203 | :fript=foo:who-cares:glork#200: | |
204 | ||
205 | The records are extracted by calling c\bcg\bge\bet\bte\ben\bnt\bt with file1 preceding file2. | |
206 | In the capability record new in file1, fript=bar overrides the definition | |
207 | of fript=foo interpolated from the capability record old in file2, who- | |
208 | cares@ prevents the definition of any who-cares definitions in old from | |
209 | being seen, glork#200 is inherited from old, and blah and anything de- | |
210 | fined by the record extensions is added to those definitions in old. | |
211 | Note that the position of the fript=bar and who-cares@ definitions before | |
212 | tc=old is important here. If they were after, the definitions in old | |
213 | would take precedence. | |
214 | ||
215 | C\bCG\bGE\bET\bTN\bNU\bUM\bM A\bAN\bND\bD C\bCG\bGE\bET\bTS\bST\bTR\bR S\bSY\bYN\bNT\bTA\bAX\bX A\bAN\bND\bD S\bSE\bEM\bMA\bAN\bNT\bTI\bIC\bCS\bS | |
216 | Two types are predefined by c\bcg\bge\bet\btn\bnu\bum\bm and c\bcg\bge\bet\bts\bst\btr\br: | |
217 | ||
218 | _\bn_\ba_\bm_\be#_\bn_\bu_\bm_\bb_\be_\br numeric capability _\bn_\ba_\bm_\be has value _\bn_\bu_\bm_\bb_\be_\br | |
219 | _\bn_\ba_\bm_\be=_\bs_\bt_\br_\bi_\bn_\bg string capability _\bn_\ba_\bm_\be has value _\bs_\bt_\br_\bi_\bn_\bg | |
220 | _\bn_\ba_\bm_\be#@ the numeric capability _\bn_\ba_\bm_\be does not exist | |
221 | _\bn_\ba_\bm_\be=@ the string capability _\bn_\ba_\bm_\be does not exist | |
222 | ||
223 | Numeric capability values may be given in one of three numeric bases. If | |
224 | the number starts with either `0x' or `0X' it is interpreted as a hex- | |
225 | adecimal number (both upper and lower case a-f may be used to denote the | |
226 | extended hexadecimal digits). Otherwise, if the number starts with a `0' | |
227 | it is interpreted as an octal number. Otherwise the number is interpret- | |
228 | ed as a decimal number. | |
229 | ||
230 | String capability values may contain any character. Non-printable ASCII | |
231 | codes, new lines, and colons may be conveniently represented by the use | |
232 | of escape sequences: | |
233 | ||
234 | ^X ('_\bX' & 037) control-_\bX | |
235 | \b, \B (ASCII 010) backspace | |
236 | \t, \T (ASCII 011) tab | |
237 | \n, \N (ASCII 012) line feed (newline) | |
238 | \f, \F (ASCII 014) form feed | |
239 | \r, \R (ASCII 015) carriage return | |
240 | \e, \E (ASCII 027) escape | |
241 | \c, \C (:) colon | |
242 | \\ (\) back slash | |
243 | \^ (^) caret | |
244 | \_\bn_\bn_\bn (ASCII octal _\bn_\bn_\bn) | |
245 | ||
246 | A `\' may be followed by up to three octal digits directly specifies the | |
247 | numeric code for a character. The use of ASCII NULs, while easily encod- | |
248 | ed, causes all sorts of problems and must be used with care since NULs | |
249 | are typically used to denote the end of strings; many applications use | |
250 | `\200' to represent a NUL. | |
251 | ||
252 | D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS | |
253 | C\bCg\bge\bet\bte\ben\bnt\bt, c\bcg\bge\bet\bts\bse\bet\bt, c\bcg\bge\bet\btm\bma\bat\btc\bch\bh, c\bcg\bge\bet\btn\bnu\bum\bm, c\bcg\bge\bet\bts\bst\btr\br, c\bcg\bge\bet\btu\bus\bst\btr\br, c\bcg\bge\bet\btf\bfi\bir\brs\bst\bt, and | |
254 | c\bcg\bge\bet\btn\bne\bex\bxt\bt return a a value greater than or equal to 0 on success and a | |
255 | value less than 0 on failure. C\bCg\bge\bet\btc\bca\bap\bp returns a character pointer on | |
256 | success and a NULL on failure. | |
257 | ||
258 | C\bCg\bge\bet\bte\ben\bnt\bt, and c\bcg\bge\bet\bts\bse\beq\bq may fail and set _\be_\br_\br_\bn_\bo for any of the errors speci- | |
259 | fied for the library functions: fopen(2), fclose(2), open(2), and | |
260 | close(2). | |
261 | ||
262 | C\bCg\bge\bet\bte\ben\bnt\bt, c\bcg\bge\bet\bts\bse\bet\bt, c\bcg\bge\bet\bts\bst\btr\br, and c\bcg\bge\bet\btu\bus\bst\btr\br may fail and set _\be_\br_\br_\bn_\bo as fol- | |
263 | ||
264 | lows: | |
265 | ||
266 | [ENOMEM] No memory to allocate. | |
267 | ||
268 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
269 | cap_mkdb(1), malloc(3) | |
270 | ||
271 | B\bBU\bUG\bGS\bS | |
272 | Colons (`:') can't be used in names, types, or values. | |
273 | ||
274 | There are no checks for t\btc\bc=\b=n\bna\bam\bme\be loops in c\bcg\bge\bet\bte\ben\bnt\bt. | |
275 | ||
276 | The buffer added to the database by a call to c\bcg\bge\bet\bts\bse\bet\bt is not unique to | |
277 | the database but is rather prepended to any database used. | |
278 | ||
279 | 4.4BSD June 4, 1993 5 |