'\" et
.TH QSUB "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.

.SH NAME
qsub
\(em submit a script
.SH SYNOPSIS
.LP
.nf
qsub \fB[\fR\(mia \fIdate_time\fB] [\fR\(miA \fIaccount_string\fB] [\fR\(mic \fIinterval\fB]
    [\fR\(miC \fIdirective_prefix\fB] [\fR\(mie \fIpath_name\fB] [\fR\(mih\fB] [\fR\(mij \fIjoin_list\fB]
    [\fR\(mik \fIkeep_list\fB] [\fR\(mim \fImail_options\fB] [\fR\(miM \fImail_list\fB] [\fR\(miN \fIname\fB]
    [\fR\(mio \fIpath_name\fB] [\fR\(mip \fIpriority\fB] [\fR\(miq \fIdestination\fB] [\fR\(mir \fIy\fR|\fIn\fB]
    [\fR\(miS \fIpath_name_list\fB] [\fR\(miu \fIuser_list\fB] [\fR\(miv \fIvariable_list\fB] [\fR\(miV\fB]
    [\fR\(miz\fB] [\fIscript\fB]\fR
.fi
.SH DESCRIPTION
To submit a script is to create a batch job that executes the script. A
script is submitted by a request to a batch server. The
.IR qsub
utility is a user-accessible batch client that submits a script.
.P
Upon successful completion, the
.IR qsub
utility shall have created a batch job that will execute the submitted
script.
.P
The
.IR qsub
utility shall submit a script by sending a
.IR "Queue Job Request"
to a batch server.
.P
The
.IR qsub
utility shall place the value of the following environment variables in
the
.IR Variable_List
attribute of the batch job:
.IR HOME ,
.IR LANG ,
.IR LOGNAME ,
.IR PATH ,
.IR MAIL ,
.IR SHELL ,
and
.IR TZ .
The name of the environment variable shall be the current name prefixed
with the string PBS_O_.
.TP 10
.BR Note:
If the current value of the
.IR HOME
variable in the environment space of the
.IR qsub
utility is
.BR /aa/bb/cc ,
then
.IR qsub
shall place
.IR PBS_O_HOME =\c
.BR /aa/bb/cc
in the
.IR Variable_List
attribute of the batch job.
.P
.P
In addition to the variables described above, the
.IR qsub
utility shall add the following variables with the indicated values to
the variable list:
.IP "\fIPBS_O_WORKDIR\fP" 14
The absolute path of the current working directory of the
.IR qsub
utility process.
.IP "\fIPBS_O_HOST\fP" 14
The name of the host on which the
.IR qsub
utility is running.
.SH OPTIONS
The
.IR qsub
utility shall conform to the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
.P
The following options shall be supported by the implementation:
.IP "\fB\(mia\ \fIdate_time\fR" 10
Define the time at which a batch job becomes eligible for execution.
.RS 10 
.P
The
.IR qsub
utility shall accept an option-argument that conforms to the syntax of
the
.IR time
operand of the
.IR touch
utility.
.br
.sp
.ce 1
\fBTable 4-19: Environment Variable Values (Utilities)\fR
.TS
center box tab(!);
cB | cB
lI | lI.
Variable Name!Value at qsub Time
_
PBS_O_HOME!HOME
PBS_O_HOST!\fRClient host name\fP
PBS_O_LANG!LANG
PBS_O_LOGNAME!LOGNAME
PBS_O_PATH!PATH
PBS_O_MAIL!MAIL
PBS_O_SHELL!SHELL
PBS_O_TZ!TZ
PBS_O_WORKDIR!\fRCurrent working directory\fP
.TE
.TP 10
.BR Note:
The server that initiates execution of the batch job will add other
variables to the batch job's environment; see
.IR "Section 3.2.2.1" ", " "Batch Job Execution".
.P
.P
The
.IR qsub
utility shall set the
.IR Execution_Time
attribute of the batch job to the number of seconds since the Epoch
that is equivalent to the local time expressed by the value of the
.IR date_time
option-argument. The Epoch is defined in the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 3.150" ", " "Epoch".
.P
If the
.BR \(mia
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Execution_Time
attribute of the batch job to a time (number of seconds since the
Epoch) that is earlier than the time at which the utility exits.
.RE
.IP "\fB\(miA\ \fIaccount_string\fR" 10
.br
Define the account to which the resource consumption of the batch job
should be charged.
.RS 10 
.P
The syntax of the
.IR account_string
option-argument is unspecified.
.P
The
.IR qsub
utility shall set the
.IR Account_Name
attribute of the batch job to the value of the
.IR account_string
option-argument.
.P
If the
.BR \(miA
option is not presented to the
.IR qsub
utility, the utility shall omit the
.IR Account_Name
attribute from the attributes of the batch job.
.RE
.IP "\fB\(mic\ \fIinterval\fR" 10
Define whether the batch job should be checkpointed, and if so, how
often.
.RS 10 
.P
The
.IR qsub
utility shall accept a value for the interval option-argument that is
one of the following:
.IP "\fRn\fR" 10
No checkpointing shall be performed on the batch job
(NO_CHECKPOINT).
.IP "\fRs\fR" 10
Checkpointing shall be performed only when the batch server is shut
down (CHECKPOINT_AT_SHUTDOWN).
.IP "\fRc\fR" 10
Automatic periodic checkpointing shall be performed at the
.IR Minimum_Cpu_Interval
attribute of the batch queue, in units of CPU minutes
(CHECKPOINT_AT_MIN_CPU_INTERVAL).
.IP "\fRc\fR=\fIminutes\fR" 10
Automatic periodic checkpointing shall be performed every
.IR minutes
of CPU time, or every
.IR Minimum_Cpu_Interval
minutes, whichever is greater. The
.IR minutes
argument shall conform to the syntax for unsigned integers and shall be
greater than zero.
.P
The
.IR qsub
utility shall set the
.IR Checkpoint
attribute of the batch job to the value of the
.IR interval
option-argument.
.P
If the
.BR \(mic
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Checkpoint
attribute of the batch job to the single character
.BR 'u' 
(CHECKPOINT_UNSPECIFIED).
.RE
.IP "\fB\(miC\ \fIdirective_prefix\fR" 10
.br
Define the prefix that declares a directive to the
.IR qsub
utility within the script.
.RS 10 
.P
The
.IR directive_prefix
is not a batch job attribute; it affects the behavior of the
.IR qsub
utility.
.P
If the
.BR \(miC
option is presented to the
.IR qsub
utility, and the value of the
.IR directive_prefix
option-argument is the null string, the utility shall not scan the
script file for directives. If the
.BR \(miC
option is not presented to the
.IR qsub
utility, then the value of the
.IR PBS_DPREFIX
environment variable is used. If the environment variable is not
defined, then #PBS encoded in the portable character set is the
default.
.RE
.IP "\fB\(mie\ \fIpath_name\fR" 10
.br
Define the path to be used for the standard error stream of the batch
job.
.RS 10 
.P
The
.IR qsub
utility shall accept a
.IR path_name
option-argument which can be preceded by a host name element of the
form
.IR hostname :.
.P
If the
.IR path_name
option-argument constitutes an absolute pathname, the
.IR qsub
utility shall set the
.IR Error_Path
attribute of the batch job to the value of the
.IR path_name
option-argument.
.P
If the
.IR path_name
option-argument constitutes a relative pathname and no host name
element is specified, the
.IR qsub
utility shall set the
.IR Error_Path
attribute of the batch job to the value of the absolute pathname
derived by expanding the
.IR path_name
option-argument relative to the current directory of the process
executing
.IR qsub .
.P
If the
.IR path_name
option-argument constitutes a relative pathname and a host name
element is specified, the
.IR qsub
utility shall set the
.IR Error_Path
attribute of the batch job to the value of the
.IR path_name
option-argument without expansion. The host name element shall be
included.
.P
If the
.IR path_name
option-argument does not include a host name element, the
.IR qsub
utility shall prefix the pathname with
.IR hostname :,
where
.IR hostname
is the name of the host upon which the
.IR qsub
utility is being executed.
.P
If the
.BR \(mie
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Error_Path
attribute of the batch job to the host name and path of the current
directory of the submitting process and the default filename.
.P
The default filename for standard error has the following format:
.sp
.RS 4
.nf
\fB
\fIjob_name\fR.e\fIsequence_number\fR
.fi \fR
.P
.RE
.RE
.IP "\fB\(mih\fR" 10
Specify that a USER hold is applied to the batch job.
.RS 10 
.P
The
.IR qsub
utility shall set the value of the
.IR Hold_Types
attribute of the batch job to the value USER.
.P
If the
.BR \(mih
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Hold_Types
attribute of the batch job to the value NO_HOLD.
.RE
.IP "\fB\(mij\ \fIjoin_list\fR" 10
Define which streams of the batch job are to be merged. The
.IR qsub
.BR \(mij
option shall accept a value for the
.IR join_list
option-argument that is a string of alphanumeric characters in the
portable character set (see the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 6.1" ", " "Portable Character Set").
.RS 10 
.P
The
.IR qsub
utility shall accept a
.IR join_list
option-argument that consists of one or more of the characters
.BR 'e' 
and
.BR 'o' ,
or the single character
.BR 'n' .
.P
All of the other batch job output streams specified will be merged into
the output stream represented by the character listed first in the
.IR join_list
option-argument.
.P
For each unique character in the
.IR join_list
option-argument, the
.IR qsub
utility shall add a value to the
.IR Join_Path
attribute of the batch job as follows, each representing a different
batch job stream to join:
.IP "\fRe\fR" 6
The standard error of the batch job (JOIN_STD_ERROR).
.IP "\fRo\fR" 6
The standard output of the batch job (JOIN_STD_OUTPUT).
.P
An existing
.IR Join_Path
attribute can be cleared by the following join type:
.IP "\fRn\fR" 6
NO_JOIN
.P
If
.BR 'n' 
is specified, then no files are joined. The
.IR qsub
utility shall consider it an error if any join type other than
.BR 'n' 
is combined with join type
.BR 'n' .
.P
Strictly conforming applications shall not repeat any of the characters
.BR 'e' ,
.BR 'o' ,
or
.BR 'n' 
within the
.IR join_list
option-argument. The
.IR qsub
utility shall permit the repetition of characters, but shall not assign
additional meaning to the repeated characters.
.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
If the
.BR \(mij
option is not presented to the
.IR qsub
utility, the utility shall set the value of the
.IR Join_Path
attribute of the batch job to NO_JOIN.
.RE
.IP "\fB\(mik\ \fIkeep_list\fR" 10
Define which output of the batch job to retain on the execution host.
.RS 10 
.P
The
.IR qsub
.BR \(mik
option shall accept a value for the
.IR keep_list
option-argument that is a string of alphanumeric characters in the
portable character set (see the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 6.1" ", " "Portable Character Set").
.P
The
.IR qsub
utility shall accept a
.IR keep_list
option-argument that consists of one or more of the characters
.BR 'e' 
and
.BR 'o' ,
or the single character
.BR 'n' .
.P
For each unique character in the
.IR keep_list
option-argument, the
.IR qsub
utility shall add a value to the
.IR Keep_Files
attribute of the batch job as follows, each representing a different
batch job stream to keep:
.IP "\fRe\fR" 6
The standard error of the batch job (KEEP_STD_ERROR).
.IP "\fRo\fR" 6
The standard output of the batch job (KEEP_STD_OUTPUT).
.P
If both
.BR 'e' 
and
.BR 'o' 
are specified, then both files are retained. An existing
.IR Keep_Files
attribute can be cleared by the following keep type:
.IP "\fRn\fR" 6
NO_KEEP
.P
If
.BR 'n' 
is specified, then no files are retained. The
.IR qsub
utility shall consider it an error if any keep type other than
.BR 'n' 
is combined with keep type
.BR 'n' .
.P
Strictly conforming applications shall not repeat any of the characters
.BR 'e' ,
.BR 'o' ,
or
.BR 'n' 
within the
.IR keep_list
option-argument. The
.IR qsub
utility shall permit the repetition of characters, but shall not assign
additional meaning to the repeated characters.
.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
.BR \(mik
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Keep_Files
attribute of the batch job to the value NO_KEEP.
.RE
.IP "\fB\(mim\ \fImail_options\fR" 10
.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.
.RS 10 
.P
The
.IR qsub
.BR \(mim
option shall accept a value for the
.IR mail_options
option-argument that is a string of alphanumeric characters in the
portable character set (see the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 6.1" ", " "Portable Character Set").
.P
The
.IR qsub
utility shall accept a value for the
.IR mail_options
option-argument that is a string of one or more of the characters
.BR 'e' ,
.BR 'b' ,
and
.BR 'a' ,
or the single character
.BR 'n' .
.P
For each unique character in the
.IR mail_options
option-argument, the
.IR qsub
utility shall add a value to the
.IR Mail_Users
attribute of the batch job as follows, each representing a different
time during the life of a batch job at which to send mail:
.IP "\fRe\fR" 6
MAIL_AT_EXIT
.IP "\fRb\fR" 6
MAIL_AT_BEGINNING
.IP "\fRa\fR" 6
MAIL_AT_ABORT
.P
If any of these characters are duplicated in the
.IR mail_options
option-argument, the duplicates shall be ignored.
.P
An existing
.IR Mail_Points
attribute can be cleared by the following mail type:
.IP "\fRn\fR" 6
NO_MAIL
.P
If
.BR 'n' 
is specified, then mail is not sent. The
.IR qsub
utility shall consider it an error if any mail type other than
.BR 'n' 
is combined with mail type
.BR 'n' .
.P
Strictly conforming applications shall not repeat any of the characters
.BR 'e' ,
.BR 'b' ,
.BR 'a' ,
or
.BR 'n' 
within the
.IR mail_options
option-argument.
.P
The
.IR qsub
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
If the
.BR \(mim
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Mail_Points
attribute to the value MAIL_AT_ABORT.
.RE
.IP "\fB\(miM\ \fImail_list\fR" 10
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.
.RS 10 
.P
The syntax of the
.IR mail_list
option-argument is unspecified.
.P
If the implementation of the
.IR qsub
utility uses a name service to locate users, the utility should accept
the syntax used by the name service.
.P
If the implementation of the
.IR qsub
utility does not use a name service to locate users, the implementation
should accept the following syntax for user names:
.sp
.RS 4
.nf
\fB
\fImail_address\fB[\fR,,\fImail_address\fR,, ...\fB]\fR
.fi \fR
.P
.RE
.P
The interpretation of
.IR mail_address
is implementation-defined.
.P
The
.IR qsub
utility shall set the
.IR Mail_Users
attribute of the batch job to the value of the
.IR mail_list
option-argument.
.P
If the
.BR \(miM
option is not presented to the
.IR qsub
utility, the utility shall place only the user name and host name for
the current process in the
.IR Mail_Users
attribute of the batch job.
.RE
.IP "\fB\(miN\ \fIname\fR" 10
Define the name of the batch job.
.RS 10 
.P
The
.IR qsub
.BR \(miN
option shall accept a value for the
.IR name
option-argument that is a string of up to 15 alphanumeric characters in
the portable character set (see the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 6.1" ", " "Portable Character Set")
where the first character is alphabetic.
.P
The
.IR qsub
utility shall set the value of the
.IR Job_Name
attribute of the batch job to the value of the
.IR name
option-argument.
.P
If the
.BR \(miN
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Job_Name
attribute of the batch job to the name of the
.IR script
argument from which the directory specification if any, has been
removed.
.P
If the
.BR \(miN
option is not presented to the
.IR qsub
utility, and the script is read from standard input, the utility shall
set the
.IR Job_Name
attribute of the batch job to the value STDIN.
.RE
.IP "\fB\(mio\ \fIpath_name\fR" 10
.br
Define the path for the standard output of the batch job.
.RS 10 
.P
The
.IR qsub
utility shall accept a
.IR path_name
option-argument that conforms to the syntax of the
.IR path_name
element defined in the System Interfaces volume of POSIX.1\(hy2008, which can be preceded by a host name
element of the form
.IR hostname :.
.P
If the
.IR path_name
option-argument constitutes an absolute pathname, the
.IR qsub
utility shall set the
.IR Output_Path
attribute of the batch job to the value of the
.IR path_name
option-argument without expansion.
.P
If the
.IR path_name
option-argument constitutes a relative pathname and no host name
element is specified, the
.IR qsub
utility shall set the
.IR Output_Path
attribute of the batch job to the pathname derived by expanding the
value of the
.IR path_name
option-argument relative to the current directory of the process
executing the
.IR qsub .
.P
If the
.IR path_name
option-argument constitutes a relative pathname and a host name
element is specified, the
.IR qsub
utility shall set the
.IR Output_Path
attribute of the batch job to the value of the
.IR path_name
option-argument without expansion.
.P
If the
.IR path_name
option-argument does not specify a host name element, the
.IR qsub
utility shall prefix the pathname with
.IR hostname :,
where
.IR hostname
is the name of the host upon which the
.IR qsub
utility is executing.
.P
If the
.BR \(mio
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Output_Path
attribute of the batch job to the host name and path of the current
directory of the submitting process and the default filename.
.P
The default filename for standard output has the following format:
.sp
.RS 4
.nf
\fB
\fIjob_name\fR.o\fIsequence_number\fR
.fi \fR
.P
.RE
.RE
.IP "\fB\(mip\ \fIpriority\fR" 10
Define the priority the batch job should have relative to other batch
jobs owned by the batch server.
.RS 10 
.P
The
.IR qsub
utility shall set the
.IR Priority
attribute of the batch job to the value of the
.IR priority
option-argument.
.P
If the
.BR \(mip
option is not presented to the
.IR qsub
utility, the value of the
.IR Priority
attribute is implementation-defined.
.P
The
.IR qsub
utility shall accept a value for the
.IR priority
option-argument that conforms to the syntax for signed decimal
integers, and which is not less than \(mi1\|024 and not greater than
1\|023.
.RE
.IP "\fB\(miq\ \fIdestination\fR" 10
.br
Define the destination of the batch job.
.RS 10 
.P
The destination is not a batch job attribute; it determines the batch
server, and possibly the batch queue, to which the
.IR qsub
utility batch queues the batch job.
.P
The
.IR qsub
utility shall submit the script to the batch server named by the
.IR destination
option-argument or the server that owns the batch queue named in the
.IR destination
option-argument.
.P
The
.IR qsub
utility shall accept an option-argument for the
.BR \(miq
option that conforms to the syntax for a destination (see
.IR "Section 3.3.2" ", " "Destination").
.P
If the
.BR \(miq
option is not presented to the
.IR qsub
utility, the
.IR qsub
utility shall submit the batch job to the default destination. The
mechanism for determining the default destination is
implementation-defined.
.RE
.IP "\fB\(mir\ \fIy\fR|\fIn\fR" 10
Define whether the batch job is rerunnable.
.RS 10 
.P
If the value of the option-argument is
.IR y ,
the
.IR qsub
utility shall set the
.IR Rerunable
attribute of the batch job to TRUE.
.P
If the value of the option-argument is
.IR n ,
the
.IR qsub
utility shall set the
.IR Rerunable
attribute of the batch job to FALSE.
.P
If the
.BR \(mir
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Rerunable
attribute of the batch job to TRUE.
.RE
.IP "\fB\(miS\ \fIpath_name_list\fR" 10
.br
Define the pathname to the shell under which the batch job is to
execute.
.RS 10 
.P
The
.IR qsub
utility shall accept a
.IR path_name_list
option-argument that conforms to the following syntax:
.sp
.RS 4
.nf
\fB
\fIpathname\fB[\fR@\fIhost\fB][\fR,,\fIpathname\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR
.fi \fR
.P
.RE
.P
The
.IR qsub
utility shall allow only one pathname for a given host name. The
.IR qsub
utility shall allow only one pathname that is missing a corresponding
host name.
.P
The
.IR qsub
utility shall add a value to the
.IR Shell_Path_List
attribute of the batch job for each entry in the
.IR path_name_list
option-argument.
.P
If the
.BR \(miS
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR Shell_Path_List
attribute of the batch job to the null string.
.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
.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs"
for a means of removing
.IR keyword =\c
.IR value
(and
.IR value @\c
.IR keyword )
pairs and other general rules for list-oriented batch job attributes.
.RE
.IP "\fB\(miu\ \fIuser_list\fR" 10
Define the user name under which the batch job is to execute.
.RS 10 
.P
The
.IR qsub
utility shall accept a
.IR user_list
option-argument that conforms to the following syntax:
.sp
.RS 4
.nf
\fB
\fIusername\fB[\fR@\fIhost\fB][\fR,,\fIusername\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR
.fi \fR
.P
.RE
.P
The
.IR qsub
utility shall accept only one user name that is missing a corresponding
host name. The
.IR qsub
utility shall accept only one user name per named host.
.P
The
.IR qsub
utility shall add a value to the
.IR User_List
attribute of the batch job for each entry in the
.IR user_list
option-argument.
.P
If the
.BR \(miu
option is not presented to the
.IR qsub
utility, the utility shall set the
.IR User_List
attribute of the batch job to the user name from which the utility is
executing. See
.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs"
for a means of removing
.IR keyword =\c
.IR value
(and
.IR value @\c
.IR keyword )
pairs and other general rules for list-oriented batch job attributes.
.RE
.IP "\fB\(miv\ \fIvariable_list\fR" 10
.br
Add to the list of variables that are exported to the session leader of
the batch job.
.RS 10 
.P
A
.IR variable_list
is a set of strings of either the form <\c
.IR variable >
or <\c
.IR variable =\c
.IR value >,
delimited by
<comma>
characters.
.P
If the
.BR \(miv
option is presented to the
.IR qsub
utility, the utility shall also add, to the environment
.IR Variable_List
attribute of the batch job, every variable named in the environment
.IR variable_list
option-argument and, optionally, values of specified variables.
.P
If a value is not provided on the command line, the
.IR qsub
utility shall set the value of each variable in the environment
.IR Variable_List
attribute of the batch job to the value of the corresponding
environment variable for the process in which the utility is executing;
see
.IR "Table 4-19, Environment Variable Values (Utilities)".
.P
A conforming application shall not repeat a variable in the environment
.IR variable_list
option-argument.
.P
The
.IR qsub
utility shall not repeat a variable in the environment
.IR Variable_List
attribute of the batch job. See
.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs"
for a means of removing
.IR keyword =\c
.IR value
(and
.IR value @\c
.IR keyword )
pairs and other general rules for list-oriented batch job attributes.
.RE
.IP "\fB\(miV\fR" 10
Specify that all of the environment variables of the process are
exported to the context of the batch job.
.RS 10 
.P
The
.IR qsub
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.
.RE
.IP "\fB\(miz\fR" 10
Specify that the utility does not write the batch
.IR job_identifier
of the created batch job to standard output.
.RS 10 
.P
If the
.BR \(miz
option is presented to the
.IR qsub
utility, the utility shall not write the batch
.IR job_identifier
of the created batch job to standard output.
.P
If the
.BR \(miz
option is not presented to the
.IR qsub
utility, the utility shall write the identifier of the created batch
job to standard output.
.RE
.SH OPERANDS
The
.IR qsub
utility shall accept a
.IR script
operand that indicates the path to the script of the batch job.
.P
If the
.IR script
operand is not presented to the
.IR qsub
utility, or if the operand is the single-character string
.BR '\(mi' ,
the utility shall read the script from standard input.
.P
If the script represents a partial path, the
.IR qsub
utility shall expand the path relative to the current directory of the
process executing the utility.
.SH STDIN
The
.IR qsub
utility reads the script of the batch job from standard input if the
script operand is omitted or is the single character
.BR '\(mi' .
.SH "INPUT FILES"
In addition to binding the file indicated by the
.IR script
operand to the batch job, the
.IR qsub
utility reads the script file and acts on directives in the script.
.SH "ENVIRONMENT VARIABLES"
The following environment variables shall affect the execution of
.IR qsub :
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 8.2" ", " "Internationalization Variables"
the precedence of internationalization variables used to determine the
values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_CTYPE\fP" 10
Determine the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to
multi-byte characters in arguments).
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error.
.IP "\fILOGNAME\fP" 10
Determine the login name of the user.
.IP "\fIPBS_DPREFIX\fP" 10
.br
Determine the default prefix for directives within the script.
.IP "\fISHELL\fP" 10
Determine the pathname of the preferred command language interpreter
of the user.
.IP "\fITZ\fP" 10
Determine the timezone used to interpret the
.IR date-time
option-argument. If
.IR TZ
is unset or null, an unspecified default timezone shall be used.
.SH "ASYNCHRONOUS EVENTS"
Once created, a batch job exists until it exits, aborts, or is
deleted.
.P
After a batch job is created by the
.IR qsub
utility, batch servers might route, execute, modify, or delete the
batch job.
.SH STDOUT
The
.IR qsub
utility writes the batch
.IR job_identifier
assigned to the batch job to standard output, unless the
.BR \(miz
option is specified.
.SH STDERR
The standard error shall be used only for diagnostic messages.
.SH "OUTPUT FILES"
None.
.SH "EXTENDED DESCRIPTION"
.SS "Script Preservation"
.P
The
.IR qsub
utility shall make the script available to the server executing the
batch job in such a way that the server executes the script as it
exists at the time of submission.
.P
The
.IR qsub
utility can send a copy of the script to the server with the
.IR "Queue Job Request"
or store a temporary copy of the script in a location specified to the
server.
.SS "Option Specification"
.P
A script can contain directives to the
.IR qsub
utility.
.P
The
.IR qsub
utility shall scan the lines of the script for directives, skipping
blank lines, until the first line that begins with a string other than
the directive string; if directives occur on subsequent lines, the
utility shall ignore those directives.
.P
Lines are separated by a
<newline>.
If the first line of the script begins with
.BR \(dq#!\(dq 
or a
<colon>
(\c
.BR ':' ),
then it is skipped. The
.IR qsub
utility shall process a line in the script as a directive if and only
if the string of characters from the first non-white-space character on
the line until the first
<space>
or
<tab>
on the line match the directive prefix. If a line in the script
contains a directive and the final characters of the line are
<backslash>
and
<newline>,
then the next line shall be interpreted as a continuation of that
directive.
.P
The
.IR qsub
utility shall process the options and option-arguments contained on the
directive prefix line using the same syntax as if the options were
input on the
.IR qsub
utility.
.P
The
.IR qsub
utility shall continue to process a directive prefix line until after a
<newline>
is encountered. An implementation may ignore lines which, according to
the syntax of the shell that will interpret the script, are comments.
An implementation shall describe in the conformance document the format
of any shell comments that it will recognize.
.P
If an option is present in both a directive and the arguments to the
.IR qsub
utility, the utility shall ignore the option and the corresponding
option-argument, if any, in the directive.
.P
If an option that is present in the directive is not present in the
arguments to the
.IR qsub
utility, the utility shall process the option and the option-argument,
if any.
.P
In order of preference, the
.IR qsub
utility shall select the directive prefix from one of the following
sources:
.IP " *" 4
If the
.BR \(miC
option is presented to the utility, the value of the
.IR directive_prefix
option-argument
.IP " *" 4
If the environment variable
.IR PBS_DPREFIX
is defined, the value of that variable
.IP " *" 4
The four-character string
.BR \(dq#PBS\(dq 
encoded in the portable character set
.P
If the
.BR \(miC
option is present in the script file it shall be ignored.
.SH "EXIT STATUS"
The following exit values shall be returned:
.IP "\00" 6
Successful completion.
.IP >0 6
An error occurred.
.SH "CONSEQUENCES OF ERRORS"
Default.
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
None.
.SH EXAMPLES
None.
.SH RATIONALE
The
.IR qsub
utility allows users to create a batch job that will process the script
specified as the operand of the utility.
.P
The options of the
.IR qsub
utility allow users to control many aspects of the queuing and
execution of a batch job.
.P
The
.BR \(mia
option allows users to designate the time after which the batch job
will become eligible to run. By specifying an execution time, users can
take advantage of resources at off-peak hours, synchronize jobs with
chronologically predictable events, and perhaps take advantage of
off-peak pricing of computing time. For these reasons and others, a
timing option is existing practice on the part of almost every batch
system, including NQS.
.P
The
.BR \(miA
option allows users to specify the account that will be charged for the
batch job. Support for account is not mandatory for conforming batch
servers.
.P
The
.BR \(miC
option allows users to prescribe the prefix for directives within the
script file. The default prefix
.BR \(dq#PBS\(dq 
may be inappropriate if the script will be interpreted with an
alternate shell, as specified by the
.BR \(miS
option.
.P
The
.BR \(mic
option allows users to establish the checkpointing interval for their
jobs. A checkpointing system, which is not defined by this volume of POSIX.1\(hy2008, allows
recovery of a batch job at the most recent checkpoint in the event of a
crash. Checkpointing is typically used for jobs that consume expensive
computing time or must meet a critical schedule. Users should be
allowed to make the tradeoff between the overhead of checkpointing and
the risk to the timely completion of the batch job; therefore, this volume of POSIX.1\(hy2008
provides the checkpointing interval option. Support for checkpointing
is optional for batch servers.
.P
The
.BR \(mie
option allows users to redirect the standard error streams of their
jobs to a non-default path. For example, if the submitted script
generally produces a great deal of useless error output, a user might
redirect the standard error output to the null device. Or, if the file
system holding the default location (the home directory of the user)
has too little free space, the user might redirect the standard error
stream to a file in another file system.
.P
The
.BR \(mih
option allows users to create a batch job that is held until explicitly
released. The ability to create a held job is useful when some external
event must complete before the batch job can execute. For example, the
user might submit a held job and release it when the system load has
dropped.
.P
The
.BR \(mij
option allows users to merge the standard error of a batch job into its
standard output stream, which has the advantage of showing the
sequential relationship between output and error messages.
.P
The
.BR \(mim
option allows users to designate those points in the execution of a
batch job at which mail will be sent to the submitting user, or to the
account(s) indicated by the
.BR \(miM
option. By requesting mail notification at points of interest in the
life of a job, the submitting user, or other designated users, can
track the progress of a batch job.
.P
The
.BR \(miN
option allows users to associate a name with the batch job. The job
name in no way affects the processing of the batch job, but rather
serves as a mnemonic handle for users. For example, the batch job name
can help the user distinguish between multiple jobs listed by the
.IR qstat
utility.
.P
The
.BR \(mio
option allows users to redirect the standard output stream. A user
might, for example, wish to redirect to the null device the standard
output stream of a job that produces copious yet superfluous output.
.P
The
.BR \(miP
option allows users to designate the relative priority of a batch job
for selection from a queue.
.P
The
.BR \(miq
option allows users to specify an initial queue for the batch job. If
the user specifies a routing queue, the batch server routes the
batch job to another queue for execution or further routing. If the
user specifies a non-routing queue, the batch server of the queue
eventually executes the batch job.
.P
The
.BR \(mir
option allows users to control whether the submitted job will be rerun
if the controlling batch node fails during execution of the batch job.
The
.BR \(mir
option likewise allows users to indicate whether or not the batch job
is eligible to be rerun by the
.IR qrerun
utility. Some jobs cannot be correctly rerun because of changes they
make in the state of databases or other aspects of their environment.
This volume of POSIX.1\(hy2008 specifies that the default, if the
.BR \(mir
option is not presented to the utility, will be that the batch job
cannot be rerun, since the result of rerunning a non-rerunnable job
might be catastrophic.
.P
The
.BR \(miS
option allows users to specify the program (usually a shell) that will
be invoked to process the script of the batch job. This option has been
modified to allow a list of shell names and locations associated with
different hosts.
.P
The
.BR \(miu
option is useful when the submitting user is authorized to use more
than one account on a given host, in which case the
.BR \(miu
option allows the user to select from among those accounts. The
option-argument is a list of user-host pairs, so that the submitting
user can provide different user identifiers for different nodes in the
event the batch job is routed. The
.BR \(miu
option provides a lot of flexibility to accommodate sites with complex
account structures. Users that have the same user identifier on all the
hosts they are authorized to use will not need to use the
.BR \(miu
option.
.P
The
.BR \(miV
option allows users to export all their current environment variables,
as of the time the batch job is submitted, to the context of the
processes of the batch job.
.P
The
.BR \(miv
option allows users to export specific environment variables from their
current process to the processes of the batch job.
.P
The
.BR \(miz
option allows users to suppress the writing of the batch job identifier
to standard output. The
.BR \(miz
option is an existing NQS practice that has been standardized.
.P
Historically, the
.IR qsub
utility has served the batch job-submission function in the NQS system,
the existing practice on which it is based. Some changes and additions
have been made to the
.IR qsub
utility in this volume of POSIX.1\(hy2008, \fIvis-a-vis\fP NQS, as a result of the growing pool
of experience with distributed batch systems.
.P
The set of features of the
.IR qsub
utility as defined in this volume of POSIX.1\(hy2008 appears to incorporate all the common
existing practice on potentially conforming platforms.
.SH "FUTURE DIRECTIONS"
The
.IR qsub
utility may be removed in a future version.
.SH "SEE ALSO"
.IR "Chapter 3" ", " "Batch Environment Services",
.IR "\fIqrerun\fR\^",
.IR "\fIqstat\fR\^",
.IR "\fItouch\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 3.150" ", " "Epoch",
.IR "Section 6.1" ", " "Portable Character Set",
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.unix.org/online.html .

Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .