File Formats process(4)
NAME
process - process contract type
SYNOPSIS
/system/contract/process
DESCRIPTION
Process contracts allow processes to create a fault boundary
around a set of subprocesses and observe events which occur
within that boundary.
Process contracts are managed using the contract(4) file
system and the libcontract(3LIB) library. The process con-
tract type directory is /system/contract/process.
CREATION
A process contract is created when an LWP that has an active
process contract template calls fork(2). Initially, the
child process created by fork() is the only resource managed
by the contract. When an LWP that does not have an active
process contract template calls fork(), the child process
created by fork() is added as a resource to the process con-
tract of which the parent was a member.
EVENT TYPES
The following events types are defined:
CTPREVEMPTY
The last member of the process contract exited.
CTPREVFORK
A new process has been added to the process contract.
CTPREVEXIT
A member of the process contract exited.
CTPREVCORE
A process failed and dumped core. This could also occur
if the process would have dumped core had appropriate
coreadm(1M) options been enabled and core file size was
unlimited.
SunOS 5.11 Last change: 25 Mar 2008 1
File Formats process(4)
CTPREVSIGNAL
A process received a fatal signal from a process, other
than the owner of the process contract, that is a member
of a different process contract.
CTPREVHWER
A process was killed because of an uncorrectable
hardware error.
TERMS
The following common contract terms, defined in contract(4),
have process-contract specific attributes:
critical event set
The default value for the critical event set is
(CTPREVEMPTY CTPREVHWER).
An attempt by a user without the {PRIVCONTRACTEVENT}
privilege in its effective set to add an event, other
than CTPREVEMPTY, to the critical event set which is
not present in the fatal set, or if the CTPRPGONLY
parameter is set and the same user attempts to add any
event, other than CTPREVEMPTY, to the critical event
set, fails.
informative event set
The default value for the informative event set is
(CTPREVCORE CTPREVSIGNAL).
The following contract terms can be read from or written to
a process contract template using the named
libcontract(3LIB) interfaces. These contract terms are in
addition to those described in contract(4).
creator's aux
Auxiliary contract description. The purpose of this
field is to provide the contract creator with a way to
differentiate process contracts it creates under the
same service FMRI. Use ctprtmplsetsvcaux(3CONTRACT)
to set this term. The default value is an empty string.
The contents of this field should be limited to 7-bit
ASCI values.
SunOS 5.11 Last change: 25 Mar 2008 2
File Formats process(4)
fatal event set
Defines a set of events which, when generated, causes
all members of the process contract to be killed with
SIGKIL, or the intersection of the contract and the
containing process group if the CTPRPGRPONLY parameter
is set. Set this term with
ctprtmplsetfatal(3CONTRACT). The fatal event set is
restricted to CTPREVCORE, CTPREVSIGNAL, and
CTPREVHWER. For CTPREVCORE and CTPREVSIGNAL
events, the scope of SIGKIL is limited to those
processes which the contract author or the event source
could have normally sent signals to.
The default value for the fatal event set is
CTPREVHWER.
If a user without the {PRIVCONTRACTEVENT} privilege in
its effective set removes an event from the fatal event
set which is present in the critical event set, the
corresponding event is automatically removed from the
critical event set and added to the informative event
set.
parameter set
Defines miscellaneous other settings. Use
ctprtmplsetparam(3CONTRACT) to set this term.
The default parameter set is empty.
The value is a bit vector comprised of some or all of:
CTPRINHERIT
If set, indicates that the process contract is to be
inherited by the process contract the contract owner
is a member of if the contract owner exits before
explicitly abandoning the process contract.
If not set, the process contract is automatically
abandoned when the owner exits.
CTPRNORPHAN
If set, all processes in a process contract are sent
SIGKIL if the process contract is abandoned, either
explicitly or because the holder died and
CTPRINHERIT was not set. The scope of SIGKIL is
limited to those processes which the contract author
SunOS 5.11 Last change: 25 Mar 2008 3
File Formats process(4)
or the event source could have normally sent signals
to.
If this is not set and the process contract is aban-
doned, the process contract is orphaned, that is,
continues to exist without owner.
CTPRPGRPONLY
If set, only those processes within the same process
group and process contract as a fatal error-
generating process are killed.
If not set, all processes within the process con-
tract are killed if a member process encounters an
error specified in the fatal set.
If a user without the {PRIVCONTRACTEVENT}
privilege in its effective set adds CTPRPGRPONLY
to a template's parameter set, any events other than
CTPREVEMPTY are automatically removed from the
critical event set and added to the informative
event set.
CTPREGENT
If set, the process contract can inherit unabandoned
contracts left by exiting member processes.
If not set, indicates that the process contract
should not inherit contracts from member processes.
If a process exits before abandoning a contract it
owns and is a member of a process contract which
does not have CTPREGENT set, the system automati-
cally abandons the contract.
If a regent process contract has inherited contracts
and is abandoned by its owner, its inherited con-
tracts are abandoned.
service FMRI
Specifies the service FMRI associated with the process
contract. Use ctprtmplsetsvcfmri(3CONTRACT) to set
this term. The default is to inherit the value from the
creator's process contract. When this term is uninitial-
ized, ctprtmplgetsvcfmri(3CONTRACT) returns the
token string inherited: to indicate the value has not
SunOS 5.11 Last change: 25 Mar 2008 4
File Formats process(4)
been set and is inherited. Setting the service FMRI to
inherited: clears the current (B value and the term is
inherited from the creator's process contract. To set
this term a process must have {PRIVCONTRACTIDENTITY}
in its effective set.
transfer contract
Specifies the ID of an empty process contract held by
the caller whose inherited process contracts are to be
transferred to the newly created contract. Use
ctprtmplsettransfer(3CONTRACT) to set the tranfer
contract. Attempts to specify a contract not held by the
calling process, or a contract which still has processes
in it, fail.
The default transfer term is 0, that is, no contract.
STATUS
In addition to the standard items, the status object read
from a status file descriptor contains the following items
to obtain this information respectively:
service contract ID
Specifies the process contract id which defined the ser-
vice FMRI term. Use ctprstatusgetsvcctid(3CONTRACT)
to read the term's value. It can be used to determine if
the service FMRI was inherited as in the example below.
ctidt ctid; /* our contract id */
int fd; /* fd of ctid's status file */
ctstathdl(Bt status;
ctidt svcctid;
if (ctstatusread(fd, CTDFIXED, &status) == 0) {
if (ctprstatusgetsvcctid(status, &svcctid) == 0) {
if (svcctid == ctid)
/* not inherited */
else
/* inherited */
}
ctstatusfree(status);
}
SunOS 5.11 Last change: 25 Mar 2008 5
File Formats process(4)
If CTDAL is specified, the following items are also avail-
able:
Member list
The PIDs of processes which are members of the process
contract. Use ctprstatusgetmembers(3CONTRACT) for
this information.
Inherited contract list
The IDs of contracts which have been inherited by the
process contract. Use
ctprstatusgetcontracts(3CONTRACT) to obtain this
information.
Service FMRI (term)
Values equal to the terms used when the contract was
written. The Service FMRI term of the process contract
of a process en(Btering a zone has the value
svc:/system/zoneenter:default when read from the non-
global zone.
contract creator
Specifies the process that created the process contract.
Use ctprstatusgetsvccreator(3CONTRACT) to read the
term's value.
creator's aux (term)
Values equal to the terms used when the contract was
written.
The following standard status items have different meanings
in some situations:
Ownership state
If the process contract has a state of CTSOWNED or
CTSINHERITED and is held by an entity in the global
zone, but contains processes in a non-global zone, it
appears to have the state CTSOWNED when observed by
processes in the non-global zone.
SunOS 5.11 Last change: 25 Mar 2008 6
File Formats process(4)
Contract holder
If the process contract has a state of CTSOWNED or
CTSINHERITED and is held by an entity in the global
zone, but contains processes in a non-global zone, it
appears to be held by the non-global zone's zsched when
observed by processes in the non-global zone.
EVENTS
In addition to the standard items, an event generated by a
process contract contains the following information:
Generating PID
The process ID of the member process which experienced
the event, or caused the contract event to be generated
(in the case of CTPREVEMPTY). Use
ctpreventgetpid(3CONTRACT) to obtain this informa-
tion.
If the event type is CTPREVFORK, the event contains:
Parent PID
The process ID which forked [Generating PID]. Use
ctpreventgetppid(3CONTRACT) to obtain this informa-
tion.
If the event type is CTPREVEXIT, the event contains:
Exit status
The exit status of the process. Use
ctpreventgetexitstatus(3CONTRACT) to obtain this
information.
If the event type is CTPREVCORE, the event can contain:
Process core name
The name of the per-process core file. Use
ctpreventgetpcorefile(3CONTRACT) to obtain this
information.
SunOS 5.11 Last change: 25 Mar 2008 7
File Formats process(4)
Global core name
The name of the process's zone's global core file. Use
ctpreventgetgcorefile(3CONTRACT) to obtain this
information.
Zone core name
The name of the system-wide core file in the global
zone. Use ctpreventgetzcorefile(3CONTRACT) to obtain
this information.
See coreadm(1M) for more information about per-process, glo-
bal, and system-wide core files.
If the event type is CTPREVSIGNAL, the event contains:
Signal
The number of the signal which killed the process. Use
ctpreventgetsignal(3CONTRACT) to obtain this infor-
mation.
It can contain:
sender
The PID of the process which sent the signal. Use
ctpreventgetsender(3CONTRACT) to obtain this infor-
mation.
FILES
/usr/include/sys/contract/process.h
Contains definitions of event-type macros.
SEE ALSO
ctrun(1), ctstat(1), ctwatch(1), coreadm(1M), close(2),
fork(2), ioctl(2), open(2), poll(2),
ctpreventgetexitstatus(3CONTRACT),
ctpreventgetgcorefile(3CONTRACT),
ctpreventgetpcorefile(3CONTRACT),
ctpreventgetpid(3CONTRACT),
ctpreventgetppid(3CONTRACT),
SunOS 5.11 Last change: 25 Mar 2008 8
File Formats process(4)
ctpreventgetsignal(3CONTRACT),
ctpreventgetzcorefile(3CONTRACT),
ctprstatusgetcontracts(3CONTRACT),
ctprstatusgetmembers(3CONTRACT),
ctprstatusgetparam(3CONTRACT),
ctprtmplsetfatal(3CONTRACT),
ctprtmplsetparam(3CONTRACT),
ctprtmplsettransfer(3CONTRACT),
cttmplsetcookie(3CONTRACT),
cttmplsetcritical(3CONTRACT),
cttmplsetinformative(3CONTRACT), libcontract(3LIB), con-
tract(4), privileges(5)
SunOS 5.11 Last change: 25 Mar 2008 9
|
