Print this page
9842 man page typos and spelling
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man4/contract.4.man.txt
+++ new/usr/src/man/man4/contract.4.man.txt
1 1 CONTRACT(4) File Formats and Configurations CONTRACT(4)
2 2
3 3
4 4
5 5 NAME
6 6 contract - the contract file system
7 7
8 8 SYNOPSIS
9 9 /system/contract
10 10
11 11
12 12 DESCRIPTION
13 13 The /system/contract file system acts as the primary interface to the
14 14 contract subsystem. There is a subdirectory of /system/contract for
15 15 each available contract type.
16 16
17 17
18 18 /system/contract can be mounted on any mount point, in addition to the
19 19 standard /system/contract mount point, and can be mounted several
20 20 places at once. Such additional mounts are allowed in order to
21 21 facilitate the confinement of processes to subtrees of the file system
22 22 using chroot(1M) and yet allow such processes to continue to use
23 23 contract commands and interfaces.
24 24
25 25
26 26 A combination of standard system calls (for example, open(2), close(2),
27 27 and poll(2)) and calls to libcontract(3LIB) access /system/contract
28 28 files.
29 29
30 30
31 31 Consumers of the contract file system must be large file aware. See
32 32 largefile(5) and lfcompile64(5).
33 33
34 34 DIRECTORY STRUCTURE
35 35 At the top level, the /system/contract directory contains
36 36 subdirectories named with each available contract type, and one special
37 37 directory, all. Each of these directories is world-readable and world-
38 38 searchable.
39 39
40 40 STRUCTURE OF /system/contract/type
41 41 Each /system/contract/type directory contains a fixed number of files.
42 42 It also contains a variable number of subdirectories corresponding to
43 43 existing contracts of type type and named with the decimal
44 44 representation of the contracts' IDs.
45 45
46 46
47 47 The following files are in a /system/contract/type directory:
48 48
49 49 template
50 50 Opening this file returns a file descriptor for a new type
51 51 contract template.
52 52
53 53 You can use the following libcontract(3LIB) calls on a
54 54 template file descriptor:
55 55
56 56 >
57 57
58 58 ct_tmpl_activate(3contract)
59 59 ct_tmpl_clear(3contract)
60 60 ct_tmpl_create(3contract)
61 61
62 62
63 63 See TERMS for additional template functions.
64 64
65 65
66 66 latest
67 67 Opening this file returns a file descriptor for the status
68 68 file of the last type contract written by the opening LWP.
69 69 See STRUCTURE OF /system/contract/type/id. If the opening
70 70 LWP has not created a type contract, opening latest fails
71 71 with ESRCH.
72 72
73 73
74 74 bundle
75 75 Opening this file returns a file descriptor for an event
76 76 endpoint which receives events from all type contracts on
77 77 the system. No privileges are required to open a type
78 78 bundle event endpoint. Events sent by contracts owned and
79 79 written by users other than the reader's effective user id
80 80 are invisible, that is, they are silently skipped, unless
81 81 the reader has {PRIV_CONTRACT_OBSERVER} in its effective
82 82 set. See EVENTS.
83 83
84 84
85 85 pbundle
86 86 Opening this file returns a file descriptor for an event
87 87 endpoint which receives events from all type contracts held
88 88 by the opening process. See EVENTS.
89 89
90 90
91 91 STRUCTURE OF /system/contract/all
92 92 The /system/contract/all directory contains a numerically named file
93 93 for each contract in the system. Each file is a symbolic link to the
94 94 type-specific directory for that contract, that is
95 95 /system/contract/all/id points to /system/contract/type/id.
96 96
97 97 STRUCTURE OF /system/contract/type/id
98 98 Each /system/contract/type/id directory contains the following files:
99 99
100 100 ctl
101 101 Opening this file returns a file descriptor for contract id's
102 102 control file. The open fails if the opening process does not
103 103 hold contract id and the contract has not been inherited by
104 104 the process contract of which the opening process is a
105 105 member. See process(4).
106 106
107 107 The following libcontract(3LIB) calls can be made on a ctl
108 108 file descriptor if the contract is owned by the caller:
109 109
110 110 ct_ctl_abandon(3contract)
111 111 ct_ctl_newct(3contract)
112 112 ct_ctl_ack(3contract)
113 113 ct_ctl_qack(3contract)
114 114
115 115
116 116 The following libcontract(3LIB) call can be made on a ctl
117 117 file descriptor if the contract doesn't have an owner:
118 118
119 119 ct_ctl_adopt(3contract)
120 120
121 121
122 122
123 123
124 124 status
125 125 Opening this file returns a file descriptor for contract id's
126 126 status file. The following libcontract(3LIB) calls can be
127 127 made on a status file descriptor:
128 128
129 129 ct_status_read(3contract)
130 130
131 131 See STATUS.
132 132
133 133
134 134 events
135 135 Opening this file returns a file descriptor for an event
136 136 endpoint which receives events from contract id. See EVENTS.
137 137
138 138 Only a process which has the same effective user ID as the
139 139 process owning the contract, the same effective user ID as
140 140 the contract's author, or has {PRIV_CONTRACT_OBSERVER} in its
141 141 effective set can open the event endpoint for a contract.
142 142
143 143
144 144 TERMS
145 145 The following terms are defined for all contracts:
146 146
147 147 cookie
148 148 Specifies a 64-bit quantity that the contract
149 149 author can use to identify the contract. Use
150 150 ct_tmpl_set_cookie(3CONTRACT) to set this
151 151 term.
152 152
153 153
154 154 informative event set
155 155 Selects which events are delivered as
156 156 informative events. Use
157 157 ct_tmpl_set_informative(3CONTRACT) to set this
158 158 term.
159 159
160 160
161 161 critical event set
162 162 Selects which events are delivered as critical
163 163 events. Use ct_tmpl_set_critical(3CONTRACT) to
164 164 set this term.
165 165
166 166
167 167 STATUS
168 168 A status object returned by ct_status_read(3CONTRACT) contains the
169 169 following pieces of information:
170 170
171 171 contract ID
172 172
173 173 The numeric ID of the contract. Use ct_status_get_id(3CONTRACT) to
174 174 obtain this information.
175 175
176 176
177 177 contract type
178 178
179 179 The type of the contract, specified as a string. Obtained using
180 180 ct_status_get_type(3CONTRACT). The contract type is the same as its
181 181 subdirectory name under /system/contract.
182 182
183 183
184 184 creator's zone ID
185 185
186 186 The zone ID of the process which created the contract. Obtained
187 187 using ct_status_get_zoneid(3CONTRACT).
188 188
189 189
190 190 ownership state
191 191
192 192 The state of the contract, specified as CTS_OWNED, CTS_INHERITED,
193 193 CTS_ORPHAN, or CTS_DEAD. Use ct_status_get_state(3CONTRACT) to
194 194 obtain this information.
195 195
196 196
197 197 contract holder
198 198
199 199 If the contract's state is CTS_OWNED, the ID of the process which
200 200 owns the contract. If the contract's state is CTS_INHERITED, the ID
201 201 of the contract which is acting as regent. If the contract's state
202 202 is CTS_ORPHAN or CTS_DEAD, this is undefined. Use
203 203 ct_status_get_holder(3CONTRACT) to obtain this information.
204 204
205 205
206 206 number of critical events
207 207
208 208 The number of unacknowledged critical events pending on the
209 209 contract's event queue. Use ct_status_get_nevents(3CONTRACT) to
210 210 obtain this information.
211 211
212 212
213 213 negotiation time
214 214
215 215 The time remaining before the current synchronous negotiation times
216 216 out. Use ct_status_get_ntime(3CONTRACT) to obtain this information.
217 217
218 218
219 219 negotiation quantum time
220 220
221 221 The time remaining before the current negotiation quantum runs out.
222 222 Use ct_status_get_qtime(3CONTRACT) to obtain this information.
223 223
224 224
225 225 negotiation event ID
226 226
227 227 The ID of the event which initiated the negotiation timeout. Use
228 228 ct_status_get_nevid(3CONTRACT) to obtain this information.
229 229
230 230
231 231 cookie (term)
232 232
233 233 The contract's cookie term. Use ct_status_get_cookie(3CONTRACT) to
234 234 obtain this information.
235 235
236 236
237 237 Informative event set (term)
238 238
239 239 The contract's informative event set. Use
240 240 ct_status_get_informative(3CONTRACT) to obtain this information.
241 241
242 242
243 243 Critical event set (term)
244 244
245 245 The contract's critical event set. Use
246 246 ct_status_get_critical(3CONTRACT) to obtain this information.
247 247
248 248
249 249 EVENTS
250 250 All three event endpoints, /system/contract/type/bundle,
251 251 /system/contract/type/pbundle, and /system/contract/type/id/events, are
252 252 accessed in the same manner.
253 253
254 254
255 255 The following libcontract(3LIB) interfaces are used with an event
256 256 endpoint file descriptor:
257 257
258 258 ct_event_read(3contract)
259 259 ct_event_read_critical(3contract)
260 260 ct_event_reset(3contract)
261 261
262 262
263 263
264 264
265 265 To facilitate processes watching multiple event endpoints, it is
266 266 possible to poll(2) on event endpoints. When it is possible to receive
267 267 on an endpoint file descriptor, POLLIN is set for that descriptor.
268 268
269 269
270 270 An event object returned by ct_event_read(3CONTRACT) contains the
271 271 following information:
272 272
273 273 contract ID
274 274 The ID of the contract that generated the
275 275 event. Use ct_event_read(3CONTRACT) to
276 276 obtain this information.
277 277
278 278
279 279 event ID
280 280 The ID of the contract event.Use
281 281 ct_event_get_evid(3CONTRACT).
282 282
283 283
284 284 flags
285 285 A bit vector possibly including CT_ACK and
286 286 CTE_INFO. Use ct_event_get_flags(3CONTRACT)
287 287 to obtain this information.
288 288
289 289
290 290 event type
291 291 The type of event, equal to one of the
292 292 constants specified in the contract type's
293 293 manual page or CT_EV_NEGEND. Use
294 294 ct_event_get_type(3CONTRACT) to obtain this
295 295 information.
296 296
297 297
298 298 EVENT TYPES
299 299 The following event types are defined:
300 300
301 301 CT_EV_NEGEND
302 302 Some time after an exit negotiation is initiated, the
303 303 CT_EV_NEGEND event is sent. This indicates that the
304 304 negotiation ended. This might be because the operation
305 305 was cancelled, or because the operation was successful.
306 306 If successful, and the owner requested that a new
307 307 contract be written, this contains the ID of that
308 308 contract.
309 309
310 310 CT_EV_NEGEND cannot be included in a contract's
311 311 informative or critical event set. It is always
312 312 delivered and always critical. If CT_EV_NEGEND
313 313 indicates that the operation was successful, no further
314 314 events are sent. The contract's owner should use
315 315 ct_ctl_abandon(3CONTRACT) to abandon the contract.
316 316
317 317 A CT_EV_NEGEND event contains:
318 318
319 319 negotiation ID
320 320 The ID of the negotiation which
321 321 ended. Use
322 322 ct_event_get_nevid(3CONTRACT) to
323 323 obain this information.
324 324
325 325
326 326 new contract ID
327 327 The ID of the newly created
328 328 contract. This value is 0 if no
329 329 contract was created, or the ID of
330 330 the existing contract if the
331 331 operation was not completed. Use
332 332 ct_event_get_newct(3CONTRACT) to
333 333 obtain this information.
334 334
335 335
336 336
337 337 FILES
338 338 /system/contract
339 339
340 340 List of all contract types
341 341
342 342
343 343 /system/contract/all
344 344
345 345 Directory of all contract IDs
346 346
347 347
|
↓ open down ↓ |
347 lines elided |
↑ open up ↑ |
348 348 /system/contract/all/id
349 349
350 350 Symbolic link to the type-specific directory of contract id
351 351
352 352
353 353 /system/contract/type
354 354
355 355 Specific type directory
356 356
357 357
358 - /system/contract/type/templete
358 + /system/contract/type/template
359 359
360 360 Template for the contract type
361 361
362 362
363 363 /system/contract/type/bundle
364 364
365 365 Listening point for all contracts of that type
366 366
367 367
368 368 /system/contract/type/pbundle
369 369
370 370 Listening point for all contracts of that type for the opening
371 371 process
372 372
373 373
374 374 /system/contract/type /latest
375 375
376 376 Status of most recent type contract created by the opening LWP
377 377
378 378
379 379 /system/contract/type/ID
380 380
381 381 Directory for contract id
382 382
383 383
384 384 /system/contract/type/ID/events
385 385
386 386 Listening point for contract id's events
387 387
388 388
389 389 /system/contract/type/ID/ctl
390 390
391 391 Control file for contract ID
392 392
393 393
394 394 /system/contract/type/ID/status
395 395
396 396 Status info for contract ID
397 397
398 398
399 399 SEE ALSO
400 400 ctrun(1), ctstat(1), ctwatch(1), chroot(1M), close(2), ioctl(2),
401 401 open(2), poll(2), ct_ctl_abandon(3CONTRACT), ct_event_read(3CONTRACT),
402 402 ct_event_get_evid(3CONTRACT), ct_event_get_flags(3CONTRACT),
403 403 ct_event_get_nevid(3CONTRACT), ct_event_get_newct(3CONTRACT),
404 404 ct_event_get_type(3CONTRACT), ct_status_read(3CONTRACT),
405 405 ct_status_get_cookie(3CONTRACT), ct_status_get_critical(3CONTRACT),
406 406 ct_status_get_holder(3CONTRACT), ct_status_get_id(3CONTRACT),
407 407 ct_status_get_informative(3CONTRACT), ct_status_get_nevid(3CONTRACT),
408 408 ct_status_get_nevents(3CONTRACT), ct_status_get_ntime(3CONTRACT),
409 409 ct_status_get_qtime(3CONTRACT), ct_status_get_state(3CONTRACT),
410 410 ct_status_get_type(3CONTRACT), ct_tmpl_set_cookie(3CONTRACT),
411 411 ct_tmpl_set_critical(3CONTRACT), ct_tmpl_set_informative(3CONTRACT),
412 412 libcontract(3LIB), process(4), largefile(5), lfcompile(5),
413 413 privileges(5)
414 414
415 415
416 416
417 417 November 26, 2017 CONTRACT(4)
|
↓ open down ↓ |
49 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX