Tribblix: manual page: ctrun.1

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.