Manual Pages for UNIX Operating System command usage for man ctrun

User Commands                                            ctrun(1)



NAME
     ctrun - execute command in a process contract

SYNOPSIS
     /usr/bin/ctrun [options] command [ argument]...


DESCRIPTION
     The ctrun utility starts a command in a newly  created  pro-
     cess   contract.   ctrun  holds  the  contract  and  can  be
     instructed to output or respond to events that occur  within
     the contract.


     For additional information about process contracts, see con-
     tract(4) and process(4).

OPTIONS
     The following options are supported:

     -A aux                    Sets    the    process    contract
                               creator's auxiliary field.


     -i event,[event ...]      Sets  the  informative  and  fatal
     -f event,[event ...]      events, respectively.

                               The following are valid events:

                               core      A member process  dumped
                                         core.

                                         core events are informa-
                                         tive by default.


                               empty     The last member  of  the
                                         process contract exited.


                               exit      A member process exited.


                               fork      A process was  added  to
                                         the process contract.


                               hwerr     A member process encoun-
                                         tered a hardware error.

                                         hwerr events  are  fatal
                                         by default.



SunOS 5.11          Last change: 22 Mar 2010                    1






User Commands                                            ctrun(1)



                               signal    A     member     process
                                         received  a fatal signal
                                         from a process in a dif-
                                         ferent process contract.

                               Only  core,  hwerr,   and   signal
                               events can be made fatal.

                               More events can be delivered  than
                               requested  if  ctrun requires them
                               for its own purposes. For example,
                               empty    messages    are    always
                               requested if a  lifetime  of  con-
                               tract is specified. See -l.


     -F fmri                   Sets the process contract  service
                               FMRI  field. To set this field the
                               caller is  required  to  have  the
                               {PRIV_CONTRACT_IDENTITY}   in  its
                               effective set.


     -l lifetime               The   following   valid   lifetime
                               values are supported:

                               child       ctrun exits  when  the
                                           command exits, regard-
                                           less  of  whether  the
                                           contract is empty.


                               contract    ctrun exits only  when
                                           the   contract  exits.
                                           This is the default.


                               none        ctrun  exits   immedi-
                                           ately,  orphaning  the
                                           contract.



     -o option,[option ...]    The  following  options  are  sup-
                               ported:

                               noorphan    Kills all processes in
                                           the  contract  if  the
                                           holder (ctrun) exits.

                                           This option is invalid
                                           when   a  lifetime  of



SunOS 5.11          Last change: 22 Mar 2010                    2






User Commands                                            ctrun(1)



                                           none is specified.


                               pgrponly    If   a   fatal   error
                                           occurs,  kills at most
                                           the process  group  of
                                           which  the errant pro-
                                           cess is a member.


                               regent      The contract  inherits
                                           inheritable  contracts
                                           when   abandoned    by
                                           member processes.



     -r count                  If  the  contract   encounters   a
                               fault,  this  option  attempts  to
                               restart the command  count  times.
                               If count is 0, the attempt to res-
                               tart  continues  indefinitely.  By
                               default, ctrun does not attempt to
                               restart the command.

                               This option is invalid if a  life-
                               time other than contract is speci-
                               fied or if the pgrponly option  is
                               used.


     -t                        If the contract created  by  ctrun
                               inherited  subcontracts  from  its
                               member  processes,   attempts   to
                               transfer  them to the new contract
                               when restarting.

                               This option is invalid  unless  -r
                               is also specified.


     -v                        Displays contract events and ctrun
                               actions as they occur.


     -V                        Displays verbose contract  events,
                               as  are displayed by the -v option
                               of ctwatch. Implies -v.


OPERANDS




SunOS 5.11          Last change: 22 Mar 2010                    3






User Commands                                            ctrun(1)



     The following operands are supported:

     argument    One of the strings treated  as  an  argument  to
                 command.


     command     The command  to  be  passed  to  execvp(2).  See
                 exec(2).


EXAMPLES
     Example 1 Running a Shell in a New Process Contract


     The following example runs a shell in  a  new  process  con-
     tract:


       example% ctrun -l child -o pgrponly ksh




     The -l child option argument  is  specified  so  that  ctrun
     won't  wait  until all children of the shell have exited. -o
     pgrponly is specified because an interactive ksh  puts  each
     job  in  a  new  process  group,  and an error in one job is
     unlikely to affect the others.


     Example 2 Running a Simple Server


     The following example runs a simple server:


       example% ctrun -r 0 -t -f hwerr,core,signal server




     The -r 0 and -t options are specified to  indicate  that  if
     the  server  encounters  a  fatal error, ctrun should try to
     restart it. The -f option makes "hwerr", "core",  and  "sig-
     nal" fatal events.


EXIT STATUS
     If  command  is  specified  and  successfully  invoked  (see
     exec(2)),  the  exit  status  of ctrun is the exit status of
     command. Otherwise, ctrun exits with one  of  the  following
     values:



SunOS 5.11          Last change: 22 Mar 2010                    4






User Commands                                            ctrun(1)



     123    The child process exited abnormally.


     124    ctrun encountered an internal error.


     125    Invalid arguments were provided to ctrun.


     126    command was found but could not be invoked.


     127    command could not be found.


FILES
     /system/contract/process/*


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcs                      |
    |_____________________________|_____________________________|
    | Interface Stability         | See below.                  |
    |_____________________________|_____________________________|



     Human Readable Output is Uncommitted. Invocation is  Commit-
     ted.

SEE ALSO
     ctstat(1),  ctwatch(1),  exec(2),  contract(4),  process(4),
     attributes(5)














SunOS 5.11          Last change: 22 Mar 2010                    5