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