share/man/man1/ctrun.1

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH CTRUN 1 "Feb 25, 2008"
   7 .SH NAME
   8 ctrun \- execute command in a process contract
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/bin/ctrun\fR [\fIoptions\fR] \fIcommand\fR [ \fIargument\fR]...
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBctrun\fR utility starts a command in a newly created process contract.
  19 \fBctrun\fR holds the contract and can be instructed to output or respond to
  20 events that occur within the contract.
  21 .sp
  22 .LP
  23 For additional information about process contracts, see \fBcontract\fR(4) and
  24 \fBprocess\fR(4).
  25 .SH OPTIONS
  26 .sp
  27 .LP
  28 The following options are supported:
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fB-A\fR \fIfmri aux\fR\fR
  33 .ad
  34 .RS 26n
  35 Sets the process contract creator's auxiliary field.
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fB-i\fR \fIevent\fR,[\fIevent\fR ...]\fR
  42 .ad
  43 .br
  44 .na
  45 \fB\fB-f\fR \fIevent\fR,[\fIevent\fR ...]\fR
  46 .ad
  47 .RS 26n
  48 Sets the informative and fatal events, respectively.
  49 .sp
  50 The following are valid \fIevent\fRs:
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fBcore\fR\fR
  55 .ad
  56 .RS 10n
  57 A member process dumped core.
  58 .sp
  59 \fBcore\fR events are informative by default.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBempty\fR\fR
  66 .ad
  67 .RS 10n
  68 The last member of the process contract exited.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBexit\fR\fR
  75 .ad
  76 .RS 10n
  77 A member process exited.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBfork\fR\fR
  84 .ad
  85 .RS 10n
  86 A process was added to the process contract.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBhwerr\fR\fR
  93 .ad
  94 .RS 10n
  95 A member process encountered a hardware error.
  96 .sp
  97 \fBhwerr\fR events are fatal by default.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBsignal\fR\fR
 104 .ad
 105 .RS 10n
 106 A member process received a fatal signal from a process in a different process
 107 contract.
 108 .RE
 109
 110 Only \fBcore\fR, \fBhwerr\fR, and \fBsignal\fR events can be made fatal.
 111 .sp
 112 More events can be delivered than requested if \fBctrun\fR requires them for
 113 its own purposes. For example, \fBempty\fR messages are always requested if a
 114 lifetime of \fBcontract\fR is specified. See \fB-l\fR.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fB-F\fR \fIfmri\fR\fR
 121 .ad
 122 .RS 26n
 123 Sets the process contract service \fBFMRI\fR field. To set this field the
 124 caller is required to have the \fB{PRIV_CONTRACT_IDENTITY}\fR in its effective
 125 set.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fB-l\fR \fIlifetime\fR\fR
 132 .ad
 133 .RS 26n
 134 The following valid \fIlifetime\fR values are supported:
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBchild\fR\fR
 139 .ad
 140 .RS 12n
 141 \fBctrun\fR exits when the command exits, regardless of whether the contract is
 142 empty.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBcontract\fR\fR
 149 .ad
 150 .RS 12n
 151 \fBctrun\fR exits only when the contract exits. This is the default.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBnone\fR\fR
 158 .ad
 159 .RS 12n
 160 \fBctrun\fR exits immediately, orphaning the contract.
 161 .RE
 162
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fB-o\fR \fIoption\fR,[\fIoption\fR ...]\fR
 169 .ad
 170 .RS 26n
 171 The following \fIoption\fRs are supported:
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBnoorphan\fR\fR
 176 .ad
 177 .RS 12n
 178 Kills all processes in the contract if the holder (\fBctrun\fR) exits.
 179 .sp
 180 This option is invalid when a lifetime of \fBnone\fR is specified.
 181 .RE
 182
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fBpgrponly\fR\fR
 187 .ad
 188 .RS 12n
 189 If a fatal error occurs, kills at most the process group of which the errant
 190 process is a member.
 191 .RE
 192
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBregent\fR\fR
 197 .ad
 198 .RS 12n
 199 The contract inherits inheritable contracts when abandoned by member processes.
 200 .RE
 201
 202 .RE
 203
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fB-r\fR \fIcount\fR\fR
 208 .ad
 209 .RS 26n
 210 If the contract encounters a fault, this option attempts to restart the command
 211 \fIcount\fR times. If \fIcount\fR is \fB0\fR, the attempt to restart continues
 212 indefinitely. By default, \fBctrun\fR does not attempt to restart the command.
 213 .sp
 214 This option is invalid if a lifetime other than \fBcontract\fR is specified or
 215 if the \fBpgrponly\fR option is used.
 216 .RE
 217
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fB-t\fR\fR
 222 .ad
 223 .RS 26n
 224 If the contract created by \fBctrun\fR inherited subcontracts from its member
 225 processes, attempts to transfer them to the new contract when restarting.
 226 .sp
 227 This option is invalid unless \fB-r\fR is also specified.
 228 .RE
 229
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fB-v\fR\fR
 234 .ad
 235 .RS 26n
 236 Displays contract events and \fBctrun\fR actions as they occur.
 237 .RE
 238
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fB-V\fR\fR
 243 .ad
 244 .RS 26n
 245 Displays verbose contract events, as are displayed by the \fB-v\fR option of
 246 \fBctwatch\fR. Implies \fB-v\fR.
 247 .RE
 248
 249 .SH OPERANDS
 250 .sp
 251 .LP
 252 The following operands are supported:
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fIargument\fR\fR
 257 .ad
 258 .RS 12n
 259 One of the strings treated as an argument to \fIcommand\fR.
 260 .RE
 261
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fIcommand\fR\fR
 266 .ad
 267 .RS 12n
 268 The command to be passed to \fBexecvp\fR(2). See \fBexec\fR(2).
 269 .RE
 270
 271 .SH EXAMPLES
 272 .LP
 273 \fBExample 1 \fRRunning a Shell in a New Process Contract
 274 .sp
 275 .LP
 276 The following example runs a shell in a new process contract:
 277
 278 .sp
 279 .in +2
 280 .nf
 281 example% ctrun -l child -o pgrponly ksh
 282 .fi
 283 .in -2
 284 .sp
 285
 286 .sp
 287 .LP
 288 The \fB-l\fR \fBchild\fR option argument is specified so that \fBctrun\fR won't
 289 wait until all children of the shell have exited. \fB-o\fR \fBpgrponly\fR is
 290 specified because an interactive \fBksh\fR puts each job in a new process
 291 group, and an error in one job is unlikely to affect the others.
 292
 293 .LP
 294 \fBExample 2 \fRRunning a Simple Server
 295 .sp
 296 .LP
 297 The following example runs a simple server:
 298
 299 .sp
 300 .in +2
 301 .nf
 302 example% \fBctrun -r 0 -t -f hwerr,core,signal server\fR
 303 .fi
 304 .in -2
 305 .sp
 306
 307 .sp
 308 .LP
 309 The \fB-r\fR \fB0\fR and \fB-t\fR options are specified to indicate that if the
 310 server encounters a fatal error, \fBctrun\fR should try to restart it. The
 311 \fB-f\fR option makes "\fBhwerr\fR", "\fBcore\fR", and "\fBsignal\fR" fatal
 312 events.
 313
 314 .SH EXIT STATUS
 315 .sp
 316 .LP
 317 If \fIcommand\fR is specified and successfully invoked (see \fBexec\fR(2)), the
 318 exit status of \fBctrun\fR is the exit status of \fIcommand\fR. Otherwise,
 319 \fBctrun\fR exits with one of the following values:
 320 .sp
 321 .ne 2
 322 .na
 323 \fB\fB123\fR\fR
 324 .ad
 325 .RS 7n
 326 The child process exited abnormally.
 327 .RE
 328
 329 .sp
 330 .ne 2
 331 .na
 332 \fB\fB124\fR\fR
 333 .ad
 334 .RS 7n
 335 \fBctrun\fR encountered an internal error.
 336 .RE
 337
 338 .sp
 339 .ne 2
 340 .na
 341 \fB\fB125\fR\fR
 342 .ad
 343 .RS 7n
 344 Invalid arguments were provided to \fBctrun\fR.
 345 .RE
 346
 347 .sp
 348 .ne 2
 349 .na
 350 \fB\fB126\fR\fR
 351 .ad
 352 .RS 7n
 353 \fIcommand\fR was found but could not be invoked.
 354 .RE
 355
 356 .sp
 357 .ne 2
 358 .na
 359 \fB\fB127\fR\fR
 360 .ad
 361 .RS 7n
 362 \fIcommand\fR could not be found.
 363 .RE
 364
 365 .SH FILES
 366 .sp
 367 .ne 2
 368 .na
 369 \fB\fB/system/contract/process/*\fR\fR
 370 .ad
 371 .RS 30n
 372
 373 .RE
 374
 375 .SH ATTRIBUTES
 376 .sp
 377 .LP
 378 See \fBattributes\fR(5) for descriptions of the following attributes:
 379 .sp
 380
 381 .sp
 382 .TS
 383 box;
 384 c | c
 385 l | l .
 386 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 387 _
 388 Interface Stability     See below.
 389 .TE
 390
 391 .sp
 392 .LP
 393 Human Readable Output is Uncommitted. Invocation is Committed.
 394 .SH SEE ALSO
 395 .sp
 396 .LP
 397 \fBctstat\fR(1), \fBctwatch\fR(1), \fBexec\fR(2), \fBcontract\fR(4),
 398 \fBprocess\fR(4), \fBattributes\fR(5)