qsub.1p (38374B)
- '\" et
- .TH QSUB "1P" 2017 "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-a \fIdate_time\fB] [\fR-A \fIaccount_string\fB] [\fR-c \fIinterval\fB]
- [\fR-C \fIdirective_prefix\fB] [\fR-e \fIpath_name\fB] [\fR-h\fB] [\fR-j \fIjoin_list\fB]
- [\fR-k \fIkeep_list\fB] [\fR-m \fImail_options\fB] [\fR-M \fImail_list\fB] [\fR-N \fIname\fB]
- [\fR-o \fIpath_name\fB] [\fR-p \fIpriority\fB] [\fR-q \fIdestination\fB] [\fR-r \fIy\fR|\fIn\fB]
- [\fR-S \fIpath_name_list\fB] [\fR-u \fIuser_list\fB] [\fR-v \fIvariable_list\fB] [\fR-V\fB]
- [\fR-z\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\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following options shall be supported by the implementation:
- .IP "\fB\-a\ \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\(hy2017,
- .IR "Section 3.150" ", " "Epoch".
- .P
- If the
- .BR \-a
- 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\-A\ \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 \-A
- 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\-c\ \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 \-c
- 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\-C\ \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 \-C
- 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 \-C
- 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\-e\ \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 \-e
- 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
- \fIjob_name\fR.e\fIsequence_number\fR
- .fi
- .P
- .RE
- .RE
- .IP "\fB\-h\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 \-h
- 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\-j\ \fIjoin_list\fR" 10
- Define which streams of the batch job are to be merged. The
- .IR qsub
- .BR \-j
- 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\(hy2017,
- .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 \-j
- 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\-k\ \fIkeep_list\fR" 10
- Define which output of the batch job to retain on the execution host.
- .RS 10
- .P
- The
- .IR qsub
- .BR \-k
- 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\(hy2017,
- .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 \-k
- 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\-m\ \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 \-m
- 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\(hy2017,
- .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 \-m
- 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\-M\ \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
- \fImail_address\fB[\fR,,\fImail_address\fR,, ...\fB]\fR
- .fi
- .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 \-M
- 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\-N\ \fIname\fR" 10
- Define the name of the batch job.
- .RS 10
- .P
- The
- .IR qsub
- .BR \-N
- 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\(hy2017,
- .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 \-N
- 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 \-N
- 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\-o\ \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\(hy2017, 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 \-o
- 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
- \fIjob_name\fR.o\fIsequence_number\fR
- .fi
- .P
- .RE
- .RE
- .IP "\fB\-p\ \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 \-p
- 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 \-1\|024 and not greater than
- 1\|023.
- .RE
- .IP "\fB\-q\ \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 \-q
- option that conforms to the syntax for a destination (see
- .IR "Section 3.3.2" ", " "Destination").
- .P
- If the
- .BR \-q
- 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\-r\ \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 \-r
- 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\-S\ \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
- \fIpathname\fB[\fR@\fIhost\fB][\fR,,\fIpathname\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR
- .fi
- .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 \-S
- 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\-u\ \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
- \fIusername\fB[\fR@\fIhost\fB][\fR,,\fIusername\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR
- .fi
- .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 \-u
- 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\-v\ \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 \-v
- 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\-V\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\-z\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 \-z
- 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 \-z
- 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 '\-' ,
- 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 '\-' .
- .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\(hy2017,
- .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 \-z
- 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 \-C
- 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 \-C
- 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 \-a
- 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 \-A
- 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 \-C
- 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 \-S
- option.
- .P
- The
- .BR \-c
- option allows users to establish the checkpointing interval for their
- jobs. A checkpointing system, which is not defined by this volume of POSIX.1\(hy2017, 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\(hy2017
- provides the checkpointing interval option. Support for checkpointing
- is optional for batch servers.
- .P
- The
- .BR \-e
- 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 \-h
- 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 \-j
- 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 \-m
- 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 \-M
- 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 \-N
- 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 \-o
- 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 \-P
- option allows users to designate the relative priority of a batch job
- for selection from a queue.
- .P
- The
- .BR \-q
- 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 \-r
- 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 \-r
- 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\(hy2017 specifies that the default, if the
- .BR \-r
- 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 \-S
- 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 \-u
- option is useful when the submitting user is authorized to use more
- than one account on a given host, in which case the
- .BR \-u
- 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 \-u
- 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 \-u
- option.
- .P
- The
- .BR \-V
- 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 \-v
- option allows users to export specific environment variables from their
- current process to the processes of the batch job.
- .P
- The
- .BR \-z
- option allows users to suppress the writing of the batch job identifier
- to standard output. The
- .BR \-z
- 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\(hy2017, \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\(hy2017 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\(hy2017,
- .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-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- 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.opengroup.org/unix/online.html .
- .PP
- 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 .