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/template\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)