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