path: root/usr/src/man/man1/ctrun.1

'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH CTRUN 1 "Feb 25, 2008"
.SH NAME
ctrun \- execute command in a process contract
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/ctrun\fR [\fIoptions\fR] \fIcommand\fR [ \fIargument\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBctrun\fR utility starts a command in a newly created process contract.
\fBctrun\fR holds the contract and can be instructed to output or respond to
events that occur within the contract.
.sp
.LP
For additional information about process contracts, see \fBcontract\fR(4) and
\fBprocess\fR(4).
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-A\fR \fIfmri aux\fR\fR
.ad
.RS 26n
Sets the process contract creator's auxiliary field.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIevent\fR,[\fIevent\fR ...]\fR
.ad
.br
.na
\fB\fB-f\fR \fIevent\fR,[\fIevent\fR ...]\fR
.ad
.RS 26n
Sets the informative and fatal events, respectively.
.sp
The following are valid \fIevent\fRs:
.sp
.ne 2
.na
\fB\fBcore\fR\fR
.ad
.RS 10n
A member process dumped core.
.sp
\fBcore\fR events are informative by default.
.RE

.sp
.ne 2
.na
\fB\fBempty\fR\fR
.ad
.RS 10n
The last member of the process contract exited.
.RE

.sp
.ne 2
.na
\fB\fBexit\fR\fR
.ad
.RS 10n
A member process exited.
.RE

.sp
.ne 2
.na
\fB\fBfork\fR\fR
.ad
.RS 10n
A process was added to the process contract.
.RE

.sp
.ne 2
.na
\fB\fBhwerr\fR\fR
.ad
.RS 10n
A member process encountered a hardware error.
.sp
\fBhwerr\fR events are fatal by default.
.RE

.sp
.ne 2
.na
\fB\fBsignal\fR\fR
.ad
.RS 10n
A member process received a fatal signal from a process in a different process
contract.
.RE

Only \fBcore\fR, \fBhwerr\fR, and \fBsignal\fR events can be made fatal.
.sp
More events can be delivered than requested if \fBctrun\fR requires them for
its own purposes. For example, \fBempty\fR messages are always requested if a
lifetime of \fBcontract\fR is specified. See \fB-l\fR.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR \fIfmri\fR\fR
.ad
.RS 26n
Sets the process contract service \fBFMRI\fR field. To set this field the
caller is required to have the \fB{PRIV_CONTRACT_IDENTITY}\fR in its effective
set.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fIlifetime\fR\fR
.ad
.RS 26n
The following valid \fIlifetime\fR values are supported:
.sp
.ne 2
.na
\fB\fBchild\fR\fR
.ad
.RS 12n
\fBctrun\fR exits when the command exits, regardless of whether the contract is
empty.
.RE

.sp
.ne 2
.na
\fB\fBcontract\fR\fR
.ad
.RS 12n
\fBctrun\fR exits only when the contract exits. This is the default.
.RE

.sp
.ne 2
.na
\fB\fBnone\fR\fR
.ad
.RS 12n
\fBctrun\fR exits immediately, orphaning the contract.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIoption\fR,[\fIoption\fR ...]\fR
.ad
.RS 26n
The following \fIoption\fRs are supported:
.sp
.ne 2
.na
\fB\fBnoorphan\fR\fR
.ad
.RS 12n
Kills all processes in the contract if the holder (\fBctrun\fR) exits.
.sp
This option is invalid when a lifetime of \fBnone\fR is specified.
.RE

.sp
.ne 2
.na
\fB\fBpgrponly\fR\fR
.ad
.RS 12n
If a fatal error occurs, kills at most the process group of which the errant
process is a member.
.RE

.sp
.ne 2
.na
\fB\fBregent\fR\fR
.ad
.RS 12n
The contract inherits inheritable contracts when abandoned by member processes.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-r\fR \fIcount\fR\fR
.ad
.RS 26n
If the contract encounters a fault, this option attempts to restart the command
\fIcount\fR times. If \fIcount\fR is \fB0\fR, the attempt to restart continues
indefinitely. By default, \fBctrun\fR does not attempt to restart the command.
.sp
This option is invalid if a lifetime other than \fBcontract\fR is specified or
if the \fBpgrponly\fR option is used.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 26n
If the contract created by \fBctrun\fR inherited subcontracts from its member
processes, attempts to transfer them to the new contract when restarting.
.sp
This option is invalid unless \fB-r\fR is also specified.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 26n
Displays contract events and \fBctrun\fR actions as they occur.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.RS 26n
Displays verbose contract events, as are displayed by the \fB-v\fR option of
\fBctwatch\fR. Implies \fB-v\fR.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIargument\fR\fR
.ad
.RS 12n
One of the strings treated as an argument to \fIcommand\fR.
.RE

.sp
.ne 2
.na
\fB\fIcommand\fR\fR
.ad
.RS 12n
The command to be passed to \fBexecvp\fR(2). See \fBexec\fR(2).
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRRunning a Shell in a New Process Contract
.sp
.LP
The following example runs a shell in a new process contract:

.sp
.in +2
.nf
example% ctrun -l child -o pgrponly ksh
.fi
.in -2
.sp

.sp
.LP
The \fB-l\fR \fBchild\fR option argument is specified so that \fBctrun\fR won't
wait until all children of the shell have exited. \fB-o\fR \fBpgrponly\fR is
specified because an interactive \fBksh\fR puts each job in a new process
group, and an error in one job is unlikely to affect the others.

.LP
\fBExample 2 \fRRunning a Simple Server
.sp
.LP
The following example runs a simple server:

.sp
.in +2
.nf
example% \fBctrun -r 0 -t -f hwerr,core,signal server\fR
.fi
.in -2
.sp

.sp
.LP
The \fB-r\fR \fB0\fR and \fB-t\fR options are specified to indicate that if the
server encounters a fatal error, \fBctrun\fR should try to restart it. The
\fB-f\fR option makes "\fBhwerr\fR", "\fBcore\fR", and "\fBsignal\fR" fatal
events.

.SH EXIT STATUS
.sp
.LP
If \fIcommand\fR is specified and successfully invoked (see \fBexec\fR(2)), the
exit status of \fBctrun\fR is the exit status of \fIcommand\fR. Otherwise,
\fBctrun\fR exits with one of the following values:
.sp
.ne 2
.na
\fB\fB123\fR\fR
.ad
.RS 7n
The child process exited abnormally.
.RE

.sp
.ne 2
.na
\fB\fB124\fR\fR
.ad
.RS 7n
\fBctrun\fR encountered an internal error.
.RE

.sp
.ne 2
.na
\fB\fB125\fR\fR
.ad
.RS 7n
Invalid arguments were provided to \fBctrun\fR.
.RE

.sp
.ne 2
.na
\fB\fB126\fR\fR
.ad
.RS 7n
\fIcommand\fR was found but could not be invoked.
.RE

.sp
.ne 2
.na
\fB\fB127\fR\fR
.ad
.RS 7n
\fIcommand\fR could not be found.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/system/contract/process/*\fR\fR
.ad
.RS 30n

.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
Human Readable Output is Uncommitted. Invocation is Committed.
.SH SEE ALSO
.sp
.LP
\fBctstat\fR(1), \fBctwatch\fR(1), \fBexec\fR(2), \fBcontract\fR(4),
\fBprocess\fR(4), \fBattributes\fR(5)