1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 2016, Joyent, Inc.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH PROCESS 4 "Sept 6, 2016"
   8 .SH NAME
   9 process \- process contract type
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB/system/contract/process\fR
  14 .fi
  15 
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 Process contracts allow processes to create a fault boundary around a set of
  20 subprocesses and observe events which occur within that boundary.
  21 .sp
  22 .LP
  23 Process contracts are managed using the \fBcontract\fR(4) file system and the
  24 \fBlibcontract\fR(3LIB) library. The process contract type directory is
  25 \fB/system/contract/process\fR.
  26 .SS "CREATION"
  27 .sp
  28 .LP
  29 A process contract is created when an LWP that has an active process contract
  30 template calls \fBfork\fR(2). Initially, the child process created by
  31 \fBfork()\fR is the only resource managed by the contract. When an LWP that
  32 does not have an active process contract template calls \fBfork()\fR, the child
  33 process created by \fBfork()\fR is added as a resource to the process contract
  34 of which the parent was a member.
  35 .SS "EVENT TYPES"
  36 .sp
  37 .LP
  38 The following events types are defined:
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fBCT_PR_EV_EMPTY\fR\fR
  43 .ad
  44 .sp .6
  45 .RS 4n
  46 The last member of the process contract exited.
  47 .RE
  48 
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fBCT_PR_EV_FORK\fR\fR
  53 .ad
  54 .sp .6
  55 .RS 4n
  56 A new process has been added to the process contract.
  57 .RE
  58 
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fBCT_PR_EV_EXIT\fR\fR
  63 .ad
  64 .sp .6
  65 .RS 4n
  66 A member of the process contract exited.
  67 .RE
  68 
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBCT_PR_EV_CORE\fR\fR
  73 .ad
  74 .sp .6
  75 .RS 4n
  76 A process failed and dumped core. This could also occur if the process would
  77 have dumped core had appropriate \fBcoreadm\fR(1M) options been enabled and
  78 core file size was unlimited.
  79 .RE
  80 
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBCT_PR_EV_SIGNAL\fR\fR
  85 .ad
  86 .sp .6
  87 .RS 4n
  88 A process received a fatal signal from a process, other than the owner of the
  89 process contract, that is a member of a different process contract.
  90 .RE
  91 
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBCT_PR_EV_HWERR\fR\fR
  96 .ad
  97 .sp .6
  98 .RS 4n
  99 A process was killed because of an uncorrectable hardware error.
 100 .RE
 101 
 102 .SS "TERMS"
 103 .sp
 104 .LP
 105 The following common contract terms, defined in \fBcontract\fR(4), have
 106 process-contract specific attributes:
 107 .sp
 108 .ne 2
 109 .na
 110 \fBcritical event set\fR
 111 .ad
 112 .sp .6
 113 .RS 4n
 114 The default value for the critical event set is \fB(CT_PR_EV_EMPTY |
 115 CT_PR_EV_HWERR)\fR.
 116 .sp
 117 An attempt by a user without the \fB{PRIV_CONTRACT_EVENT}\fR privilege in its
 118 effective set to add an event, other than \fBCT_PR_EV_EMPTY\fR, to the critical
 119 event set which is not present in the fatal set, or if the \fBCT_PR_PGONLY\fR
 120 parameter is set and the same user attempts to add any event, other than
 121 \fBCT_PR_EV_EMPTY\fR, to the critical event set, fails.
 122 .RE
 123 
 124 .sp
 125 .ne 2
 126 .na
 127 \fBinformative event set\fR
 128 .ad
 129 .sp .6
 130 .RS 4n
 131 The default value for the informative event set is \fB(CT_PR_EV_CORE |
 132 CT_PR_EV_SIGNAL)\fR.
 133 .RE
 134 
 135 .sp
 136 .LP
 137 The following contract terms can be read from or written to a process contract
 138 template using the named \fBlibcontract\fR(3LIB) interfaces. These contract
 139 terms are in addition to those described in \fBcontract\fR(4).
 140 .sp
 141 .ne 2
 142 .na
 143 \fBcreator's aux\fR
 144 .ad
 145 .sp .6
 146 .RS 4n
 147 Auxiliary contract description. The purpose of this field is to provide the
 148 contract creator with a way to differentiate process contracts it creates under
 149 the same service FMRI. Use ct_pr_tmpl_set_svc_aux(3CONTRACT) to set this term.
 150 The default value is an empty string. The contents of this field should be
 151 limited to 7-bit ASCII values.
 152 .RE
 153 
 154 .sp
 155 .ne 2
 156 .na
 157 \fBfatal event set\fR
 158 .ad
 159 .sp .6
 160 .RS 4n
 161 Defines a set of events which, when generated, causes all members of the
 162 process contract to be killed with \fBSIGKILL\fR, or the intersection of the
 163 contract and the containing process group if the \fBCT_PR_PGRPONLY\fR parameter
 164 is set. Set this term with \fBct_pr_tmpl_set_fatal\fR(3CONTRACT). The fatal
 165 event set is restricted to \fBCT_PR_EV_CORE\fR, \fBCT_PR_EV_SIGNAL\fR, and
 166 \fBCT_PR_EV_HWERR\fR. For \fBCT_PR_EV_CORE\fR and \fBCT_PR_EV_SIGNAL\fR events,
 167 the scope of \fBSIGKILL\fR is limited to those processes which the contract
 168 author or the event source could have normally sent signals to.
 169 .sp
 170 The default value for the fatal event set is \fBCT_PR_EV_HWERR\fR.
 171 .sp
 172 If a user without the \fB{PRIV_CONTRACT_EVENT}\fR privilege in its effective
 173 set removes an event from the fatal event set which is present in the critical
 174 event set, the corresponding event is automatically removed from the critical
 175 event set and added to the informative event set.
 176 .RE
 177 
 178 .sp
 179 .ne 2
 180 .na
 181 \fBparameter set\fR
 182 .ad
 183 .sp .6
 184 .RS 4n
 185 Defines miscellaneous other settings. Use \fBct_pr_tmpl_set_param\fR(3CONTRACT)
 186 to set this term.
 187 .sp
 188 The default parameter set is empty.
 189 .sp
 190 The value is a bit vector comprised of some or all of:
 191 .sp
 192 .ne 2
 193 .na
 194 \fB\fBCT_PR_INHERIT\fR\fR
 195 .ad
 196 .sp .6
 197 .RS 4n
 198 If set, indicates that the process contract is to be inherited by the process
 199 contract the contract owner is a member of if the contract owner exits before
 200 explicitly abandoning the process contract.
 201 .sp
 202 If not set, the process contract is automatically abandoned when the owner
 203 exits.
 204 .RE
 205 
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBCT_PR_KEEP_EXEC\fR\fR
 210 .ad
 211 .sp .6
 212 .RS 4n
 213 If set, the process contract template remains active across \fBexec\fR(2).
 214 This can be used to setup a contract for children of an application which
 215 is not contract-aware. If this is not set then the system clears the active
 216 template when the process execs. Because this option is intended for an
 217 application which is not contract-aware, new child process contracts will be
 218 automatically abandoned by the parent.
 219 .RE
 220 
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBCT_PR_NOORPHAN\fR\fR
 225 .ad
 226 .sp .6
 227 .RS 4n
 228 If set, all processes in a process contract are sent \fBSIGKILL\fR if the
 229 process contract is abandoned, either explicitly or because the holder died and
 230 \fBCT_PR_INHERIT\fR was not set. The scope of \fBSIGKILL\fR is limited to those
 231 processes which the contract author or the event source could have normally
 232 sent signals to.
 233 .sp
 234 If this is not set and the process contract is abandoned, the process contract
 235 is orphaned, that is, continues to exist without owner.
 236 .RE
 237 
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBCT_PR_PGRPONLY\fR\fR
 242 .ad
 243 .sp .6
 244 .RS 4n
 245 If set, only those processes within the same process group and process contract
 246 as a fatal error-generating process are killed.
 247 .sp
 248 If not set, all processes within the process contract are killed if a member
 249 process encounters an error specified in the fatal set.
 250 .sp
 251 If a user without the \fB{PRIV_CONTRACT_EVENT}\fR privilege in its effective
 252 set adds \fBCT_PR_PGRPONLY\fR to a template's parameter set, any events other
 253 than \fBCT_PR_EV_EMPTY\fR are automatically removed from the critical event set
 254 and added to the informative event set.
 255 .RE
 256 
 257 .sp
 258 .ne 2
 259 .na
 260 \fB\fBCT_PR_REGENT\fR\fR
 261 .ad
 262 .sp .6
 263 .RS 4n
 264 If set, the process contract can inherit unabandoned contracts left by exiting
 265 member processes.
 266 .sp
 267 If not set, indicates that the process contract should not inherit contracts
 268 from member processes. If a process exits before abandoning a contract it owns
 269 and is a member of a process contract which does not have \fBCT_PR_REGENT\fR
 270 set, the system automatically abandons the contract.
 271 .sp
 272 If a regent process contract has inherited contracts and is abandoned by its
 273 owner, its inherited contracts are abandoned.
 274 .RE
 275 
 276 .RE
 277 
 278 .sp
 279 .ne 2
 280 .na
 281 \fBservice FMRI\fR
 282 .ad
 283 .sp .6
 284 .RS 4n
 285 Specifies the service FMRI associated with the process contract. Use
 286 \fBct_pr_tmpl_set_svc_fmri\fR(3CONTRACT) to set this term. The default is to
 287 inherit the value from the creator's process contract. When this term is
 288 uninitialized, \fBct_pr_tmpl_get_svc_fmri\fR(3CONTRACT) returns the token
 289 string \fBinherited:\fR to indicate the value has not been set and is
 290 inherited. Setting the service FMRI to \fBinherited\fR: clears the current
 291 (\fBB\fR value and the \fBterm\fR is inherited from the creator's process
 292 contract. To set this term a process must have \fB{PRIV_CONTRACT_IDENTITY}\fR
 293 in its effective set.
 294 .RE
 295 
 296 .sp
 297 .ne 2
 298 .na
 299 \fBtransfer contract\fR
 300 .ad
 301 .sp .6
 302 .RS 4n
 303 Specifies the ID of an empty process contract held by the caller whose
 304 inherited process contracts are to be transferred to the newly created
 305 contract. Use \fBct_pr_tmpl_set_transfer\fR(3CONTRACT) to set the tranfer
 306 contract. Attempts to specify a contract not held by the calling process, or a
 307 contract which still has processes in it, fail.
 308 .sp
 309 The default transfer term is \fB0\fR, that is, no contract.
 310 .RE
 311 
 312 .SS "STATUS"
 313 .sp
 314 .LP
 315 In addition to the standard items, the status object read from a status file
 316 descriptor contains the following items to obtain this information
 317 respectively:
 318 .sp
 319 .ne 2
 320 .na
 321 \fBservice contract ID\fR
 322 .ad
 323 .sp .6
 324 .RS 4n
 325 Specifies the process contract id which defined the service FMRI term. Use
 326 \fBct_pr_status_get_svc_ctid\fR(3CONTRACT) to read the term's value. It can be
 327 used to determine if the service FMRI was inherited as in the example below.
 328 .sp
 329 .in +2
 330 .nf
 331 ctid_t ctid;           /* our contract id */
 332 int fd;       /* fd of ctid's status file */
 333 
 334 ct_stathdl_(Bt status;
 335 ctid_t svc_ctid;
 336 
 337 if (ct_status_read(fd, CTD_FIXED, &status) == 0) {
 338       if (ct_pr_status_get_svc_ctid(status, &svc_ctid) == 0) {
 339             if (svc_ctid == ctid)
 340                 /* not inherited */
 341             else
 342                 /* inherited */
 343       }
 344       ct_status_free(status);
 345 }
 346 .fi
 347 .in -2
 348 .sp
 349 
 350 .RE
 351 
 352 .sp
 353 .LP
 354 If \fBCTD_ALL\fR is specified, the following items are also available:
 355 .sp
 356 .ne 2
 357 .na
 358 \fBMember list\fR
 359 .ad
 360 .sp .6
 361 .RS 4n
 362 The PIDs of processes which are members of the process contract. Use
 363 \fBct_pr_status_get_members\fR(3CONTRACT) for this information.
 364 .RE
 365 
 366 .sp
 367 .ne 2
 368 .na
 369 \fBInherited contract list\fR
 370 .ad
 371 .sp .6
 372 .RS 4n
 373 The IDs of contracts which have been inherited by the process contract. Use
 374 \fBct_pr_status_get_contracts\fR(3CONTRACT) to obtain this information.
 375 .RE
 376 
 377 .sp
 378 .ne 2
 379 .na
 380 \fBService FMRI (term)\fR
 381 .ad
 382 .sp .6
 383 .RS 4n
 384 Values equal to the terms used when the contract was written. The Service FMRI
 385 term of the process contract of a process en(\fBBtering\fR a zone has  the
 386 value \fBsvc:/system/zone_enter:default\fR when read from the non-global zone.
 387 .RE
 388 
 389 .sp
 390 .ne 2
 391 .na
 392 \fBcontract creator\fR
 393 .ad
 394 .sp .6
 395 .RS 4n
 396 Specifies the process that created the process contract. Use
 397 \fBct_pr_status_get_svc_creator\fR(3CONTRACT) to read the term's value.
 398 .RE
 399 
 400 .sp
 401 .ne 2
 402 .na
 403 \fBcreator's aux (term)\fR
 404 .ad
 405 .sp .6
 406 .RS 4n
 407 Values equal to the terms used when the contract was written.
 408 .RE
 409 
 410 .sp
 411 .LP
 412 The following standard status items have different meanings in some situations:
 413 .sp
 414 .ne 2
 415 .na
 416 \fBOwnership state\fR
 417 .ad
 418 .sp .6
 419 .RS 4n
 420 If the process contract has a state of \fBCTS_OWNED\fR or \fBCTS_INHERITED\fR
 421 and is held by an entity in the global zone, but contains processes in a
 422 non-global zone, it appears to have the state \fBCTS_OWNED\fR when observed by
 423 processes in the non-global zone.
 424 .RE
 425 
 426 .sp
 427 .ne 2
 428 .na
 429 \fBContract holder\fR
 430 .ad
 431 .sp .6
 432 .RS 4n
 433 If the process contract has a state of \fBCTS_OWNED\fR or \fBCTS_INHERITED\fR
 434 and is held by an entity in the global zone, but contains processes in a
 435 non-global zone, it appears to be held by the non-global zone's \fBzsched\fR
 436 when observed by processes in the non-global zone.
 437 .RE
 438 
 439 .SS "EVENTS"
 440 .sp
 441 .LP
 442 In addition to the standard items, an event generated by a process contract
 443 contains the following information:
 444 .sp
 445 .ne 2
 446 .na
 447 \fBGenerating PID\fR
 448 .ad
 449 .sp .6
 450 .RS 4n
 451 The process ID of the member process which experienced the event, or caused the
 452 contract event to be generated (in the case of \fBCT_PR_EV_EMPTY\fR). Use
 453 \fBct_pr_event_get_pid\fR(3CONTRACT) to obtain this information.
 454 .RE
 455 
 456 .sp
 457 .LP
 458 If the event type is \fBCT_PR_EV_FORK\fR, the event contains:
 459 .sp
 460 .ne 2
 461 .na
 462 \fBParent PID\fR
 463 .ad
 464 .sp .6
 465 .RS 4n
 466 The process ID which forked [Generating PID]. Use
 467 \fBct_pr_event_get_ppid\fR(3CONTRACT) to obtain this information.
 468 .RE
 469 
 470 .sp
 471 .LP
 472 If the event type is \fBCT_PR_EV_EXIT\fR, the event contains:
 473 .sp
 474 .ne 2
 475 .na
 476 \fBExit status\fR
 477 .ad
 478 .sp .6
 479 .RS 4n
 480 The exit status of the process. Use \fBct_pr_event_get_exitstatus\fR(3CONTRACT)
 481 to obtain this information.
 482 .RE
 483 
 484 .sp
 485 .LP
 486 If the event type is \fBCT_PR_EV_CORE\fR, the event can contain:
 487 .sp
 488 .ne 2
 489 .na
 490 \fBProcess core name\fR
 491 .ad
 492 .sp .6
 493 .RS 4n
 494 The name of the per-process core file. Use
 495 \fBct_pr_event_get_pcorefile\fR(3CONTRACT) to obtain this information.
 496 .RE
 497 
 498 .sp
 499 .ne 2
 500 .na
 501 \fBGlobal core name\fR
 502 .ad
 503 .sp .6
 504 .RS 4n
 505 The name of the process's zone's global core file. Use
 506 \fBct_pr_event_get_gcorefile\fR(3CONTRACT) to obtain this information.
 507 .RE
 508 
 509 .sp
 510 .ne 2
 511 .na
 512 \fBZone core name\fR
 513 .ad
 514 .sp .6
 515 .RS 4n
 516 The name of the system-wide core file in the global zone. Use
 517 \fBct_pr_event_get_zcorefile\fR(3CONTRACT) to obtain this information.
 518 .RE
 519 
 520 .sp
 521 .LP
 522 See \fBcoreadm\fR(1M) for more information about per-process, global, and
 523 system-wide core files.
 524 .sp
 525 .LP
 526 If the event type is \fBCT_PR_EV_SIGNAL\fR, the event contains:
 527 .sp
 528 .ne 2
 529 .na
 530 \fBSignal\fR
 531 .ad
 532 .sp .6
 533 .RS 4n
 534 The number of the signal which killed the process. Use
 535 \fBct_pr_event_get_signal\fR(3CONTRACT) to obtain this information.
 536 .RE
 537 
 538 .sp
 539 .LP
 540 It can contain:
 541 .sp
 542 .ne 2
 543 .na
 544 \fBsender\fR
 545 .ad
 546 .sp .6
 547 .RS 4n
 548 The PID of the process which sent the signal. Use
 549 \fBct_pr_event_get_sender\fR(3CONTRACT) to obtain this information.
 550 .RE
 551 
 552 .SH FILES
 553 .sp
 554 .ne 2
 555 .na
 556 \fB\fB/usr/include/sys/contract/process.h\fR\fR
 557 .ad
 558 .sp .6
 559 .RS 4n
 560 Contains definitions of event-type macros.
 561 .RE
 562 
 563 .SH SEE ALSO
 564 .sp
 565 .LP
 566 \fBctrun\fR(1), \fBctstat\fR(1), \fBctwatch\fR(1), \fBcoreadm\fR(1M),
 567 \fBclose\fR(2), \fBfork\fR(2), \fBioctl\fR(2), \fBopen\fR(2), \fBpoll\fR(2),
 568 \fBct_pr_event_get_exitstatus\fR(3CONTRACT),
 569 \fBct_pr_event_get_gcorefile\fR(3CONTRACT),
 570 \fBct_pr_event_get_pcorefile\fR(3CONTRACT),
 571 \fBct_pr_event_get_pid\fR(3CONTRACT), \fBct_pr_event_get_ppid\fR(3CONTRACT),
 572 \fBct_pr_event_get_signal\fR(3CONTRACT),
 573 \fBct_pr_event_get_zcorefile\fR(3CONTRACT),
 574 \fBct_pr_status_get_contracts\fR(3CONTRACT),
 575 \fBct_pr_status_get_members\fR(3CONTRACT),
 576 \fBct_pr_status_get_param\fR(3CONTRACT), \fBct_pr_tmpl_set_fatal\fR(3CONTRACT),
 577 \fBct_pr_tmpl_set_param\fR(3CONTRACT),
 578 \fBct_pr_tmpl_set_transfer\fR(3CONTRACT), \fBct_tmpl_set_cookie\fR(3CONTRACT),
 579 \fBct_tmpl_set_critical\fR(3CONTRACT),
 580 \fBct_tmpl_set_informative\fR(3CONTRACT), \fBlibcontract\fR(3LIB),
 581 \fBcontract\fR(4), \fBprivileges\fR(5)