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