CTRUN(1) 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 process 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 contract(5) and
process(5).

OPTIONS

The following options are supported:

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


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

The following are valid events:

core
A member process dumped core.

core events are informative 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 encountered a
hardware error.

hwerr events are fatal by default.


signal
A member process received a fatal
signal from a process in a different
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 contract 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,
regardless of whether the contract
is empty.


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


none
ctrun exits immediately, orphaning
the contract.


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

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

This option is invalid when a
lifetime of none is specified.


pgrponly
If a fatal error occurs, kills at
most the process group of which the
errant process 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 restart continues
indefinitely. By default, ctrun does not
attempt to restart the command.

This option is invalid if a lifetime other than
contract is specified 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

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 contract:


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 "signal" 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:

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(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | See below. |
+--------------------+-----------------+


Human Readable Output is Uncommitted. Invocation is Committed.

SEE ALSO

ctstat(1), ctwatch(1), exec(2), contract(5), process(5), attributes(7)

February 25, 2008 CTRUN(1)