QALTER(1POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 QALTER 💖

ok so bestie, welcome to QALTER(1POSIX) — the POSIX Programmer's Manual page for the qalter utility. this one is literally about changing your batch jobs' whole vibe after you've already submitted them. slay. 🎀

✨ PROLOG ✨

real talk first, bestie 💜 — this manual page is part of the POSIX Programmer's Manual. so heads up: the Linux implementation of this interface may differ (go consult the corresponding Linux manual page for the details of Linux behavior), or ngl, the interface may not be implemented on Linux at all. no cap.

🎀 NAME 🎀

qalter — alter batch job.

that's it. that's the job. alter the batch job. 💅

💅 SYNOPSIS 💅

qalter [-a date_time] [-A account_string] [-c interval] [-e path_name]
    [-h hold_list] [-j join_list] [-k keep_list] [-l resource_list]
    [-m mail_options] [-M mail_list] [-N name] [-o path_name]
    [-p priority] [-r y|n] [-S path_name_list] [-u user_list]
    job_identifier...

🌸 DESCRIPTION 🌸

so the way this works is: the attributes of a batch job get altered by a request sent to the batch server that manages that batch job. and qalter? qalter is the user-accessible batch client that makes that request. you tell it which batch jobs to touch, it goes and asks for the alteration. main character energy fr. ✨

here's the whole ruleset, and bestie, every word of it matters:

  • qalter shall alter the attributes of those batch jobs, and only those batch jobs, for which a batch job_identifier is presented to the utility. like, no sneaky extras. 🫶
  • qalter shall alter the attributes of batch jobs in the order in which the batch job_identifiers are presented to the utility. order matters, periodt.
  • If qalter fails to process a batch job_identifier successfully, it shall proceed to process the remaining batch job_identifiers, if any. so one bad apple does not stop the whole party. 🍓
  • For each batch job_identifier for which qalter succeeds, each attribute of the identified batch job shall be altered as indicated by all the options presented to the utility.
  • For each identified batch job for which qalter fails, the utility shall not alter any attribute of the batch job. all or nothing, iykyk.
  • For each batch job that qalter processes, the utility shall not modify any attribute other than those required by the options and option-arguments presented to the utility. it does exactly what you asked, not one thing more. 👑

then the mechanics:

qalter shall alter batch jobs by sending a Modify Job Request to the batch server that manages each batch job. at the time the qalter utility exits, it shall have modified the batch job corresponding to each successfully processed batch job_identifier.

⚠️ and listen — an attempt to alter the attributes of a batch job in the RUNNING state is implementation-defined. so like, it might work, it might not, it's giving "ask your implementation." 🙈

✨ OPTIONS ✨

first things first: qalter shall conform to the Base Definitions volume of POSIX.1-2017, Section 12.2, Utility Syntax Guidelines. rules are rules, bestie. 💜

and the following options shall be supported by the implementation:

  • -a date_time — Redefine the time at which the batch job becomes eligible for execution. ⏰

The date_time argument shall be in the same form and represent the same time as for the touch utility. The time so represented shall be set into the Execution_Time attribute of the batch job.

🚨 If the time specified is earlier than the current time, the -a option shall have no effect. like, the past is the past, girl.
  • -A account_string — Redefine the account to which the resource consumption of the batch job should be charged. 💸

The syntax of the account_string option-argument is unspecified.

qalter shall set the Account_Name attribute of the batch job to the value of the account_string option-argument.

  • -c interval — Redefine whether the batch job should be checkpointed, and if so, how often. 🔄

qalter shall accept a value for the interval option-argument that is one of the following:

  • n — No checkpointing is to be performed on the batch job (NO_CHECKPOINT).
  • s — Checkpointing is to be performed only when the batch server is shut down (CHECKPOINT_AT_SHUTDOWN).
  • c — Automatic periodic checkpointing is to 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 is to 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. 🫠

An implementation may define other checkpoint intervals. The conformance document for an implementation shall describe any alternative checkpoint intervals, how they are specified, their internal behavior, and how they affect the behavior of the utility.

qalter shall set the Checkpoint attribute of the batch job to the value of the interval option-argument.

  • -e path_name — Redefine the path to be used for the standard error stream of the batch job. 🚨

qalter 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, qalter shall set the Error_Path attribute of the batch job to the value of the path_name option-argument, including the host name element, if present.
  • If the path_name option-argument constitutes a relative pathname and no host name element is specified, qalter 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 that executes the qalter utility.
  • If the path_name option-argument constitutes a relative pathname and a host name element is specified, qalter shall set the Error_Path attribute of the batch job to the value of the option-argument without expansion.
  • If the path_name option-argument does not include a host name element, qalter shall prefix the pathname in the Error_Path attribute with hostname:, where hostname is the name of the host upon which the qalter utility is being executed.
  • -h hold_list — Redefine the types of holds, if any, on the batch job. ✋

The qalter -h option shall accept a value for the hold_list option-argument that is a string of alphanumeric characters in the portable character set.

qalter shall accept a value for the hold_list option-argument that is a string of one or more of the characters 'u', 's', or 'o', or the single character 'n'. For each unique character in the hold_list option-argument, qalter shall add a value to the Hold_Types attribute of the batch job as follows, each representing a different hold type:

  • u — USER
  • s — SYSTEM
  • o — OPERATOR

If any of these characters are duplicated in the hold_list option-argument, the duplicates shall be ignored. An existing Hold_Types attribute can be cleared by the hold type:

  • n — NO_HOLD
🚨 qalter shall consider it an error if any hold type other than 'n' is combined with hold type 'n'. Strictly conforming applications shall not repeat any of the characters 'u', 's', 'o', or 'n' within the hold_list option-argument. qalter shall permit the repetition of characters, but shall not assign additional meaning to the repeated characters.

An implementation may define other hold types. The conformance document for an implementation shall describe any additional hold types, how they are specified, their internal behavior, and how they affect the behavior of the utility.

  • -j join_list — Redefine which streams of the batch job are to be merged. 🦋

The qalter -j option shall accept a value for the join_list option-argument that is a string of alphanumeric characters in the portable character set.

qalter 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 shall be merged into the output stream represented by the character listed first in the join_list option-argument. first one wins, bestie.

For each unique character in the join_list option-argument, qalter 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 join type:

  • n — NO_JOIN

If 'n' is specified, then no files are joined.

🚨 qalter shall consider it an error if any join type other than 'n' is combined with join type 'n'.

Strictly conforming applications shall not repeat any of the characters 'e', 'o', or 'n' within the join_list option-argument. qalter shall permit the repetition of characters, but shall not assign additional meaning to the repeated characters.

An implementation may define other join types. The conformance document for an implementation shall describe any additional batch job streams, how they are specified, their internal behavior, and how they affect the behavior of the utility.

  • -k keep_list — Redefine which output of the batch job to retain on the execution host. 💾

The qalter -k option shall accept a value for the keep_list option-argument that is a string of alphanumeric characters in the portable character set.

qalter 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, qalter 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 — this keeps the standard error of the batch job (that's KEEP_STD_ERROR, bestie 💅).
  • o — this keeps the standard output of the batch job (aka KEEP_STD_OUTPUT).

If you specify both e and o, then both files are retained, no crumbs left behind ✨. And an existing Keep_Files attribute can be cleared out entirely by this keep type:

  • n — NO_KEEP. If n is specified, then no files are retained. And heads up: qalter shall consider it an error if any keep type other than n is combined with keep type n 🚫. They do NOT mix.

Strictly conforming applications shall not repeat any of the characters e, o, or n within the keep_list option-argument. qalter shall permit the repetition of characters, but shall not assign additional meaning to the repeated characters — so like, you can type it, it just doesn't mean anything extra 🙈. 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.

  • -l resource_list — Redefine the resources that are allowed or required by the batch job.

qalter shall accept a resource_list option-argument that conforms to the following syntax:

resource=value[,,resource=value,,...]

qalter shall set one entry in the value of the Resource_List attribute of the batch job for each resource listed in the resource_list option-argument.

Because the list of supported resource names might vary by batch server, qalter shall rely on the batch server to validate the resource names and associated values 🔍. 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.

  • -m mail_options — Redefine the points in the execution of the batch job at which the batch server is to send mail about a change in the state of the batch job.

The qalter -m option shall accept a value for the mail_options option-argument that is a string of alphanumeric characters in the portable character set.

qalter 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, qalter 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. So chill, spamming eee changes nothing 💀.

An existing Mail_Points attribute can be cleared by the mail type:

  • n — NO_MAIL. If n is specified, then mail is not sent. And qalter shall consider it an error if any mail type other than n is combined with mail type n. Strictly conforming applications shall not repeat any of the characters e, b, a, or n within the mail_options option-argument. qalter 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.

  • -M mail_list — Redefine the list of users to which the batch server that executes the batch job is to send mail, if the batch server sends mail about the batch job.

The syntax of the mail_list option-argument is unspecified. If the implementation of qalter uses a name service to locate users, the utility shall accept the syntax used by the name service.

If the implementation of qalter does not use a name service to locate users, the implementation shall accept the following syntax for user names:

mail_address[,,mail_address,,...]

The interpretation of mail_address is implementation-defined. The qalter utility shall set the Mail_Users attribute of the batch job to the value of the mail_list option-argument.

  • -N name — Redefine the name of the batch job.

The qalter -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 where the first character is alphabetic 🔤. Yes, fifteen, and yes, it has to start with a letter, don't fight it.

The syntax of the name option-argument is unspecified. The qalter utility shall set the Job_Name attribute of the batch job to the value of the name option-argument.

  • -o path_name — Redefine the path for the standard output of the batch job.

qalter 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, qalter shall set the Output_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, qalter shall set the Output_Path attribute of the batch job to the absolute pathname derived by expanding the path_name option-argument relative to the current directory of the process that executes the qalter utility.

If the path_name option-argument constitutes a relative pathname and a host name element is specified, qalter shall set the Output_Path attribute of the batch job to the value of the path_name option-argument without any expansion of the pathname.

If the path_name option-argument does not include a host name element, qalter shall prefix the pathname in the Output_Path attribute with hostname:, where hostname is the name of the host upon which the qalter utility is being executed.

  • -p priority — Redefine the priority of the batch job.

qalter 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. So that's your range, stay inside it or it's over for you 😭.

qalter shall set the Priority attribute of the batch job to the value of the priority option-argument.

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

If the value of the option-argument is y, qalter shall set the Rerunable attribute of the batch job to TRUE. ✅

If the value of the option-argument is n, qalter shall set the Rerunable attribute of the batch job to FALSE. ❌

qalter shall consider it an error if any character other than y or n is specified in the option-argument. Binary choice only, no vibes in between.

  • -S path_name_list — Redefine the shell that interprets the script at the destination system.

qalter shall accept a path_name_list option-argument that conforms to the following syntax:

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

qalter shall accept only one pathname that is missing a corresponding host name. qalter shall allow only one pathname per named host. Them's the rules 🫶.

qalter shall add a value to the Shell_Path_List attribute of the batch job for each entry in the path_name_list option-argument. 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 — Redefine the user name under which the batch job is to run at the destination system.

qalter shall accept a user_list option-argument that conforms to the following syntax:

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

qalter shall accept only one user name that is missing a corresponding host name. qalter shall accept only one user name per named host.

qalter shall add a value to the User_List attribute of the batch job for each entry in the user_list option-argument. 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.

🦋 OPERANDS 🦋

The qalter utility shall accept one or more operands that conform to the syntax for a batch job_identifier (see Section 3.3.1, Batch Job Identifier). So yeah, you gotta hand it at least one job to actually alter, bestie — it can't read your mind 💅.

🎀 STDIN 🎀

Not used. Nope, not even a little. qalter is not here for your piped-in thoughts, it wants its arguments on the command line ✨.

🌸 INPUT FILES 🌸

None. Zero. Nada. It's not reading any files to do its thing 🦋.

🌸 ENVIRONMENT VARIABLES 🌸

okay bestie, here's the lineup of env vars that actually get a say in how qalter runs. 💖

  • LANG — gives you a default value for all the internationalization variables that are unset or null. (peep the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the whole precedence situation, like which one wins when they're all fighting.)
  • LC_ALL — if it's set to a non-empty string value, it overrides every single other internationalization variable. she's the main character, fr.
  • LC_CTYPE — decides the locale used to interpret sequences of bytes as characters (like, single-byte vs multi-byte characters in arguments, iykyk).
  • LC_MESSAGES — decides the locale that affects the format and contents of diagnostic messages written to standard error.
  • LOGNAME — determines the login name 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 gets used. no cap, it's just unspecified. 🙈

✨ ASYNCHRONOUS EVENTS ✨

Default. that's it, that's the whole section. she said nothing and left. 💅

🎀 STDOUT 🎀

None. literally nothing comes out. silence. iconic.

🦋 STDERR 🦋

The standard error shall be used only for diagnostic messages. so if you're getting output there, bestie, something's up.

🌈 OUTPUT FILES 🌈

None.

💜 EXTENDED DESCRIPTION 💜

None.

⭐ EXIT STATUS ⭐

here's the vibe check on how qalter says goodbye:

  • 0 — Successful completion. slay, it worked.
  • >0 — An error occurred. 😭

💀 CONSEQUENCES OF ERRORS 💀

On top of the default behavior, there's one special case: qalter shall not be required to write a diagnostic message to standard error when the error reply it gets back from a batch server indicates that the batch job_identifier does not exist on that server. and whether qalter tries to go hunt down the batch job on other batch servers? that's implementation-defined. so it might go looking, it might not. mystery. 🕵️

fr fr, the following sections are informative. like, they're context, not rules.

🫶 APPLICATION USAGE 🫶

None.

🍓 EXAMPLES 🍓

None.

👑 RATIONALE 👑

The qalter utility lets users change the attributes of a batch job. that's the whole job description.

As a way of altering a queued job, qalter is superior to deleting and requeuing the batch job — because an altered job keeps its place in the queue with some traditional selection algorithms. plus qalter is both shorter and simpler than doing a whole qdel then qsub sequence. not me doing extra work for no reason. 💅

Now, what happens if a user tries to alter a batch job that's in a RUNNING state? that's implementation-defined, because a batch job in the RUNNING state will already have opened its output files and otherwise done whatever the options in effect at the time the job began execution told it to do. so yeah, kinda locked in at that point.

The options qalter processes are identical to those of the qsub utility, with a few exceptions: -V, -v, and -q.

  • -V and -v are just not appropriate for qalter, since they capture potentially transient environment information from the submitting process. like, that info is from back when you submitted, bestie.
  • -q would specify a new queue, which would largely negate the previously stated advantage of using qalter; and on top of that, the qmove utility provides a superior means of moving jobs. so just use that.

Each of the following paragraphs gives the rationale for a qalter option. (more rationale about these options lives in the rationale for the qsub utility, if you wanna go read that too.)

  • The -a option lets users alter the date and time at which a batch job becomes eligible to run.
  • The -A option lets users change the account that will be charged for the resources consumed by the batch job. support for -A is mandatory for conforming implementations of qalter, even though support of accounting is optional for servers. whether or not to support accounting is left to the implementor of the server, but making -A support mandatory assures users of a consistent interface and lets them control accounting on servers that do support accounting.
  • The -c option lets users alter the checkpointing interval of a batch job. a checkpointing system, which is not defined by POSIX.1‐2008, 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 servers.
  • The -e option lets users alter the name and location of the standard error stream written by a batch job. however, the path of the standard error stream is meaningless if the value of the Join_Path attribute of the batch job is TRUE. 🙃
  • The -h option lets users set the hold type in the Hold_Types attribute of a batch job. the qhold and qrls utilities add or remove hold types to the Hold_Types attribute, respectively. the -h option has been modified to allow for implementation-defined hold types.
  • The -j option lets users alter the decision to join (merge) the standard error stream of the batch job with the standard output stream of the batch job.
  • The -l option lets users change the resource limits imposed on a batch job.
  • The -m option lets users modify the list of points in the life of a batch job at which the designated users will receive mail notification.
  • The -M option lets users alter the list of users who will receive notification about events in the life of a batch job.
  • The -N option lets users change the name of a batch job.
  • The -o option lets users alter the name and path to which the standard output stream of the batch job will be written.
  • The -P option lets users modify the priority of a batch job. support for priority is optional for batch servers.
  • The -r option lets users alter the rerunability status of a batch job.
  • The -S option lets users change the name and location of the shell image that will be invoked to interpret the script of the batch job. this option has been modified to allow a list of shell name and locations associated with different hosts.
  • The -u option lets users change the user identifier under which the batch job will execute.

The job_identifier operand syntax is there so the user can tell the difference between the originating and destination (or executing) batch server. these may or may not be the same, no promises. the .server_name portion identifies the originating batch server, while the @server portion identifies the destination batch server.

Historically, qalter has been a component of the Network Queuing System (NQS), the existing practice from which this utility has been derived. lore. 📜

🔮 FUTURE DIRECTIONS 🔮

The qalter utility may be removed in a future version. so like… enjoy her while she's here. 😭

🧚 SEE ALSO 🧚

  • Chapter 3, Batch Environment Services
  • qdel
  • qhold
  • qmove
  • qrls
  • qsub
  • touch

And from the Base Definitions volume of POSIX.1‐2017:

  • Chapter 8, Environment Variables
  • Section 12.2, Utility Syntax Guidelines

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 .

and that's a wrap, bestie 🫶 this one's brought to you by IEEE/The Open Group, dated 2017, and the page itself is QALTER(1POSIX). go forth and alter some jobs, you absolute icon. 💅✨🎀

📦 where this page comes from