share/man/man4/contract.4

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