qsub.html

IEEE 1003.1-2003, Single Unix Specification v3

<dt><tt>o</tt></dt>

<dd>The standard output of the batch job (JOIN_STD_OUTPUT).</dd>
</dl>

<p>An existing <i>Join_Path</i> attribute can be cleared by the following join type:</p>

<dl compact>
<dt><tt>n</tt></dt>

<dd>NO_JOIN</dd>
</dl>

<p>If <tt>'n'</tt> is specified, then no files are joined. The <i>qsub</i> utility shall consider it an error if any join type
other than <tt>'n'</tt> is combined with join type <tt>'n'</tt> .</p>

<p>Strictly conforming applications shall not repeat any of the characters <tt>'e'</tt> , <tt>'o'</tt> , or <tt>'n'</tt> within the
<i>join_list</i> option-argument. The <i>qsub</i> utility shall permit the repetition of characters, but shall not assign
additional meaning to the repeated characters.</p>

<p>An implementation may define other join types. The conformance document for an implementation shall describe any additional
batch job streams, how they are specified, their internal behavior, and how they affect the behavior of the utility.</p>

<p>If the <b>-j</b> option is not presented to the <i>qsub</i> utility, the utility shall set the value of the <i>Join_Path</i>
attribute of the batch job to NO_JOIN.</p>
</dd>

<dt><b>-k&nbsp;</b> <i>keep_list</i></dt>

<dd>Define which output of the batch job to retain on the execution host. 

<p>The <i>qsub</i> <b>-k</b> option shall accept a value for the <i>keep_list</i> option-argument that is a string of alphanumeric
characters in the portable character set (see the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/xbd_chap06.html#tag_06_01">Section 6.1, Portable Character Set</a>).</p>

<p>The <i>qsub</i> utility shall accept a <i>keep_list</i> option-argument that consists of one or more of the characters
<tt>'e'</tt> and <tt>'o'</tt> , or the single character <tt>'n'</tt> .</p>

<p>For each unique character in the <i>keep_list</i> option-argument, the <i>qsub</i> utility shall add a value to the
<i>Keep_Files</i> attribute of the batch job as follows, each representing a different batch job stream to keep:</p>

<dl compact>
<dt><tt>e</tt></dt>

<dd>The standard error of the batch job (KEEP_STD_ERROR).</dd>

<dt><tt>o</tt></dt>

<dd>The standard output of the batch job (KEEP_STD_OUTPUT).</dd>
</dl>

<p>If both <tt>'e'</tt> and <tt>'o'</tt> are specified, then both files are retained. An existing <i>Keep_Files</i> attribute can
be cleared by the following keep type:</p>

<dl compact>
<dt><tt>n</tt></dt>

<dd>NO_KEEP</dd>
</dl>

<p>If <tt>'n'</tt> is specified, then no files are retained. The <i>qsub</i> utility shall consider it an error if any keep type
other than <tt>'n'</tt> is combined with keep type <tt>'n'</tt> .</p>

<p>Strictly conforming applications shall not repeat any of the characters <tt>'e'</tt> , <tt>'o'</tt> , or <tt>'n'</tt> within the
<i>keep_list</i> option-argument. The <i>qsub</i> utility shall permit the repetition of characters, but shall not assign
additional meaning to the repeated characters.</p>

<p>An implementation may define other keep types. The conformance document for an implementation shall describe any additional keep
types, how they are specified, their internal behavior, and how they affect the behavior of the utility. If the <b>-k</b> option is
not presented to the <i>qsub</i> utility, the utility shall set the <i>Keep_Files</i> attribute of the batch job to the value
NO_KEEP.</p>
</dd>

<dt><b>-m&nbsp;</b> <i>mail_options</i></dt>

<dd><br>
Define the points in the execution of the batch job at which the batch server that manages the batch job shall send mail about a
change in the state of the batch job. 

<p>The <i>qsub</i> <b>-m</b> option shall accept a value for the <i>mail_options</i> option-argument that is a string of
alphanumeric characters in the portable character set (see the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/xbd_chap06.html#tag_06_01">Section 6.1, Portable Character Set</a>).</p>

<p>The <i>qsub</i> utility shall accept a value for the <i>mail_options</i> option-argument that is a string of one or more of the
characters <tt>'e'</tt> , <tt>'b'</tt> , and <tt>'a'</tt> , or the single character <tt>'n'</tt> .</p>

<p>For each unique character in the <i>mail_options</i> option-argument, the <i>qsub</i> utility shall add a value to the
<i>Mail_Users</i> attribute of the batch job as follows, each representing a different time during the life of a batch job at which
to send mail:</p>

<dl compact>
<dt><tt>e</tt></dt>

<dd>MAIL_AT_EXIT</dd>

<dt><tt>b</tt></dt>

<dd>MAIL_AT_BEGINNING</dd>

<dt><tt>a</tt></dt>

<dd>MAIL_AT_ABORT</dd>
</dl>

<p>If any of these characters are duplicated in the <i>mail_options</i> option-argument, the duplicates shall be ignored.</p>

<p>An existing <i>Mail_Points</i> attribute can be cleared by the following mail type:</p>

<dl compact>
<dt><tt>n</tt></dt>

<dd>NO_MAIL</dd>
</dl>

<p>If <tt>'n'</tt> is specified, then mail is not sent. The <i>qsub</i> utility shall consider it an error if any mail type other
than <tt>'n'</tt> is combined with mail type <tt>'n'</tt> .</p>

<p>Strictly conforming applications shall not repeat any of the characters <tt>'e'</tt> , <tt>'b'</tt> , <tt>'a'</tt> , or
<tt>'n'</tt> within the <i>mail_options</i> option-argument.</p>

<p>The <i>qsub</i> utility shall permit the repetition of characters, but shall not assign additional meaning to the repeated
characters. An implementation may define other mail types. The conformance document for an implementation shall describe any
additional mail types, how they are specified, their internal behavior, and how they affect the behavior of the utility.</p>

<p>If the <b>-m</b> option is not presented to the <i>qsub</i> utility, the utility shall set the <i>Mail_Points</i> attribute to
the value MAIL_AT_ABORT.</p>
</dd>

<dt><b>-M&nbsp;</b> <i>mail_list</i></dt>

<dd>Define the list of users to which a batch server that executes the batch job shall send mail, if the server sends mail about
the batch job. 

<p>The syntax of the <i>mail_list</i> option-argument is unspecified.</p>

<p>If the implementation of the <i>qsub</i> utility uses a name service to locate users, the utility should accept the syntax used
by the name service.</p>

<p>If the implementation of the <i>qsub</i> utility does not use a name service to locate users, the implementation should accept
the following syntax for user names:</p>

<pre>
<i>mail_address</i><b>[</b><tt>,,</tt><i>mail_address</i><tt>,, ...</tt><b>]</b>
</pre>

<p>The interpretation of <i>mail_address</i> is implementation-defined.</p>

<p>The <i>qsub</i> utility shall set the <i>Mail_Users</i> attribute of the batch job to the value of the <i>mail_list</i>
option-argument.</p>

<p>If the <b>-M</b> option is not presented to the <i>qsub</i> utility, the utility shall place only the user name and host name
for the current process in the <i>Mail_Users</i> attribute of the batch job.</p>
</dd>

<dt><b>-N&nbsp;</b> <i>name</i></dt>

<dd>Define the name of the batch job. 

<p>The <i>qsub</i> <b>-N</b> option shall accept a value for the <i>name</i> option-argument that is a string of up to 15
alphanumeric characters in the portable character set (see the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/xbd_chap06.html#tag_06_01">Section 6.1, Portable Character Set</a>) where the first character is alphabetic.</p>

<p>The <i>qsub</i> utility shall set the value of the <i>Job_Name</i> attribute of the batch job to the value of the <i>name</i>
option-argument.</p>

<p>If the <b>-N</b> option is not presented to the <i>qsub</i> utility, the utility shall set the <i>Job_Name</i> attribute of the
batch job to the name of the <i>script</i> argument from which the directory specification if any, has been removed.</p>

<p>If the <b>-N</b> option is not presented to the <i>qsub</i> utility, and the script is read from standard input, the utility
shall set the <i>Job_Name</i> attribute of the batch job to the value STDIN.</p>
</dd>

<dt><b>-o&nbsp;</b> <i>path_name</i></dt>

<dd>Define the path for the standard output of the batch job. 

<p>The <i>qsub</i> utility shall accept a <i>path_name</i> option-argument that conforms to the syntax of the <i>path_name</i>
element defined in the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001, which can be preceded by a host name element of
the form <i>hostname</i>:.</p>

<p>If the <i>path_name</i> option-argument constitutes an absolute pathname, the <i>qsub</i> utility shall set the
<i>Output_Path</i> attribute of the batch job to the value of the <i>path_name</i> option-argument without expansion.</p>

<p>If the <i>path_name</i> option-argument constitutes a relative pathname and no host name element is specified, the <i>qsub</i>
utility shall set the <i>Output_Path</i> attribute of the batch job to the pathname derived by expanding the value of the
<i>path_name</i> option-argument relative to the current directory of the process executing the <i>qsub</i>.</p>

<p>If the <i>path_name</i> option-argument constitutes a relative pathname and a host name element is specified, the <i>qsub</i>
utility shall set the <i>Output_Path</i> attribute of the batch job to the value of the <i>path_name</i> option-argument without
expansion.</p>

<p>If the <i>path_name</i> option-argument does not specify a host name element, the <i>qsub</i> utility shall prefix the pathname
with <i>hostname</i>:, where <i>hostname</i> is the name of the host upon which the <i>qsub</i> utility is executing.</p>

<p>If the <b>-o</b> option is not presented to the <i>qsub</i> utility, the utility shall set the <i>Output_Path</i> attribute of
the batch job to the host name and path of the current directory of the submitting process and the default filename.</p>

<p>The default filename for standard output has the following format:</p>

<pre>
<i>job_name</i><tt>.o</tt><i>sequence_number</i>
</pre>
</dd>

<dt><b>-p&nbsp;</b> <i>priority</i></dt>

<dd>Define the priority the batch job should have relative to other batch jobs owned by the batch server. 

<p>The <i>qsub</i> utility shall set the <i>Priority</i> attribute of the batch job to the value of the <i>priority</i>
option-argument.</p>

<p>If the <b>-p</b> option is not presented to the <i>qsub</i> utility, the value of the <i>Priority</i> attribute is
implementation-defined.</p>

<p>The <i>qsub</i> utility shall accept a value for the <i>priority</i> option-argument that conforms to the syntax for signed
decimal integers, and which is not less than -1024 and not greater than 1023.</p>
</dd>

<dt><b>-q&nbsp;</b> <i>destination</i></dt>

<dd><br>
Define the destination of the batch job. 

<p>The destination is not a batch job attribute; it determines the batch server, and possibly the batch queue, to which the
<i>qsub</i> utility batch queues the batch job.</p>

<p>The <i>qsub</i> utility shall submit the script to the batch server named by the <i>destination</i> option-argument or the
server that owns the batch queue named in the <i>destination</i> option-argument.</p>

<p>The <i>qsub</i> utility shall accept an option-argument for the <b>-q</b> option that conforms to the syntax for a destination
(see <a href="xcu_chap03.html#tag_03_03_02"><i>Destination</i></a> ).</p>

<p>If the <b>-q</b> option is not presented to the <i>qsub</i> utility, the <i>qsub</i> utility shall submit the batch job to the
default destination. The mechanism for determining the default destination is implementation-defined.</p>
</dd>

<dt><b>-r&nbsp;</b> <i>y</i>|<i>n</i></dt>

<dd>Define whether the batch job is rerunnable. 

<p>If the value of the option-argument is <i>y</i>, the <i>qsub</i> utility shall set the <i>Rerunable</i> attribute of the batch
job to TRUE.</p>

<p>If the value of the option-argument is <i>n</i>, the <i>qsub</i> utility shall set the <i>Rerunable</i> attribute of the batch
job to FALSE.</p>

<p>If the <b>-r</b> option is not presented to the <i>qsub</i> utility, the utility shall set the <i>Rerunable</i> attribute of the
batch job to TRUE.</p>
</dd>

<dt><b>-S&nbsp;</b> <i>path_name_list</i></dt>

<dd><br>
Define the pathname to the shell under which the batch job is to execute. 

<p>The <i>qsub</i> utility shall accept a <i>path_name_list</i> option-argument that conforms to the following syntax:</p>

<pre>
<i>pathname</i><b>[</b><tt>@</tt><i>host</i><b>][</b><tt>,,</tt><i>pathname</i><b>[</b><tt>@</tt><i>host</i><b>]</b><tt>,, ...</tt><b>]</b>
</pre>

<p>The <i>qsub</i> utility shall allow only one pathname for a given host name. The <i>qsub</i> utility shall allow only one
pathname that is missing a corresponding host name.</p>

<p>The <i>qsub</i> utility shall add a value to the <i>Shell_Path_List</i> attribute of the batch job for each entry in the
<i>path_name_list</i> option-argument.</p>

<p>If the <b>-S</b> option is not presented to the <i>qsub</i> utility, the utility shall set the <i>Shell_Path_List</i> attribute
of the batch job to the null string.</p>

<p>The conformance document for an implementation shall describe the mechanism used to set the default shell and determine the
current value of the default shell. An implementation shall provide a means for the installation to set the default shell to the
login shell of the user under which the batch job is to execute. See <a href="xcu_chap03.html#tag_03_03_03"><i>Multiple
Keyword-Value Pairs</i></a> for a means of removing <i>keyword</i>= <i>value</i> (and <i>value</i>@ <i>keyword</i>) pairs and other
general rules for list-oriented batch job attributes.</p>
</dd>

<dt><b>-u&nbsp;</b> <i>user_list</i></dt>

<dd>Define the user name under which the batch job is to execute. 

<p>The <i>qsub</i> utility shall accept a <i>user_list</i> option-argument that conforms to the following syntax:</p>

<pre>
<i>username</i><b>[</b><tt>@</tt><i>host</i><b>][</b><tt>,,</tt><i>username</i><b>[</b><tt>@</tt><i>host</i><b>]</b><tt>,, ...</tt><b>]</b>
</pre>

<p>The <i>qsub</i> utility shall accept only one user name that is missing a corresponding host name. The <i>qsub</i> utility shall
accept only one user name per named host.</p>

<p>The <i>qsub</i> utility shall add a value to the <i>User_List</i> attribute of the batch job for each entry in the
<i>user_list</i> option-argument.</p>

<p>If the <b>-u</b> option is not presented to the <i>qsub</i> utility, the utility shall set the <i>User_List</i> attribute of the
batch job to the user name from which the utility is executing. See <a href="xcu_chap03.html#tag_03_03_03"><i>Multiple
Keyword-Value Pairs</i></a> for a means of removing <i>keyword</i>= <i>value</i> (and <i>value</i>@ <i>keyword</i>) pairs and other
general rules for list-oriented batch job attributes.</p>
</dd>

<dt><b>-v&nbsp;</b> <i>variable_list</i></dt>

<dd><br>
Add to the list of variables that are exported to the session leader of the batch job. 

<p>A <i>variable_list</i> is a set of strings of either the form &lt; <i>variable</i>&gt; or &lt; <i>variable</i>=
<i>value</i>&gt;, delimited by commas.</p>

<p>If the <b>-v</b> option is presented to the <i>qsub</i> utility, the utility shall also add, to the environment
<i>Variable_List</i> attribute of the batch job, every variable named in the environment <i>variable_list</i> option-argument and,
optionally, values of specified variables.</p>

<p>If a value is not provided on the command line, the <i>qsub</i> utility shall set the value of each variable in the environment
<i>Variable_List</i> attribute of the batch job to the value of the corresponding environment variable for the process in which the
utility is executing; see <a href="#tagtcjh_18">Environment Variable Values (Utilities)</a> .</p>

<p>A conforming application shall not repeat a variable in the environment <i>variable_list</i> option-argument.</p>

<p>The <i>qsub</i> utility shall not repeat a variable in the environment <i>Variable_List</i> attribute of the batch job. See <a
href="xcu_chap03.html#tag_03_03_03"><i>Multiple Keyword-Value Pairs</i></a> for a means of removing <i>keyword</i>= <i>value</i>
(and <i>value</i>@ <i>keyword</i>) pairs and other general rules for list-oriented batch job attributes.</p>
</dd>

<dt><b>-V</b></dt>

<dd>Specify that all of the environment variables of the process are exported to the context of the batch job. 

<p>The <i>qsub</i> utility shall place every environment variable in the process in which the utility is executing in the list and
shall set the value of each variable in the attribute to the value of that variable in the process.</p>
</dd>

<dt><b>-z</b></dt>

<dd>Specify that the utility does not write the batch <i>job_identifier</i> of the created batch job to standard output. 

<p>If the <b>-z</b> option is presented to the <i>qsub</i> utility, the utility shall not write the batch <i>job_identifier</i> of