share/man/man1/newtask.1

   1 '\" te
   2 .\"  Copyright (c) 2004, 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 NEWTASK 1 "Nov 17, 2004"
   7 .SH NAME
   8 newtask \- create new task and optionally change project
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBnewtask\fR [\fB-p\fR \fIproject\fR] [\fB-v\fR] [\fB-c\fR \fIpid\fR | [\fB-Fl\fR] [\fIcommand...\fR]]
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBnewtask\fR command executes the user's default shell or a specified
  19 command, placing the executed command in a new task owned by the specified
  20 project. The user's default shell is the one specified in the \fBpasswd\fR
  21 database, and is determined using \fBgetpwnam()\fR.
  22 .sp
  23 .LP
  24 Alternatively, newtask can be used to cause an already running process to enter
  25 a newly created task. A project for the new task can also be specified in this
  26 form of the command. This might be desirable for processes that are mission
  27 critical and cannot be restarted in order to put them into a new project.
  28 .sp
  29 .LP
  30 In the case that extended accounting is active, the \fBnewtask\fR command can
  31 additionally cause the creation of a task accounting record marking the
  32 completion of the preceding system task.
  33 .SH OPTIONS
  34 .sp
  35 .LP
  36 The following options are supported:
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fB-c\fR \fIpid\fR\fR
  41 .ad
  42 .RS 10n
  43 Cause a running process to enter a newly created task. A project for the new
  44 task can also be specified using the \fB-p\fR option. The invoking user must
  45 either own the process or have super-user privileges.
  46 .sp
  47 If the project is being changed, the process owner must be a member of the
  48 specified project, or the invoking user must have super-user privileges. When
  49 the project is changed for a running process, its pool binding as well as
  50 resource controls are modified to match the configuration of the new project.
  51 Controls not explicitly specified in the project entry is preserved.
  52 .sp
  53 This option is incompatible with the \fB-F\fR and \fB-l\fR options.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fB-F\fR\fR
  60 .ad
  61 .RS 10n
  62 Creates a finalized task, within which further \fBnewtask\fR or
  63 \fBsettaskid\fR(2) invocations would fail. Finalized tasks can be useful at
  64 some sites for simplifying the attribution of resource consumption.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fB-l\fR\fR
  71 .ad
  72 .RS 10n
  73 Changes the environment to what would be expected if the user actually logged
  74 in again as a member of the new project.
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fB-p\fR\fR
  81 .ad
  82 .RS 10n
  83 Changes the project \fBID\fR of the new task to that associated with the given
  84 project name. The invoking user must be a valid member of the requested
  85 project, or must have super-user privileges, for the command to succeed. If no
  86 project name is specified, the new task is started in the invoking user's
  87 current project.
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fB-v\fR\fR
  94 .ad
  95 .RS 10n
  96 Verbose: displays the system task id as the new system task is begun.
  97 .RE
  98
  99 .SH OPERANDS
 100 .sp
 101 .LP
 102 The following operands are supported:
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fIproject\fR\fR
 107 .ad
 108 .RS 11n
 109 The project to which resource usage by the created task should be charged. The
 110 requested project must be defined in the project databases defined in
 111 \fBnsswitch.conf\fR(4).
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fIcommand\fR\fR
 118 .ad
 119 .RS 11n
 120 The command to be executed as the new task. If no command is given, the user's
 121 login shell is invoked. (If the login shell is not available, \fB/bin/sh\fR is
 122 invoked.)
 123 .RE
 124
 125 .SH EXAMPLES
 126 .LP
 127 \fBExample 1 \fRCreating a New Shell
 128 .sp
 129 .LP
 130 The following example creates a new shell in the \fBcanada\fR project,
 131 displaying the task id:
 132
 133 .sp
 134 .in +2
 135 .nf
 136 example$ \fBid -p\fR
 137 uid=565(gh) gid=10(staff) projid=10(default)
 138 example$ \fBnewtask -v -p canada\fR
 139 38
 140 example$ \fBid -p\fR
 141 uid=565(gh) gid=10(staff) projid=82(canada)
 142 .fi
 143 .in -2
 144 .sp
 145
 146 .LP
 147 \fBExample 2 \fRRunning the \fBdate\fR Command
 148 .sp
 149 .LP
 150 The following example runs the date command in the \fBrussia\fR project:
 151
 152 .sp
 153 .in +2
 154 .nf
 155 example$ \fBnewtask -p russia date\fR
 156 Tue Aug 31 11:12:10 PDT 1999
 157 .fi
 158 .in -2
 159 .sp
 160
 161 .LP
 162 \fBExample 3 \fRChanging the Project of an Existing Process
 163 .sp
 164 .LP
 165 The following example changes the project of the existing process with a pid of
 166 \fB9999\fR to \fBrussia\fR:
 167
 168 .sp
 169 .in +2
 170 .nf
 171 example$ \fBnewtask -c 9999 -p russia\fR
 172 .fi
 173 .in -2
 174 .sp
 175
 176 .SH EXIT STATUS
 177 .sp
 178 .LP
 179 The following exit values are returned:
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fB0\fR\fR
 184 .ad
 185 .RS 5n
 186 Successful execution.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fB1\fR\fR
 193 .ad
 194 .RS 5n
 195 A fatal error occurred during execution.
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fB2\fR\fR
 202 .ad
 203 .RS 5n
 204 Invalid command line options were specified.
 205 .RE
 206
 207 .SH FILES
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fB/etc/project\fR\fR
 212 .ad
 213 .RS 16n
 214 Local database containing valid project definitions for this machine.
 215 .RE
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fB/proc/pid/*\fR\fR
 221 .ad
 222 .RS 16n
 223 Process information and control files.
 224 .RE
 225
 226 .SH SEE ALSO
 227 .sp
 228 .LP
 229 \fBproc\fR(1), \fBid\fR(8), \fBpoolbind\fR(8), \fBexecvp\fR(2),
 230 \fBsetrctl\fR(2), \fBsettaskid\fR(2), \fBsetproject\fR(3PROJECT),
 231 \fBnsswitch.conf\fR(4), \fBproc\fR(4), \fBproject\fR(4), \fBattributes\fR(5)