process(4) - osol9

1process(4)                       File Formats                       process(4)
2
3
4

NAME

6       process - process contract type
7

SYNOPSIS

9       /system/contract/process
10
11

DESCRIPTION

13       Process  contracts  allow processes to create a fault boundary around a
14       set of subprocesses and observe events which occur within  that  bound‐
15       ary.
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 /sys‐
20       tem/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 lim‐
102           ited 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 intersec‐
109           tion  of  the  contract  and  the  containing  process group if the
110           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 effec‐
120           tive set removes an event from the fatal event set which is present
121           in the critical event set, the corresponding event is automatically
122           removed from the critical event set and added  to  the  informative
123           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_NOORPHAN
147
148               If set, all processes in a process contract are sent SIGKILL if
149               the process contract is abandoned, either explicitly or because
150               the holder died and CT_PR_INHERIT was not  set.  The  scope  of
151               SIGKILL is limited to those processes which the contract author
152               or the event source could have normally sent signals to.
153
154               If this is not set and the process contract is  abandoned,  the
155               process contract is orphaned, that is, continues to exist with‐
156               out owner.
157
158
159           CT_PR_PGRPONLY
160
161               If set, only those processes within the same process group  and
162               process  contract  as  a  fatal  error-generating  process  are
163               killed.
164
165               If not set, all  processes  within  the  process  contract  are
166               killed if a member process encounters an error specified in the
167               fatal set.
168
169               If a user without the {PRIV_CONTRACT_EVENT}  privilege  in  its
170               effective  set  adds  CT_PR_PGRPONLY  to a template's parameter
171               set, any events other  than  CT_PR_EV_EMPTY  are  automatically
172               removed  from  the critical event set and added to the informa‐
173               tive event set.
174
175
176           CT_PR_REGENT
177
178               If set, the process contract can inherit unabandoned  contracts
179               left by exiting member processes.
180
181               If  not  set,  indicates  that  the process contract should not
182               inherit contracts from member processes.  If  a  process  exits
183               before  abandoning  a  contract  it  owns  and is a member of a
184               process contract which does not have CT_PR_REGENT set, the sys‐
185               tem automatically abandons the contract.
186
187               If  a  regent  process  contract has inherited contracts and is
188               abandoned by its owner, its inherited contracts are abandoned.
189
190
191
192       service FMRI
193
194           Specifies the service FMRI associated with  the  process  contract.
195           Use   ct_pr_tmpl_set_svc_fmri(3CONTRACT)  to  set  this  term.  The
196           default is to inherit the value from  the  creator's  process  con‐
197           tract.       When       this       term      is      uninitialized,
198           ct_pr_tmpl_get_svc_fmri(3CONTRACT) returns the token string  inher‐
199           ited: to indicate the value has not been set and is inherited. Set‐
200           ting the service FMRI to inherited: clears the current (B value and
201           the  term  is inherited from the creator's process contract. To set
202           this term a  process  must  have  {PRIV_CONTRACT_IDENTITY}  in  its
203           effective set.
204
205
206       transfer contract
207
208           Specifies  the  ID  of an empty process contract held by the caller
209           whose inherited process contracts are  to  be  transferred  to  the
210           newly  created  contract. Use ct_pr_tmpl_set_transfer(3CONTRACT) to
211           set the tranfer contract. Attempts to specify a contract  not  held
212           by  the calling process, or a contract which still has processes in
213           it, fail.
214
215           The default transfer term is 0, that is, no contract.
216
217
218   STATUS
219       In addition to the standard items, the status object read from a status
220       file descriptor contains the following items to obtain this information
221       respectively:
222
223       service contract ID
224
225           Specifies the process contract id which defined  the  service  FMRI
226           term.  Use  ct_pr_status_get_svc_ctid(3CONTRACT) to read the term's
227           value. It can be used to determine if the service FMRI  was  inher‐
228           ited as in the example below.
229
230             ctid_t ctid;           /* our contract id */
231             int fd;       /* fd of ctid's status file */
232
233             ct_stathdl_(Bt status;
234             ctid_t svc_ctid;
235
236             if (ct_status_read(fd, CTD_FIXED, &status) == 0) {
237                   if (ct_pr_status_get_svc_ctid(status, &svc_ctid) == 0) {
238                         if (svc_ctid == ctid)
239                             /* not inherited */
240                         else
241                             /* inherited */
242                   }
243                   ct_status_free(status);
244             }
245
246
247
248
249
250       If CTD_ALL is specified, the following items are also available:
251
252       Member list
253
254           The  PIDs  of  processes which are members of the process contract.
255           Use ct_pr_status_get_members(3CONTRACT) for this information.
256
257
258       Inherited contract list
259
260           The IDs of contracts which have been inherited by the process  con‐
261           tract.  Use  ct_pr_status_get_contracts(3CONTRACT)  to  obtain this
262           information.
263
264
265       Service FMRI (term)
266
267           Values equal to the terms used when the contract was  written.  The
268           Service FMRI term of the process contract of a process en(Btering a
269           zone has  the value svc:/system/zone_enter:default when  read  from
270           the non-global zone.
271
272
273       contract creator
274
275           Specifies  the  process  that  created  the  process  contract. Use
276           ct_pr_status_get_svc_creator(3CONTRACT) to read the term's value.
277
278
279       creator's aux (term)
280
281           Values equal to the terms used when the contract was written.
282
283
284
285       The following standard status items have  different  meanings  in  some
286       situations:
287
288       Ownership state
289
290           If  the  process contract has a state of CTS_OWNED or CTS_INHERITED
291           and is held by an entity in the global zone, but contains processes
292           in  a  non-global zone, it appears to have the state CTS_OWNED when
293           observed by processes in the non-global zone.
294
295
296       Contract holder
297
298           If the process contract has a state of CTS_OWNED  or  CTS_INHERITED
299           and is held by an entity in the global zone, but contains processes
300           in a non-global zone, it appears  to  be  held  by  the  non-global
301           zone's zsched when observed by processes in the non-global zone.
302
303
304   EVENTS
305       In addition to the standard items, an event generated by a process con‐
306       tract contains the following information:
307
308       Generating PID
309
310           The process ID of the member process which experienced  the  event,
311           or  caused  the  contract  event  to  be  generated (in the case of
312           CT_PR_EV_EMPTY). Use ct_pr_event_get_pid(3CONTRACT) to obtain  this
313           information.
314
315
316
317       If the event type is CT_PR_EV_FORK, the event contains:
318
319       Parent PID
320
321           The    process    ID    which    forked   [Generating   PID].   Use
322           ct_pr_event_get_ppid(3CONTRACT) to obtain this information.
323
324
325
326       If the event type is CT_PR_EV_EXIT, the event contains:
327
328       Exit status
329
330           The  exit  status  of  the  process.  Use  ct_pr_event_get_exitsta‐
331           tus(3CONTRACT) to obtain this information.
332
333
334
335       If the event type is CT_PR_EV_CORE, the event can contain:
336
337       Process core name
338
339           The  name  of the per-process core file. Use ct_pr_event_get_pcore‐
340           file(3CONTRACT) to obtain this information.
341
342
343       Global core name
344
345           The  name  of  the  process's  zone's   global   core   file.   Use
346           ct_pr_event_get_gcorefile(3CONTRACT) to obtain this information.
347
348
349       Zone core name
350
351           The  name  of  the  system-wide  core  file in the global zone. Use
352           ct_pr_event_get_zcorefile(3CONTRACT) to obtain this information.
353
354
355
356       See coreadm(1M) for more information  about  per-process,  global,  and
357       system-wide core files.
358
359
360       If the event type is CT_PR_EV_SIGNAL, the event contains:
361
362       Signal
363
364           The   number   of   the   signal  which  killed  the  process.  Use
365           ct_pr_event_get_signal(3CONTRACT) to obtain this information.
366
367
368
369       It can contain:
370
371       sender
372
373           The   PID   of   the   process   which   sent   the   signal.   Use
374           ct_pr_event_get_sender(3CONTRACT) to obtain this information.
375
376

FILES

378       /usr/include/sys/contract/process.h
379
380           Contains definitions of event-type macros.
381
382

NAME

SYNOPSIS

DESCRIPTION

FILES

SEE ALSO