unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

process(4)                       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  bound-
       ary.

       Process contracts are managed using the contract(4) file system and the
       libcontract(3LIB) library. The process contract type directory is /sys-
       tem/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 contract of which the parent was a member.

   EVENT TYPES
       The following events types are defined:

       CT_PR_EV_EMPTY

           The last member of the process contract exited.



       CT_PR_EV_FORK

           A new process has been added to the process contract.



       CT_PR_EV_EXIT

           A member of the process contract exited.



       CT_PR_EV_CORE

           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.



       CT_PR_EV_SIGNAL

           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.



       CT_PR_EV_HWERR

           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:

       informative event set

           The default value for the informative event set is (CT_PR_EV_CORE |
           CT_PR_EV_SIGNAL).



       critical event set

           The default value for the critical event set is  (CT_PR_EV_EMPTY  |
           CT_PR_EV_HWERR).

           An attempt by a user without the {PRIV_CONTRACT_EVENT} privilege in
           its effective set to add an event, other  than  CT_PR_EV_EMPTY,  to
           the critical event set which is not present in the fatal set, or if
           the CT_PR_PGONLY parameter is set and the same user attempts to add
           any  event,  other  than CT_PR_EV_EMPTY, to the critical event set,
           fails.



       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).

       fatal event set

           Defines a set of events which, when generated, causes  all  members
           of the process contract to be killed with SIGKILL, or the intersec-
           tion of the contract  and  the  containing  process  group  if  the
           CT_PR_PGRPONLY    parameter    is   set.   Set   this   term   with
           ct_pr_tmpl_set_fatal(3CONTRACT). The fatal event set is  restricted
           to   CT_PR_EV_CORE,   CT_PR_EV_SIGNAL,   and   CT_PR_EV_HWERR.  For
           CT_PR_EV_CORE and CT_PR_EV_SIGNAL events, the scope of  SIGKILL  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 CT_PR_EV_HWERR.

           If a user without the {PRIV_CONTRACT_EVENT} privilege in its effec-
           tive 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
           ct_pr_tmpl_set_param(3CONTRACT) to set this term.

           The default parameter set is empty.

           The value is a bit vector comprised of some or all of:


           CT_PR_INHERIT

               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.




           CT_PR_NOORPHAN

               If set, all processes in a process contract are sent SIGKILL if
               the process contract is abandoned, either explicitly or because
               the  holder  died  and  CT_PR_INHERIT was not set. The scope of
               SIGKILL is limited to those processes which the contract author
               or the event source could have normally sent signals to.

               If  this  is not set and the process contract is abandoned, the
               process contract is orphaned, that is, continues to exist with-
               out owner.



           CT_PR_PGRPONLY

                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 contract are
               killed if a member process encounters an error specified in the
               fatal set.

               If  a  user  without the {PRIV_CONTRACT_EVENT} privilege in its
               effective set adds CT_PR_PGRPONLY  to  a  template's  parameter
               set,  any  events  other  than CT_PR_EV_EMPTY are automatically
               removed from the critical event set and added to  the  informa-
               tive event set.



           CT_PR_REGENT

               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 CT_PR_REGENT set, the sys-
               tem automatically abandons the contract.

               If a regent process contract has  inherited  contracts  and  is
               abandoned by its owner, its inherited contracts are abandoned.



       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 ct_pr_tmpl_set_transfer(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 if CTD_FIXED is specified:

       Fatal event set (term)
       Parameter set (term)

           Values equal to the terms used when the contract was written. Use


           ct_pr_status_get_fatal(3contract)
            ct_pr_status_get_param(3contract)

           to obtain this information. respectively.




       If CTD_ALL is specified, the following items are also available:

       Member list

           The  PIDs  of  processes which are members of the process contract.
           Use ct_pr_status_get_members(3CONTRACT) to obtain this information.



       Inherited contract list

           The IDs of contracts which have been inherited by the process  con-
           tract.  Use  ct_pr_status_get_contracts(3CONTRACT)  to  obtain this
           information.



       The following standard status items have  different  meanings  in  some
       situations:

       Ownership state

            If  the process contract has a state of CTS_OWNED or CTS_INHERITED
           and is held by an entity in the global zone, but contains processes
           in  a  non-global zone, it appears to have the state CTS_OWNED when
           observed by processes in the non-global zone.



       Contract holder

            If the process contract has a state of CTS_OWNED or  CTS_INHERITED
           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 con-
       tract 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
           CT_PR_EV_EMPTY). Use ct_pr_event_get_pid(3CONTRACT) to obtain  this
           information.



       If the event type is CT_PR_EV_FORK, the event contains:

       Parent PID

           The    process    ID    which    forked   [Generating   PID].   Use
           ct_pr_event_get_ppid(3CONTRACT) to obtain this information.



       If the event type is CT_PR_EV_EXIT, the event contains:

       Exit status

            The exit  status  of  the  process.  Use  ct_pr_event_get_exitsta-
           tus(3CONTRACT) to obtain this information.



       If the event type is CT_PR_EV_CORE, the event can contain:

       Process core name

           The  name  of the per-process core file. Use ct_pr_event_get_pcore-
           file(3CONTRACT) to obtain this information.



       Global core name

            The  name  of  the  process's  zone's  global   core   file.   Use
           ct_pr_event_get_gcorefile(3CONTRACT) to obtain this information.



       Zone core name

           The  name  of  the  system-wide  core  file in the global zone. Use
           ct_pr_event_get_zcorefile(3contract) to obtain this information.



       See coreadm(1M) for more information  about  per-process,  global,  and
       system-wide core files.

       If the event type is CT_PR_EV_SIGNAL, the event contains:

       Signal

           The   number   of   the   signal  which  killed  the  process.  Use
           ct_pr_event_get_signal(3CONTRACT) to obtain this information.



       It can contain:

       sender

           The   PID   of   the   process   which   sent   the   signal.   Use
           ct_pr_event_get_sender(3CONTRACT) to obtain this information.



SEE ALSO
       ctrun(1),   ctstat(1),   ctwatch(1),  coreadm(1M),  close(2),  fork(2),
       ioctl(2),  open(2),   poll(2),   ct_pr_event_get_exitstatus(3CONTRACT),
       ct_pr_event_get_gcorefile(3CONTRACT),   ct_pr_event_get_pcorefile(3CON-
       TRACT),   ct_pr_event_get_pid(3CONTRACT),    ct_pr_event_get_ppid(3CON-
       TRACT),     ct_pr_event_get_signal(3CONTRACT),    ct_pr_status_get_con-
       tracts(3CONTRACT),                 ct_pr_status_get_members(3CONTRACT),
       ct_pr_tmpl_set_fatal(3CONTRACT),       ct_pr_tmpl_set_param(3CONTRACT),
       ct_pr_tmpl_set_transfer(3CONTRACT),      ct_tmpl_set_cookie(3CONTRACT),
       ct_tmpl_set_critical(3CONTRACT),    ct_tmpl_set_informative(3CONTRACT),
       libcontract(3LIB), contract(4), privileges(5)



SunOS 5.10                        20 Jul 2004                       process(4)