1 PROCESS(4) File Formats and Configurations PROCESS(4)
2
3
4
5 NAME
6 process - process contract type
7
8 SYNOPSIS
9 /system/contract/process
10
11
12 DESCRIPTION
13 Process contracts allow processes to create a fault boundary around a
14 set of subprocesses and observe events which occur within that
15 boundary.
16
17
18 Process contracts are managed using the contract(4) file system and the
19 libcontract(3LIB) library. The process contract type directory is
20 /system/contract/process.
21
22 CREATION
23 A process contract is created when an LWP that has an active process
24 contract template calls fork(2). Initially, the child process created
25 by fork() is the only resource managed by the contract. When an LWP
26 that does not have an active process contract template calls fork(),
27 the child process created by fork() is added as a resource to the
28 process contract of which the parent was a member.
29
30 EVENT TYPES
31 The following events types are defined:
32
33 CT_PR_EV_EMPTY
34
35 The last member of the process contract exited.
36
37
38 CT_PR_EV_FORK
39
40 A new process has been added to the process contract.
41
42
43 CT_PR_EV_EXIT
44
45 A member of the process contract exited.
46
47
48 CT_PR_EV_CORE
49
50 A process failed and dumped core. This could also occur if the
51 process would have dumped core had appropriate coreadm(1M) options
52 been enabled and core file size was unlimited.
53
54
55 CT_PR_EV_SIGNAL
56
57 A process received a fatal signal from a process, other than the
58 owner of the process contract, that is a member of a different
59 process contract.
60
61
62 CT_PR_EV_HWERR
63
64 A process was killed because of an uncorrectable hardware error.
65
66
67 TERMS
68 The following common contract terms, defined in contract(4), have
69 process-contract specific attributes:
70
71 critical event set
72
73 The default value for the critical event set is (CT_PR_EV_EMPTY |
74 CT_PR_EV_HWERR).
75
76 An attempt by a user without the {PRIV_CONTRACT_EVENT} privilege in
77 its effective set to add an event, other than CT_PR_EV_EMPTY, to
78 the critical event set which is not present in the fatal set, or if
79 the CT_PR_PGONLY parameter is set and the same user attempts to add
80 any event, other than CT_PR_EV_EMPTY, to the critical event set,
81 fails.
82
83
84 informative event set
85
86 The default value for the informative event set is (CT_PR_EV_CORE |
87 CT_PR_EV_SIGNAL).
88
89
90
91 The following contract terms can be read from or written to a process
92 contract template using the named libcontract(3LIB) interfaces. These
93 contract terms are in addition to those described in contract(4).
94
95 creator's aux
96
97 Auxiliary contract description. The purpose of this field is to
98 provide the contract creator with a way to differentiate process
99 contracts it creates under the same service FMRI. Use
100 ct_pr_tmpl_set_svc_aux(3CONTRACT) to set this term. The default
101 value is an empty string. The contents of this field should be
102 limited to 7-bit ASCII values.
103
104
105 fatal event set
106
107 Defines a set of events which, when generated, causes all members
108 of the process contract to be killed with SIGKILL, or the
109 intersection of the contract and the containing process group if
110 the CT_PR_PGRPONLY parameter is set. Set this term with
111 ct_pr_tmpl_set_fatal(3CONTRACT). The fatal event set is restricted
112 to CT_PR_EV_CORE, CT_PR_EV_SIGNAL, and CT_PR_EV_HWERR. For
113 CT_PR_EV_CORE and CT_PR_EV_SIGNAL events, the scope of SIGKILL is
114 limited to those processes which the contract author or the event
115 source could have normally sent signals to.
116
117 The default value for the fatal event set is CT_PR_EV_HWERR.
118
119 If a user without the {PRIV_CONTRACT_EVENT} privilege in its
120 effective set removes an event from the fatal event set which is
121 present in the critical event set, the corresponding event is
122 automatically removed from the critical event set and added to the
123 informative event set.
124
125
126 parameter set
127
128 Defines miscellaneous other settings. Use
129 ct_pr_tmpl_set_param(3CONTRACT) to set this term.
130
131 The default parameter set is empty.
132
133 The value is a bit vector comprised of some or all of:
134
135 CT_PR_INHERIT
136
137 If set, indicates that the process contract is to be inherited
138 by the process contract the contract owner is a member of if
139 the contract owner exits before explicitly abandoning the
140 process contract.
141
142 If not set, the process contract is automatically abandoned
143 when the owner exits.
144
145
146 CT_PR_KEEP_EXEC
147
148 If set, the process contract template remains active across
149 exec(2). This can be used to setup a contract for children of
150 an application which is not contract-aware. If this is not set
151 then the system clears the active template when the process
152 execs. Because this option is intended for an application which
153 is not contract-aware, new child process contracts will be
154 automatically abandoned by the parent.
155
156
157 CT_PR_NOORPHAN
158
159 If set, all processes in a process contract are sent SIGKILL if
160 the process contract is abandoned, either explicitly or because
161 the holder died and CT_PR_INHERIT was not set. The scope of
162 SIGKILL is limited to those processes which the contract author
163 or the event source could have normally sent signals to.
164
165 If this is not set and the process contract is abandoned, the
166 process contract is orphaned, that is, continues to exist
167 without owner.
168
169
170 CT_PR_PGRPONLY
171
172 If set, only those processes within the same process group and
173 process contract as a fatal error-generating process are
174 killed.
175
176 If not set, all processes within the process contract are
177 killed if a member process encounters an error specified in the
178 fatal set.
179
180 If a user without the {PRIV_CONTRACT_EVENT} privilege in its
181 effective set adds CT_PR_PGRPONLY to a template's parameter
182 set, any events other than CT_PR_EV_EMPTY are automatically
183 removed from the critical event set and added to the
184 informative event set.
185
186
187 CT_PR_REGENT
188
189 If set, the process contract can inherit unabandoned contracts
190 left by exiting member processes.
191
192 If not set, indicates that the process contract should not
193 inherit contracts from member processes. If a process exits
194 before abandoning a contract it owns and is a member of a
195 process contract which does not have CT_PR_REGENT set, the
196 system automatically abandons the contract.
197
198 If a regent process contract has inherited contracts and is
199 abandoned by its owner, its inherited contracts are abandoned.
200
201
202
203 service FMRI
204
205 Specifies the service FMRI associated with the process contract.
206 Use ct_pr_tmpl_set_svc_fmri(3CONTRACT) to set this term. The
207 default is to inherit the value from the creator's process
208 contract. When this term is uninitialized,
209 ct_pr_tmpl_get_svc_fmri(3CONTRACT) returns the token string
210 inherited: to indicate the value has not been set and is inherited.
211 Setting the service FMRI to inherited: clears the current (B value
212 and the term is inherited from the creator's process contract. To
213 set this term a process must have {PRIV_CONTRACT_IDENTITY} in its
214 effective set.
215
216
217 transfer contract
218
219 Specifies the ID of an empty process contract held by the caller
220 whose inherited process contracts are to be transferred to the
221 newly created contract. Use ct_pr_tmpl_set_transfer(3CONTRACT) to
222 set the tranfer contract. Attempts to specify a contract not held
223 by the calling process, or a contract which still has processes in
224 it, fail.
225
226 The default transfer term is 0, that is, no contract.
227
228
229 STATUS
230 In addition to the standard items, the status object read from a status
231 file descriptor contains the following items to obtain this information
232 respectively:
233
234 service contract ID
235
236 Specifies the process contract id which defined the service FMRI
237 term. Use ct_pr_status_get_svc_ctid(3CONTRACT) to read the term's
238 value. It can be used to determine if the service FMRI was
239 inherited as in the example below.
240
241 ctid_t ctid; /* our contract id */
242 int fd; /* fd of ctid's status file */
243
244 ct_stathdl_(Bt status;
245 ctid_t svc_ctid;
246
247 if (ct_status_read(fd, CTD_FIXED, &status) == 0) {
248 if (ct_pr_status_get_svc_ctid(status, &svc_ctid) == 0) {
249 if (svc_ctid == ctid)
250 /* not inherited */
251 else
252 /* inherited */
253 }
254 ct_status_free(status);
255 }
256
257
258
259
260
261 If CTD_ALL is specified, the following items are also available:
262
263 Member list
264
265 The PIDs of processes which are members of the process contract.
266 Use ct_pr_status_get_members(3CONTRACT) for this information.
267
268
269 Inherited contract list
270
271 The IDs of contracts which have been inherited by the process
272 contract. Use ct_pr_status_get_contracts(3CONTRACT) to obtain this
273 information.
274
275
276 Service FMRI (term)
277
278 Values equal to the terms used when the contract was written. The
279 Service FMRI term of the process contract of a process en(Btering a
280 zone has the value svc:/system/zone_enter:default when read from
281 the non-global zone.
282
283
284 contract creator
285
286 Specifies the process that created the process contract. Use
287 ct_pr_status_get_svc_creator(3CONTRACT) to read the term's value.
288
289
290 creator's aux (term)
291
292 Values equal to the terms used when the contract was written.
293
294
295
296 The following standard status items have different meanings in some
297 situations:
298
299 Ownership state
300
301 If the process contract has a state of CTS_OWNED or CTS_INHERITED
302 and is held by an entity in the global zone, but contains processes
303 in a non-global zone, it appears to have the state CTS_OWNED when
304 observed by processes in the non-global zone.
305
306
307 Contract holder
308
309 If the process contract has a state of CTS_OWNED or CTS_INHERITED
310 and is held by an entity in the global zone, but contains processes
311 in a non-global zone, it appears to be held by the non-global
312 zone's zsched when observed by processes in the non-global zone.
313
314
315 EVENTS
316 In addition to the standard items, an event generated by a process
317 contract contains the following information:
318
319 Generating PID
320
321 The process ID of the member process which experienced the event,
322 or caused the contract event to be generated (in the case of
323 CT_PR_EV_EMPTY). Use ct_pr_event_get_pid(3CONTRACT) to obtain this
324 information.
325
326
327
328 If the event type is CT_PR_EV_FORK, the event contains:
329
330 Parent PID
331
332 The process ID which forked [Generating PID]. Use
333 ct_pr_event_get_ppid(3CONTRACT) to obtain this information.
334
335
336
337 If the event type is CT_PR_EV_EXIT, the event contains:
338
339 Exit status
340
341 The exit status of the process. Use
342 ct_pr_event_get_exitstatus(3CONTRACT) to obtain this information.
343
344
345
346 If the event type is CT_PR_EV_CORE, the event can contain:
347
348 Process core name
349
350 The name of the per-process core file. Use
351 ct_pr_event_get_pcorefile(3CONTRACT) to obtain this information.
352
353
354 Global core name
355
356 The name of the process's zone's global core file. Use
357 ct_pr_event_get_gcorefile(3CONTRACT) to obtain this information.
358
359
360 Zone core name
361
362 The name of the system-wide core file in the global zone. Use
363 ct_pr_event_get_zcorefile(3CONTRACT) to obtain this information.
364
365
366
367 See coreadm(1M) for more information about per-process, global, and
368 system-wide core files.
369
370
371 If the event type is CT_PR_EV_SIGNAL, the event contains:
372
373 Signal
374
375 The number of the signal which killed the process. Use
376 ct_pr_event_get_signal(3CONTRACT) to obtain this information.
377
378
379
380 It can contain:
381
382 sender
383
384 The PID of the process which sent the signal. Use
385 ct_pr_event_get_sender(3CONTRACT) to obtain this information.
386
387
388 FILES
389 /usr/include/sys/contract/process.h
390
391 Contains definitions of event-type macros.
392
393
394 SEE ALSO
395 ctrun(1), ctstat(1), ctwatch(1), coreadm(1M), close(2), fork(2),
396 ioctl(2), open(2), poll(2), ct_pr_event_get_exitstatus(3CONTRACT),
397 ct_pr_event_get_gcorefile(3CONTRACT),
398 ct_pr_event_get_pcorefile(3CONTRACT), ct_pr_event_get_pid(3CONTRACT),
399 ct_pr_event_get_ppid(3CONTRACT), ct_pr_event_get_signal(3CONTRACT),
400 ct_pr_event_get_zcorefile(3CONTRACT),
401 ct_pr_status_get_contracts(3CONTRACT),
402 ct_pr_status_get_members(3CONTRACT), ct_pr_status_get_param(3CONTRACT),
403 ct_pr_tmpl_set_fatal(3CONTRACT), ct_pr_tmpl_set_param(3CONTRACT),
404 ct_pr_tmpl_set_transfer(3CONTRACT), ct_tmpl_set_cookie(3CONTRACT),
405 ct_tmpl_set_critical(3CONTRACT), ct_tmpl_set_informative(3CONTRACT),
406 libcontract(3LIB), contract(4), privileges(5)
407
408
409
410 Sept 6, 2016 PROCESS(4)