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