Print this page
9842 man page typos and spelling
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man4/contract.4
+++ new/usr/src/man/man4/contract.4
1 1 '\" te
2 2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 6 .TH CONTRACT 4 "Nov 26, 2017"
7 7 .SH NAME
8 8 contract \- the contract file system
9 9 .SH SYNOPSIS
10 10 .LP
11 11 .nf
12 12 \fB/system/contract\fR
13 13 .fi
14 14
15 15 .SH DESCRIPTION
16 16 .LP
17 17 The \fB/system/contract\fR file system acts as the primary interface to the
18 18 contract subsystem. There is a subdirectory of \fB/system/contract\fR for each
19 19 available contract type.
20 20 .sp
21 21 .LP
22 22 \fB/system/contract\fR can be mounted on any mount point, in addition to the
23 23 standard \fB/system/contract\fR mount point, and can be mounted several places
24 24 at once. Such additional mounts are allowed in order to facilitate the
25 25 confinement of processes to subtrees of the file system using \fBchroot\fR(1M)
26 26 and yet allow such processes to continue to use contract commands and
27 27 interfaces.
28 28 .sp
29 29 .LP
30 30 A combination of standard system calls (for example, \fBopen\fR(2),
31 31 \fBclose\fR(2), and \fBpoll\fR(2)) and calls to \fBlibcontract\fR(3LIB) access
32 32 \fB/system/contract\fR files.
33 33 .sp
34 34 .LP
35 35 Consumers of the contract file system must be large file aware. See
36 36 \fBlargefile\fR(5) and \fBlfcompile64\fR(5).
37 37 .SS "DIRECTORY STRUCTURE"
38 38 .LP
39 39 At the top level, the \fB/system/contract\fR directory contains subdirectories
40 40 named with each available contract type, and one special directory, \fBall\fR.
41 41 Each of these directories is world-readable and world-searchable.
42 42 .SS "STRUCTURE OF \fB/system/contract/\fItype\fR\fR"
43 43 .LP
44 44 Each \fB/system/contract/\fItype\fR\fR directory contains a fixed number of
45 45 files. It also contains a variable number of subdirectories corresponding to
46 46 existing contracts of type \fItype\fR and named with the decimal representation
47 47 of the contracts' IDs.
48 48 .sp
49 49 .LP
50 50 The following files are in a \fB/system/contract/\fItype\fR\fR directory:
51 51 .sp
52 52 .ne 2
53 53 .na
54 54 \fB\fBtemplate\fR\fR
55 55 .ad
56 56 .RS 12n
57 57 Opening this file returns a file descriptor for a new \fItype\fR contract
58 58 template.
59 59 .sp
60 60 You can use the following \fBlibcontract\fR(3LIB) calls on a template file
61 61 descriptor:
62 62 .sp
63 63 .in +2
64 64 .nf
65 65 >
66 66
67 67 ct_tmpl_activate(3contract)
68 68 ct_tmpl_clear(3contract)
69 69 ct_tmpl_create(3contract)
70 70 .fi
71 71 .in -2
72 72 .sp
73 73
74 74 See TERMS for additional template functions.
75 75 .RE
76 76
77 77 .sp
78 78 .ne 2
79 79 .na
80 80 \fBlatest\fR
81 81 .ad
82 82 .RS 12n
83 83 Opening this file returns a file descriptor for the status file of the last
84 84 \fItype\fR contract written by the opening LWP. See \fBSTRUCTURE OF
85 85 /system/contract/\fItype\fR/\fIid\fR\fR. If the opening LWP has not created a
86 86 \fItype\fR contract, opening latest fails with \fBESRCH\fR.
87 87 .RE
88 88
89 89 .sp
90 90 .ne 2
91 91 .na
92 92 \fBbundle\fR
93 93 .ad
94 94 .RS 12n
95 95 Opening this file returns a file descriptor for an event endpoint which
96 96 receives events from all \fItype\fR contracts on the system. No privileges are
97 97 required to open a type bundle event endpoint. Events sent by contracts owned
98 98 and written by users other than the reader's effective user id are invisible,
99 99 that is, they are silently skipped, unless the reader has
100 100 \fB{PRIV_CONTRACT_OBSERVER}\fR in its effective set. See \fBEVENTS\fR.
101 101 .RE
102 102
103 103 .sp
104 104 .ne 2
105 105 .na
106 106 \fBpbundle\fR
107 107 .ad
108 108 .RS 12n
109 109 Opening this file returns a file descriptor for an event endpoint which
110 110 receives events from all \fItype\fR contracts held by the opening process. See
111 111 \fBEVENTS\fR.
112 112 .RE
113 113
114 114 .SS "STRUCTURE OF /system/contract/all"
115 115 .LP
116 116 The \fB/system/contract/all\fR directory contains a numerically named file for
117 117 each contract in the system. Each file is a symbolic link to the type-specific
118 118 directory for that contract, that is \fB/system/contract/all/\fIid\fR\fR points
119 119 to \fB/system/contract/\fItype\fR/\fIid\fR\fR.
120 120 .SS "STRUCTURE OF /system/contract/\fItype\fR/\fIid\fR"
121 121 .LP
122 122 Each \fB/system/contract/\fItype\fR/\fIid\fR\fR directory contains the
123 123 following files:
124 124 .sp
125 125 .ne 2
126 126 .na
127 127 \fBctl\fR
128 128 .ad
129 129 .RS 10n
130 130 Opening this file returns a file descriptor for contract \fIid\fR's control
131 131 file. The open fails if the opening process does not hold contract \fIid\fR and
132 132 the contract has not been inherited by the process contract of which the
133 133 opening process is a member. See \fBprocess\fR(4).
134 134 .sp
135 135 The following \fBlibcontract\fR(3LIB) calls can be made on a \fBctl\fR file
136 136 descriptor if the contract is owned by the caller:
137 137 .sp
138 138 .in +2
139 139 .nf
140 140 ct_ctl_abandon(3contract)
141 141 ct_ctl_newct(3contract)
142 142 ct_ctl_ack(3contract)
143 143 ct_ctl_qack(3contract)
144 144 .fi
145 145 .in -2
146 146 .sp
147 147
148 148 The following \fBlibcontract\fR(3LIB) call can be made on a ctl file descriptor
149 149 if the contract doesn't have an owner:
150 150 .sp
151 151 .in +2
152 152 .nf
153 153 ct_ctl_adopt(3contract)
154 154 .fi
155 155 .in -2
156 156 .sp
157 157
158 158 .RE
159 159
160 160 .sp
161 161 .ne 2
162 162 .na
163 163 \fBstatus\fR
164 164 .ad
165 165 .RS 10n
166 166 Opening this file returns a file descriptor for contract \fIid\fR's status
167 167 file. The following \fBlibcontract\fR(3LIB) calls can be made on a status file
168 168 descriptor:
169 169 .LP
170 170 .nf
171 171 ct_status_read(3contract)
172 172 .fi
173 173
174 174 See STATUS.
175 175 .RE
176 176
177 177 .sp
178 178 .ne 2
179 179 .na
180 180 \fBevents\fR
181 181 .ad
182 182 .RS 10n
183 183 Opening this file returns a file descriptor for an event endpoint which
184 184 receives events from contract \fIid\fR. See \fBEVENTS\fR.
185 185 .sp
186 186 Only a process which has the same effective user ID as the process owning the
187 187 contract, the same effective user ID as the contract's author, or has
188 188 \fB{PRIV_CONTRACT_OBSERVER}\fR in its effective set can open the event endpoint
189 189 for a contract.
190 190 .RE
191 191
192 192 .SS "TERMS"
193 193 .LP
194 194 The following terms are defined for all contracts:
195 195 .sp
196 196 .ne 2
197 197 .na
198 198 \fBcookie\fR
199 199 .ad
200 200 .RS 25n
201 201 Specifies a 64-bit quantity that the contract author can use to identify the
202 202 contract. Use \fBct_tmpl_set_cookie\fR(3CONTRACT) to set this term.
203 203 .RE
204 204
205 205 .sp
206 206 .ne 2
207 207 .na
208 208 \fBinformative event set\fR
209 209 .ad
210 210 .RS 25n
211 211 Selects which events are delivered as informative events. Use
212 212 \fBct_tmpl_set_informative\fR(3CONTRACT) to set this term.
213 213 .RE
214 214
215 215 .sp
216 216 .ne 2
217 217 .na
218 218 \fBcritical event set\fR
219 219 .ad
220 220 .RS 25n
221 221 Selects which events are delivered as critical events. Use
222 222 \fBct_tmpl_set_critical\fR(3CONTRACT) to set this term.
223 223 .RE
224 224
225 225 .SS "STATUS"
226 226 .LP
227 227 A status object returned by \fBct_status_read\fR(3CONTRACT) contains the
228 228 following pieces of information:
229 229 .sp
230 230 .ne 2
231 231 .na
232 232 \fBcontract ID\fR
233 233 .ad
234 234 .sp .6
235 235 .RS 4n
236 236 The numeric ID of the contract. Use \fBct_status_get_id\fR(3CONTRACT) to obtain
237 237 this information.
238 238 .RE
239 239
240 240 .sp
241 241 .ne 2
242 242 .na
243 243 \fBcontract type\fR
244 244 .ad
245 245 .sp .6
246 246 .RS 4n
247 247 The type of the contract, specified as a string. Obtained using
248 248 \fBct_status_get_type\fR(3CONTRACT). The contract type is the same as its
249 249 subdirectory name under \fB/system/contract\fR.
250 250 .RE
251 251
252 252 .sp
253 253 .ne 2
254 254 .na
255 255 \fBcreator's zone ID\fR
256 256 .ad
257 257 .sp .6
258 258 .RS 4n
259 259 The zone ID of the process which created the contract. Obtained using
260 260 \fBct_status_get_zoneid\fR(3CONTRACT).
261 261 .RE
262 262
263 263 .sp
264 264 .ne 2
265 265 .na
266 266 \fBownership state\fR
267 267 .ad
268 268 .sp .6
269 269 .RS 4n
270 270 The state of the contract, specified as \fBCTS_OWNED\fR, \fBCTS_INHERITED\fR,
271 271 \fBCTS_ORPHAN\fR, or \fBCTS_DEAD\fR. Use \fBct_status_get_state\fR(3CONTRACT)
272 272 to obtain this information.
273 273 .RE
274 274
275 275 .sp
276 276 .ne 2
277 277 .na
278 278 \fBcontract holder\fR
279 279 .ad
280 280 .sp .6
281 281 .RS 4n
282 282 If the contract's state is \fBCTS_OWNED\fR, the ID of the process which owns
283 283 the contract. If the contract's state is \fBCTS_INHERITED\fR, the ID of the
284 284 contract which is acting as regent. If the contract's state is \fBCTS_ORPHAN\fR
285 285 or \fBCTS_DEAD\fR, this is undefined. Use \fBct_status_get_holder\fR(3CONTRACT)
286 286 to obtain this information.
287 287 .RE
288 288
289 289 .sp
290 290 .ne 2
291 291 .na
292 292 \fBnumber of critical events\fR
293 293 .ad
294 294 .sp .6
295 295 .RS 4n
296 296 The number of unacknowledged critical events pending on the contract's event
297 297 queue. Use \fBct_status_get_nevents\fR(3CONTRACT) to obtain this information.
298 298 .RE
299 299
300 300 .sp
301 301 .ne 2
302 302 .na
303 303 \fBnegotiation time\fR
304 304 .ad
305 305 .sp .6
306 306 .RS 4n
307 307 The time remaining before the current synchronous negotiation times out. Use
308 308 \fBct_status_get_ntime\fR(3CONTRACT) to obtain this information.
309 309 .RE
310 310
311 311 .sp
312 312 .ne 2
313 313 .na
314 314 \fBnegotiation quantum time\fR
315 315 .ad
316 316 .sp .6
317 317 .RS 4n
318 318 The time remaining before the current negotiation quantum runs out. Use
319 319 \fBct_status_get_qtime\fR(3CONTRACT) to obtain this information.
320 320 .RE
321 321
322 322 .sp
323 323 .ne 2
324 324 .na
325 325 \fBnegotiation event ID\fR
326 326 .ad
327 327 .sp .6
328 328 .RS 4n
329 329 The ID of the event which initiated the negotiation timeout. Use
330 330 \fBct_status_get_nevid\fR(3CONTRACT) to obtain this information.
331 331 .RE
332 332
333 333 .sp
334 334 .ne 2
335 335 .na
336 336 \fBcookie (term)\fR
337 337 .ad
338 338 .sp .6
339 339 .RS 4n
340 340 The contract's cookie term. Use \fBct_status_get_cookie\fR(3CONTRACT) to obtain
341 341 this information.
342 342 .RE
343 343
344 344 .sp
345 345 .ne 2
346 346 .na
347 347 \fBInformative event set (term)\fR
348 348 .ad
349 349 .sp .6
350 350 .RS 4n
351 351 The contract's informative event set. Use
352 352 \fBct_status_get_informative\fR(3CONTRACT) to obtain this information.
353 353 .RE
354 354
355 355 .sp
356 356 .ne 2
357 357 .na
358 358 \fBCritical event set (term)\fR
359 359 .ad
360 360 .sp .6
361 361 .RS 4n
362 362 The contract's critical event set. Use \fBct_status_get_critical\fR(3CONTRACT)
363 363 to obtain this information.
364 364 .RE
365 365
366 366 .SS "EVENTS"
367 367 .LP
368 368 All three event endpoints, \fB/system/contract/\fItype\fR/bundle\fR,
369 369 \fB/system/contract/\fItype\fR/pbundle\fR, and
370 370 \fB/system/contract/\fItype\fR/\fIid\fR/events\fR, are accessed in the same
371 371 manner.
372 372 .sp
373 373 .LP
374 374 The following \fBlibcontract\fR(3LIB) interfaces are used with an event
375 375 endpoint file descriptor:
376 376 .sp
377 377 .in +2
378 378 .nf
379 379 ct_event_read(3contract)
380 380 ct_event_read_critical(3contract)
381 381 ct_event_reset(3contract)
382 382 .fi
383 383 .in -2
384 384 .sp
385 385
386 386 .sp
387 387 .LP
388 388 To facilitate processes watching multiple event endpoints, it is possible to
389 389 poll(2) on event endpoints. When it is possible to receive on an endpoint file
390 390 descriptor, POLLIN is set for that descriptor.
391 391 .sp
392 392 .LP
393 393 An event object returned by \fBct_event_read\fR(3CONTRACT) contains the
394 394 following information:
395 395 .sp
396 396 .ne 2
397 397 .na
398 398 \fBcontract ID\fR
399 399 .ad
400 400 .RS 28n
401 401 The ID of the contract that generated the event. Use
402 402 \fBct_event_read\fR(3CONTRACT) to obtain this information.
403 403 .RE
404 404
405 405 .sp
406 406 .ne 2
407 407 .na
408 408 \fBevent ID\fR
409 409 .ad
410 410 .RS 28n
411 411 The ID of the contract event.Use \fBct_event_get_evid\fR(3CONTRACT).
412 412 .RE
413 413
414 414 .sp
415 415 .ne 2
416 416 .na
417 417 \fBflags\fR
418 418 .ad
419 419 .RS 28n
420 420 A bit vector possibly including \fBCT_ACK\fR and \fBCTE_INFO\fR. Use
421 421 \fBct_event_get_flags\fR(3CONTRACT) to obtain this information.
422 422 .RE
423 423
424 424 .sp
425 425 .ne 2
426 426 .na
427 427 \fBevent type\fR
428 428 .ad
429 429 .RS 28n
430 430 The type of event, equal to one of the constants specified in the contract
431 431 type's manual page or \fBCT_EV_NEGEND\fR. Use
432 432 \fBct_event_get_type\fR(3CONTRACT) to obtain this information.
433 433 .RE
434 434
435 435 .SS "EVENT TYPES"
436 436 .LP
437 437 The following event types are defined:
438 438 .sp
439 439 .ne 2
440 440 .na
441 441 \fB\fBCT_EV_NEGEND\fR\fR
442 442 .ad
443 443 .RS 16n
444 444 Some time after an exit negotiation is initiated, the \fBCT_EV_NEGEND\fR event
445 445 is sent. This indicates that the negotiation ended. This might be because the
446 446 operation was cancelled, or because the operation was successful. If
447 447 successful, and the owner requested that a new contract be written, this
448 448 contains the ID of that contract.
449 449 .sp
450 450 \fBCT_EV_NEGEND\fR cannot be included in a contract's informative or critical
451 451 event set. It is always delivered and always critical. If \fBCT_EV_NEGEND\fR
452 452 indicates that the operation was successful, no further events are sent. The
453 453 contract's owner should use \fBct_ctl_abandon\fR(3CONTRACT) to abandon the
454 454 contract.
455 455 .sp
456 456 A \fBCT_EV_NEGEND\fR event contains:
457 457 .sp
458 458 .ne 2
459 459 .na
460 460 \fBnegotiation ID\fR
461 461 .ad
462 462 .RS 19n
463 463 The ID of the negotiation which ended. Use \fBct_event_get_nevid\fR(3CONTRACT)
464 464 to obain this information.
465 465 .RE
466 466
467 467 .sp
468 468 .ne 2
469 469 .na
470 470 \fBnew contract ID\fR
471 471 .ad
472 472 .RS 19n
473 473 The ID of the newly created contract. This value is 0 if no contract was
474 474 created, or the ID of the existing contract if the operation was not completed.
475 475 Use \fBct_event_get_newct\fR(3CONTRACT) to obtain this information.
476 476 .RE
477 477
478 478 .RE
479 479
480 480 .SH FILES
481 481 .ne 2
482 482 .na
483 483 \fB\fB/system/contract\fR\fR
484 484 .ad
485 485 .sp .6
486 486 .RS 4n
487 487 List of all contract types
488 488 .RE
489 489
490 490 .sp
491 491 .ne 2
492 492 .na
493 493 \fB\fB/system/contract/all\fR\fR
494 494 .ad
495 495 .sp .6
496 496 .RS 4n
497 497 Directory of all contract IDs
498 498 .RE
499 499
500 500 .sp
501 501 .ne 2
502 502 .na
503 503 \fB\fB/system/contract/all/\fIid\fR\fR\fR
504 504 .ad
505 505 .sp .6
506 506 .RS 4n
507 507 Symbolic link to the type-specific directory of contract \fIid\fR
508 508 .RE
509 509
510 510 .sp
511 511 .ne 2
512 512 .na
|
↓ open down ↓ |
512 lines elided |
↑ open up ↑ |
513 513 \fB\fB/system/contract/\fItype\fR\fR\fR
514 514 .ad
515 515 .sp .6
516 516 .RS 4n
517 517 Specific type directory
518 518 .RE
519 519
520 520 .sp
521 521 .ne 2
522 522 .na
523 -\fB\fB/system/contract/\fItype\fR/templete\fR\fR
523 +\fB\fB/system/contract/\fItype\fR/template\fR\fR
524 524 .ad
525 525 .sp .6
526 526 .RS 4n
527 527 Template for the contract type
528 528 .RE
529 529
530 530 .sp
531 531 .ne 2
532 532 .na
533 533 \fB\fB/system/contract/\fItype\fR/bundle\fR\fR
534 534 .ad
535 535 .sp .6
536 536 .RS 4n
537 537 Listening point for all contracts of that type
538 538 .RE
539 539
540 540 .sp
541 541 .ne 2
542 542 .na
543 543 \fB\fB/system/contract/\fItype\fR/pbundle\fR\fR
544 544 .ad
545 545 .sp .6
546 546 .RS 4n
547 547 Listening point for all contracts of that type for the opening process
548 548 .RE
549 549
550 550 .sp
551 551 .ne 2
552 552 .na
553 553 \fB\fB/system/contract/\fItype\fR /latest\fR\fR
554 554 .ad
555 555 .sp .6
556 556 .RS 4n
557 557 Status of most recent \fItype\fR contract created by the opening LWP
558 558 .RE
559 559
560 560 .sp
561 561 .ne 2
562 562 .na
563 563 \fB\fB/system/contract/\fItype\fR/\fIID\fR\fR\fR
564 564 .ad
565 565 .sp .6
566 566 .RS 4n
567 567 Directory for contract id
568 568 .RE
569 569
570 570 .sp
571 571 .ne 2
572 572 .na
573 573 \fB\fB/system/contract/\fItype\fR/\fIID\fR/events\fR\fR
574 574 .ad
575 575 .sp .6
576 576 .RS 4n
577 577 Listening point for contract id's events
578 578 .RE
579 579
580 580 .sp
581 581 .ne 2
582 582 .na
583 583 \fB\fB/system/contract/\fItype\fR/\fIID\fR/ctl\fR\fR
584 584 .ad
585 585 .sp .6
586 586 .RS 4n
587 587 Control file for contract ID
588 588 .RE
589 589
590 590 .sp
591 591 .ne 2
592 592 .na
593 593 \fB\fB/system/contract/\fItype\fR/\fIID\fR/status\fR\fR
594 594 .ad
595 595 .sp .6
596 596 .RS 4n
597 597 Status info for contract ID
598 598 .RE
599 599
600 600 .SH SEE ALSO
601 601 .LP
602 602 \fBctrun\fR(1), \fBctstat\fR(1), \fBctwatch\fR(1), \fBchroot\fR(1M),
603 603 \fBclose\fR(2), \fBioctl\fR(2), \fBopen\fR(2), \fBpoll\fR(2),
604 604 \fBct_ctl_abandon\fR(3CONTRACT), \fBct_event_read\fR(3CONTRACT),
605 605 \fBct_event_get_evid\fR(3CONTRACT), \fBct_event_get_flags\fR(3CONTRACT),
606 606 \fBct_event_get_nevid\fR(3CONTRACT), \fBct_event_get_newct\fR(3CONTRACT),
607 607 \fBct_event_get_type\fR(3CONTRACT),
608 608 \fBct_status_read\fR(3CONTRACT), \fBct_status_get_cookie\fR(3CONTRACT),
609 609 \fBct_status_get_critical\fR(3CONTRACT), \fBct_status_get_holder\fR(3CONTRACT),
610 610 \fBct_status_get_id\fR(3CONTRACT), \fBct_status_get_informative\fR(3CONTRACT),
611 611 \fBct_status_get_nevid\fR(3CONTRACT), \fBct_status_get_nevents\fR(3CONTRACT),
612 612 \fBct_status_get_ntime\fR(3CONTRACT), \fBct_status_get_qtime\fR(3CONTRACT),
613 613 \fBct_status_get_state\fR(3CONTRACT), \fBct_status_get_type\fR(3CONTRACT),
614 614 \fBct_tmpl_set_cookie\fR(3CONTRACT), \fBct_tmpl_set_critical\fR(3CONTRACT),
615 615 \fBct_tmpl_set_informative\fR(3CONTRACT), \fBlibcontract\fR(3LIB),
616 616 \fBprocess\fR(4), \fBlargefile\fR(5), \fBlfcompile\fR(5), \fBprivileges\fR(5)
|
↓ open down ↓ |
83 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX