The qsub utility shall conform to the Base Definitions volume of
POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported by the implementation:
-a date_time
Define the time at which a batch job becomes eligible
for execution.
The qsub utility shall accept an option-argument that
conforms to the syntax of the time operand of the touch
utility.
Table 4-19: Environment Variable Values (Utilities)
┌──────────────┬───────────────────────────┐
│Variable Name │ Value at qsub Time │
├──────────────┼───────────────────────────┤
│PBS_O_HOME │ HOME │
│PBS_O_HOST │ Client host name │
│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 │ Current working directory │
└──────────────┴───────────────────────────┘
Note: The server that initiates execution of the batch
job will add other variables to the batch job's
environment; see Section 3.2.2.1, Batch Job
Execution.
The qsub utility shall set the 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 date_time option-argument. The Epoch
is defined in the Base Definitions volume of
POSIX.1‐2017, Section 3.150, Epoch.
If the -a option is not presented to the qsub utility,
the utility shall set the 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.
-A account_string
Define the account to which the resource consumption of
the batch job should be charged.
The syntax of the account_string option-argument is
unspecified.
The qsub utility shall set the Account_Name attribute
of the batch job to the value of the account_string
option-argument.
If the -A option is not presented to the qsub utility,
the utility shall omit the Account_Name attribute from
the attributes of the batch job.
-c interval
Define whether the batch job should be checkpointed,
and if so, how often.
The qsub utility shall accept a value for the interval
option-argument that is one of the following:
n No checkpointing shall be performed on the
batch job (NO_CHECKPOINT).
s Checkpointing shall be performed only when
the batch server is shut down
(CHECKPOINT_AT_SHUTDOWN).
c Automatic periodic checkpointing shall be
performed at the Minimum_Cpu_Interval
attribute of the batch queue, in units of CPU
minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL).
c=minutes Automatic periodic checkpointing shall be
performed every minutes of CPU time, or every
Minimum_Cpu_Interval minutes, whichever is
greater. The minutes argument shall conform
to the syntax for unsigned integers and shall
be greater than zero.
The qsub utility shall set the Checkpoint attribute of
the batch job to the value of the interval option-
argument.
If the -c option is not presented to the qsub utility,
the utility shall set the Checkpoint attribute of the
batch job to the single character 'u'
(CHECKPOINT_UNSPECIFIED).
-C directive_prefix
Define the prefix that declares a directive to the qsub
utility within the script.
The directive_prefix is not a batch job attribute; it
affects the behavior of the qsub utility.
If the -C option is presented to the qsub utility, and
the value of the directive_prefix option-argument is
the null string, the utility shall not scan the script
file for directives. If the -C option is not presented
to the qsub utility, then the value of the PBS_DPREFIX
environment variable is used. If the environment
variable is not defined, then #PBS encoded in the
portable character set is the default.
-e path_name
Define the path to be used for the standard error
stream of the batch job.
The qsub utility shall accept a path_name option-
argument which can be preceded by a host name element
of the form hostname:.
If the path_name option-argument constitutes an
absolute pathname, the qsub utility shall set the
Error_Path attribute of the batch job to the value of
the path_name option-argument.
If the path_name option-argument constitutes a relative
pathname and no host name element is specified, the
qsub utility shall set the Error_Path attribute of the
batch job to the value of the absolute pathname derived
by expanding the path_name option-argument relative to
the current directory of the process executing qsub.
If the path_name option-argument constitutes a relative
pathname and a host name element is specified, the qsub
utility shall set the Error_Path attribute of the batch
job to the value of the path_name option-argument
without expansion. The host name element shall be
included.
If the path_name option-argument does not include a
host name element, the qsub utility shall prefix the
pathname with hostname:, where hostname is the name of
the host upon which the qsub utility is being executed.
If the -e option is not presented to the qsub utility,
the utility shall set the 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.
The default filename for standard error has the
following format:
job_name.esequence_number
-h Specify that a USER hold is applied to the batch job.
The qsub utility shall set the value of the Hold_Types
attribute of the batch job to the value USER.
If the -h option is not presented to the qsub utility,
the utility shall set the Hold_Types attribute of the
batch job to the value NO_HOLD.
-j join_list
Define which streams of the batch job are to be merged.
The qsub -j option shall accept a value for the
join_list option-argument that is a string of
alphanumeric characters in the portable character set
(see the Base Definitions volume of POSIX.1‐2017,
Section 6.1, Portable Character Set).
The qsub utility shall accept a join_list option-
argument that consists of one or more of the characters
'e' and 'o', or the single character 'n'.
All of the other batch job output streams specified
will be merged into the output stream represented by
the character listed first in the join_list option-
argument.
For each unique character in the join_list option-
argument, the qsub utility shall add a value to the
Join_Path attribute of the batch job as follows, each
representing a different batch job stream to join:
e The standard error of the batch job
(JOIN_STD_ERROR).
o The standard output of the batch job
(JOIN_STD_OUTPUT).
An existing Join_Path attribute can be cleared by the
following join type:
n NO_JOIN
If 'n' is specified, then no files are joined. The qsub
utility shall consider it an error if any join type
other than 'n' is combined with join type 'n'.
Strictly conforming applications shall not repeat any
of the characters 'e', 'o', or 'n' within the join_list
option-argument. The qsub utility shall permit the
repetition of characters, but shall not assign
additional meaning to the repeated characters.
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.
If the -j option is not presented to the qsub utility,
the utility shall set the value of the Join_Path
attribute of the batch job to NO_JOIN.
-k keep_list
Define which output of the batch job to retain on the
execution host.
The qsub -k option shall accept a value for the
keep_list option-argument that is a string of
alphanumeric characters in the portable character set
(see the Base Definitions volume of POSIX.1‐2017,
Section 6.1, Portable Character Set).
The qsub utility shall accept a keep_list option-
argument that consists of one or more of the characters
'e' and 'o', or the single character 'n'.
For each unique character in the keep_list option-
argument, the qsub utility shall add a value to the
Keep_Files attribute of the batch job as follows, each
representing a different batch job stream to keep:
e The standard error of the batch job
(KEEP_STD_ERROR).
o The standard output of the batch job
(KEEP_STD_OUTPUT).
If both 'e' and 'o' are specified, then both files are
retained. An existing Keep_Files attribute can be
cleared by the following keep type:
n NO_KEEP
If 'n' is specified, then no files are retained. The
qsub utility shall consider it an error if any keep
type other than 'n' is combined with keep type 'n'.
Strictly conforming applications shall not repeat any
of the characters 'e', 'o', or 'n' within the keep_list
option-argument. The qsub utility shall permit the
repetition of characters, but shall not assign
additional meaning to the repeated characters.
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 -k option is not
presented to the qsub utility, the utility shall set
the Keep_Files attribute of the batch job to the value
NO_KEEP.
-m mail_options
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.
The qsub -m option shall accept a value for the
mail_options option-argument that is a string of
alphanumeric characters in the portable character set
(see the Base Definitions volume of POSIX.1‐2017,
Section 6.1, Portable Character Set).
The qsub utility shall accept a value for the
mail_options option-argument that is a string of one or
more of the characters 'e', 'b', and 'a', or the single
character 'n'.
For each unique character in the mail_options option-
argument, the qsub utility shall add a value to the
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:
e MAIL_AT_EXIT
b MAIL_AT_BEGINNING
a MAIL_AT_ABORT
If any of these characters are duplicated in the
mail_options option-argument, the duplicates shall be
ignored.
An existing Mail_Points attribute can be cleared by the
following mail type:
n NO_MAIL
If 'n' is specified, then mail is not sent. The qsub
utility shall consider it an error if any mail type
other than 'n' is combined with mail type 'n'.
Strictly conforming applications shall not repeat any
of the characters 'e', 'b', 'a', or 'n' within the
mail_options option-argument.
The 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.
If the -m option is not presented to the qsub utility,
the utility shall set the Mail_Points attribute to the
value MAIL_AT_ABORT.
-M mail_list
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.
The syntax of the mail_list option-argument is
unspecified.
If the implementation of the qsub utility uses a name
service to locate users, the utility should accept the
syntax used by the name service.
If the implementation of the qsub utility does not use
a name service to locate users, the implementation
should accept the following syntax for user names:
mail_address[,,mail_address,, ...]
The interpretation of mail_address is implementation-
defined.
The qsub utility shall set the Mail_Users attribute of
the batch job to the value of the mail_list option-
argument.
If the -M option is not presented to the qsub utility,
the utility shall place only the user name and host
name for the current process in the Mail_Users
attribute of the batch job.
-N name Define the name of the batch job.
The qsub -N option shall accept a value for the 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‐2017,
Section 6.1, Portable Character Set) where the first
character is alphabetic.
The qsub utility shall set the value of the Job_Name
attribute of the batch job to the value of the name
option-argument.
If the -N option is not presented to the qsub utility,
the utility shall set the Job_Name attribute of the
batch job to the name of the script argument from which
the directory specification if any, has been removed.
If the -N option is not presented to the qsub utility,
and the script is read from standard input, the utility
shall set the Job_Name attribute of the batch job to
the value STDIN.
-o path_name
Define the path for the standard output of the batch
job.
The qsub utility shall accept a path_name option-
argument that conforms to the syntax of the path_name
element defined in the System Interfaces volume of
POSIX.1‐2017, which can be preceded by a host name
element of the form hostname:.
If the path_name option-argument constitutes an
absolute pathname, the qsub utility shall set the
Output_Path attribute of the batch job to the value of
the path_name option-argument without expansion.
If the path_name option-argument constitutes a relative
pathname and no host name element is specified, the
qsub utility shall set the Output_Path attribute of the
batch job to the pathname derived by expanding the
value of the path_name option-argument relative to the
current directory of the process executing the qsub.
If the path_name option-argument constitutes a relative
pathname and a host name element is specified, the qsub
utility shall set the Output_Path attribute of the
batch job to the value of the path_name option-argument
without expansion.
If the path_name option-argument does not specify a
host name element, the qsub utility shall prefix the
pathname with hostname:, where hostname is the name of
the host upon which the qsub utility is executing.
If the -o option is not presented to the qsub utility,
the utility shall set the 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.
The default filename for standard output has the
following format:
job_name.osequence_number
-p priority
Define the priority the batch job should have relative
to other batch jobs owned by the batch server.
The qsub utility shall set the Priority attribute of
the batch job to the value of the priority option-
argument.
If the -p option is not presented to the qsub utility,
the value of the Priority attribute is implementation-
defined.
The qsub utility shall accept a value for the priority
option-argument that conforms to the syntax for signed
decimal integers, and which is not less than -1024 and
not greater than 1023.
-q destination
Define the destination of the batch job.
The destination is not a batch job attribute; it
determines the batch server, and possibly the batch
queue, to which the qsub utility batch queues the batch
job.
The qsub utility shall submit the script to the batch
server named by the destination option-argument or the
server that owns the batch queue named in the
destination option-argument.
The qsub utility shall accept an option-argument for
the -q option that conforms to the syntax for a
destination (see Section 3.3.2, Destination).
If the -q option is not presented to the qsub utility,
the qsub utility shall submit the batch job to the
default destination. The mechanism for determining the
default destination is implementation-defined.
-r y|n Define whether the batch job is rerunnable.
If the value of the option-argument is y, the qsub
utility shall set the Rerunable attribute of the batch
job to TRUE.
If the value of the option-argument is n, the qsub
utility shall set the Rerunable attribute of the batch
job to FALSE.
If the -r option is not presented to the qsub utility,
the utility shall set the Rerunable attribute of the
batch job to TRUE.
-S path_name_list
Define the pathname to the shell under which the batch
job is to execute.
The qsub utility shall accept a path_name_list option-
argument that conforms to the following syntax:
pathname[@host][,,pathname[@host],, ...]
The qsub utility shall allow only one pathname for a
given host name. The qsub utility shall allow only one
pathname that is missing a corresponding host name.
The qsub utility shall add a value to the
Shell_Path_List attribute of the batch job for each
entry in the path_name_list option-argument.
If the -S option is not presented to the qsub utility,
the utility shall set the Shell_Path_List attribute of
the batch job to the null string.
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 Section 3.3.3, Multiple Keyword-Value
Pairs for a means of removing keyword=value (and
value@keyword) pairs and other general rules for list-
oriented batch job attributes.
-u user_list
Define the user name under which the batch job is to
execute.
The qsub utility shall accept a user_list option-
argument that conforms to the following syntax:
username[@host][,,username[@host],, ...]
The qsub utility shall accept only one user name that
is missing a corresponding host name. The qsub utility
shall accept only one user name per named host.
The qsub utility shall add a value to the User_List
attribute of the batch job for each entry in the
user_list option-argument.
If the -u option is not presented to the qsub utility,
the utility shall set the User_List attribute of the
batch job to the user name from which the utility is
executing. See Section 3.3.3, Multiple Keyword-Value
Pairs for a means of removing keyword=value (and
value@keyword) pairs and other general rules for list-
oriented batch job attributes.
-v variable_list
Add to the list of variables that are exported to the
session leader of the batch job.
A variable_list is a set of strings of either the form
<variable> or <variable=value>, delimited by <comma>
characters.
If the -v option is presented to the qsub utility, the
utility shall also add, to the environment
Variable_List attribute of the batch job, every
variable named in the environment variable_list option-
argument and, optionally, values of specified
variables.
If a value is not provided on the command line, the
qsub utility shall set the value of each variable in
the environment 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 Table 4-19, Environment Variable Values
(Utilities).
A conforming application shall not repeat a variable in
the environment variable_list option-argument.
The qsub utility shall not repeat a variable in the
environment Variable_List attribute of the batch job.
See Section 3.3.3, Multiple Keyword-Value Pairs for a
means of removing keyword=value (and value@keyword)
pairs and other general rules for list-oriented batch
job attributes.
-V Specify that all of the environment variables of the
process are exported to the context of the batch job.
The 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.
-z Specify that the utility does not write the batch
job_identifier of the created batch job to standard
output.
If the -z option is presented to the qsub utility, the
utility shall not write the batch job_identifier of the
created batch job to standard output.
If the -z option is not presented to the qsub utility,
the utility shall write the identifier of the created
batch job to standard output.
