QSUB(1P)

📦 version 2017a, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, nixpkgs unstable, opensuse-leap 16.0

QSUB(1P) — POSIX Programmer's Manual 🫶

🌸 PROLOG 🌸

okay so real talk: 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. so check before you wreck, bestie. 💅

✨ NAME ✨

qsub — submit a script 💌

🎀 SYNOPSIS 🎀

qsub [-a date_time] [-A account_string] [-c interval]
    [-C directive_prefix] [-e path_name] [-h] [-j join_list]
    [-k keep_list] [-m mail_options] [-M mail_list] [-N name]
    [-o path_name] [-p priority] [-q destination] [-r y|n]
    [-S path_name_list] [-u user_list] [-v variable_list] [-V]
    [-z] [script]

🌈 DESCRIPTION 🌈

okay so submitting a script? it means creating a batch job that runs that script. 💫 A script gets submitted when a request goes to a batch server. The qsub utility is basically a user-accessible batch client that submits a script. periodt. 💅

Upon successful completion, qsub shall have created a batch job that will execute the submitted script. ✨

qsub shall submit a script by sending a Queue Job Request to a batch server. 🚀

qsub shall place the value of these environment variables in the Variable_List attribute of the batch job: HOME, LANG, LOGNAME, PATH, MAIL, SHELL, and TZ. 🫶 The name of the environment variable shall be the current name prefixed with the string PBS_O_. 💖

📝 Note: if the current value of the HOME variable in the environment space of the qsub utility is /aa/bb/cc, then qsub shall place PBS_O_HOME=/aa/bb/cc in the Variable_List attribute of the batch job. so cute.

In addition to the variables described above, qsub shall add these variables with the indicated values to the variable list:

  • PBS_O_WORKDIR — the absolute path of the current working directory of the qsub utility process. 📂
  • PBS_O_HOST — the name of the host on which the qsub utility is running. 🖥️

💅 OPTIONS 💅

qsub 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. ⏰

qsub 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) - 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. 👀

qsub 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 qsub, 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. 🤷‍♀️

qsub 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 qsub, 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. 🔄

qsub 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. 🔢

qsub 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 qsub, 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 qsub 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 qsub, 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 qsub, 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. 📝

qsub 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, qsub 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, qsub 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, qsub 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, qsub 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 qsub, 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. ✋

qsub 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 qsub, 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). 🔤

qsub 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, qsub 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. 🚫

okay so continuing the -j saga, bestie, we were literally just talking about join_list 👇

If n is in there, then no files are joined, like, at all, none, zero, the end. And the qsub utility shall consider it an error if any join type other than n is combined with join type n. So don't do that. 🚫

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 — so repeating them is just... noise, not a secret extra feature. 🙈

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 — decide which output of the batch job gets to stay on the execution host. keeping receipts, but like, filesystem receipts ✨

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. fr fr, that combo is not it 💀

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. she emails you when things happen, it's giving attentive 💌

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. do not do this, bestie, it's an error and I will know 🙈

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. it's the group chat list, basically 🫶

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. naming your child, but the child is a 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. where the lil output goes to live 🏠

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. main character energy, ranked 👑

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. where the job is going, it's a whole vibe check 💅

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 isn't handed to qsub, it's gonna submit the batch job to the default destination. How that default destination gets figured out? implementation-defined, bestie — not our problem. ✨

  • -r y|n — sets whether the batch job is rerunnable. 💫

If the option-argument value is y, qsub sets the Rerunable attribute of the batch job to TRUE.

If the option-argument value is n, qsub sets the Rerunable attribute of the batch job to FALSE.

If -r isn't presented at all, the utility sets the Rerunable attribute of the batch job to TRUE. (default behavior, we love a chill default 🫶)

  • -S path_name_list — defines the pathname to the shell that the batch job executes under. 🐚

qsub shall accept a path_name_list option-argument that conforms to this syntax:

pathname[@host][,,pathname[@host],, ...]

qsub shall allow only one pathname for a given host name. And it shall allow only one pathname that's missing a corresponding host name. (one of each, no greedy behavior 💅)

qsub 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 -S isn't presented, the utility sets 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 — defines the user name the batch job executes under. 👑

qsub shall accept a user_list option-argument that conforms to this syntax:

username[@host][,,username[@host],, ...]

qsub shall accept only one user name that's missing a corresponding host name. And it shall accept only one user name per named host.

qsub shall add a value to the User_List attribute of the batch job for each entry in the user_list option-argument.

If -u isn't presented, the utility sets 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 — adds to the list of variables that get 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 -v is presented, 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 isn't provided on the command line, qsub 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. Don't do it, bestie, it's giving redundant. 🙈

qsub 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 — says that all of the environment variables of the process get exported to the context of the batch job. 🌍

qsub 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. (literally everything, no crumbs left behind ✨)

  • -z — says the utility does not write the batch job_identifier of the created batch job to standard output. 🤫

If -z is presented, the utility shall not write the batch job_identifier of the created batch job to standard output.

If -z isn't presented, the utility shall write the identifier of the created batch job to standard output.

🦋 OPERANDS 🦋

The qsub utility shall accept a script operand that indicates the path to the script of the batch job. 📜

If the script operand isn't presented, or if the operand is the single-character string '-', the utility shall read the script from standard input.

If the script represents a partial path, qsub shall expand the path relative to the current directory of the process executing the utility. 🗺️

🌸 STDIN 🌸

The qsub utility reads the script of the batch job from standard input if the script operand is omitted or is the single character '-'. ⌨️

🎀 INPUT FILES 🎀

On top of binding the file indicated by the script operand to the batch job, the qsub utility reads the script file and acts on directives in the script. 👀

✨ ENVIRONMENT VARIABLES ✨

These environment variables shall affect how qsub runs, bestie:

  • LANG — provides a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
  • LC_ALL — if set to a non-empty string value, overrides the values of all the other internationalization variables. (main character energy, overrides everyone 👑)
  • LC_CTYPE — determines 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).
  • LC_MESSAGES — determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
  • LOGNAME — determines the login name of the user. 🪪
  • PBS_DPREFIX — determines the default prefix for directives within the script. 🔤
  • SHELL — determines the pathname of the preferred command language interpreter of the user. 🐚
  • TZ — determines the timezone used to interpret the date-time option-argument. If TZ is unset or null, an unspecified default timezone shall be used. 🕰️

💫 ASYNCHRONOUS EVENTS 💫

Once created, a batch job exists until it exits, aborts, or is deleted. periodt. 💀

After a batch job is created by the qsub utility, batch servers might route, execute, modify, or delete the batch job. (out of your hands at that point, fr fr 🫶)

🌈 STDOUT 🌈

The qsub utility writes the batch job_identifier assigned to the batch job to standard output, unless the -z option is specified. 📬

🍓 STDERR 🍓

The standard error shall be used only for diagnostic messages. 📢

🧚 OUTPUT FILES 🧚

None. Nada. Zero. 💅

👑 EXTENDED DESCRIPTION 👑

💖 Script Preservation 💖

The 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. 🧊 (frozen in time, iconic)

The qsub utility can send a copy of the script to the server with the Queue Job Request or store a temporary copy of the script in a location specified to the server.

💜 Option Specification 💜

A script can contain directives to the qsub utility. 📝

The 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. (first non-directive line ends the party 🎉)

Lines are separated by a <newline>. If the first line of the script begins with "#!" or a <colon> (':'), then it is skipped. The 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. ↩️

The 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 qsub utility.

The 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.

If an option is present in both a directive and the arguments to qsub, the utility shall ignore the option and the corresponding option-argument, if any, in the directive. (command line wins, always 🏆)

If an option that's present in the directive is not present in the arguments to qsub, the utility shall process the option and the option-argument, if any.

In order of preference, the qsub utility shall select the directive prefix from one of the following sources:

  • If the -C option is presented to the utility, the value of the directive_prefix option-argument
  • If the environment variable PBS_DPREFIX is defined, the value of that variable
  • The four-character string "#PBS" encoded in the portable character set
If the -C option is present in the script file it shall be ignored. 🚫 (only counts on the command line, iykyk)

🔥 EXIT STATUS 🔥

These are the exit values that shall be returned:

  • 0 — Successful completion. 🎉
  • >0 — An error occurred. 😭

💀 CONSEQUENCES OF ERRORS 💀

Default. 💅

The following sections are informative. ✨

🌸 APPLICATION USAGE 🌸

None. 😌 Like, there's literally nothing to say here, bestie.

✨ EXAMPLES ✨

None. No examples, no cap. 🫶

🧠 RATIONALE 🧠

Okay so the qsub utility lets users create a batch job that will process the script specified as the operand of the utility. Periodt. 💖

The options of the qsub utility let users control many aspects of the queuing and execution of a batch job. Iconic behavior. 👑

The -a option lets users 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. ⏰

The -A option lets users specify the account that will be charged for the batch job. Support for account is not mandatory for conforming batch servers. 💳

The -C option lets users prescribe the prefix for directives within the script file. The default prefix "#PBS" may be inappropriate if the script will be interpreted with an alternate shell, as specified by the -S option. 🎀

The -c option lets users establish the checkpointing interval for their jobs. A checkpointing system, which is not defined by this volume of POSIX.1‐2017, 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‐2017 provides the checkpointing interval option. Support for checkpointing is optional for batch servers. 😭

The -e option lets users 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. 🚮

The -h option lets users 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. ✋

The -j option lets users 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. 🔀

The -m option lets users 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 -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. 📬

The -N option lets users 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 qstat utility. 🏷️

The -o option lets users 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. 🗑️

The -P option lets users designate the relative priority of a batch job for selection from a queue. ⭐

The -q option lets users 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. 🚦

The -r option lets users control whether the submitted job will be rerun if the controlling batch node fails during execution of the batch job. The -r option likewise lets users indicate whether or not the batch job is eligible to be rerun by the 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‐2017 specifies that the default, if the -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. 💀

The -S option lets users 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. 🐚

The -u option is useful when the submitting user is authorized to use more than one account on a given host, in which case the -u option lets the user 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 -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 -u option. 👥

The -V option lets users 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. 🌍

The -v option lets users export specific environment variables from their current process to the processes of the batch job. 🧪

The -z option lets users suppress the writing of the batch job identifier to standard output. The -z option is an existing NQS practice that has been standardized. 🤫

Historically, the 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 qsub utility in this volume of POSIX.1‐2017, vis-a-vis NQS, as a result of the growing pool of experience with distributed batch systems. 📚

The set of features of the qsub utility as defined in this volume of POSIX.1‐2017 appears to incorporate all the common existing practice on potentially conforming platforms. ✨

🔮 FUTURE DIRECTIONS 🔮

The qsub utility may be removed in a future version. 😭 Like, enjoy it while it lasts, bestie.

👀 SEE ALSO 👀

Chapter 3, Batch Environment Services, qrerun, qstat, touch

The Base Definitions volume of POSIX.1‐2017, Section 3.150, Epoch, Section 6.1, Portable Character Set, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines

Legal tea, no cap ☕: 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 .

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 .

kisses, your Unix bestie 💋 — this page is from IEEE/The Open Group, 2017, and its ID is QSUB(1P). Stay queued and slay. 🎀✨

📦 where this page comes from