diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/qsub.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/qsub.1p | 1474 |
1 files changed, 1474 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/qsub.1p b/man-pages-posix-2017/man1p/qsub.1p new file mode 100644 index 0000000..e0d2dee --- /dev/null +++ b/man-pages-posix-2017/man1p/qsub.1p @@ -0,0 +1,1474 @@ +'\" 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 . |