qsig(1B)

💅 qsig — like, the whole manual, but make it make sense

okay bestie, so this is qsig(1B) from PBS Professional — yes, the parentheses and the 1B are part of the name, it's giving "section 1B, admin commands", iconic. this one's literally just "send a signal to a batch job," but there's lore. sit down, grab a strawberry drink 🍓, we're doing this.

---

✨ SYNOPSIS ✨

qsig [-s <signal>] <job ID> [<job ID> ...]
qsig --version

that's it. two lines. so clean. 🫶

---

🦋 DESCRIPTION 🦋

so qsig sends a signal to all the processes of the jobs you name. no cap. under the hood it's firing off a Signal Job batch request to the server that actually owns the job — you're not doing the deed yourself, you're asking nicely. 💅

and it's flexible fr fr — qsig works on jobs, job arrays, subjobs, and ranges of subjobs. if you point it at a range of subjobs, only the running subjobs in that range get signaled. the rest are just vibing, untouched.

okay now, small caveat, keep up: not all signal names are recognized by qsig. 🙈 if using a signal name isn't working for you, try throwing the signal number at it instead. iykyk.

🌸 Using admin-suspend and admin-resume 🌸

so this is the main character part. imagine you've got a vnode that needs maintenance but you wanna keep it powered up — you just don't want jobs running on it while the maintenance is happening. that's exactly what the special signals admin-suspend and admin-resume are for: suspending and resuming the jobs on the vnode. 🎀

when you hit a vnode's job(s) with admin-suspend, the vnode goes into the maintenance state, and its scheduler stops scheduling jobs on it. periodt. ⭐

⚠️ but listen — you must separately admin-suspend each job on the vnode. it's not a one-and-done bundle situation, bestie. every job, individually. 😭

and when its last admin-suspended job gets admin-resumed, the vnode leaves the maintenance state. bye maintenance era 👋

💀 Restrictions 💀

the request to signal a job gets rejected if:

• the user is not authorized to signal the job
• the job is not in the running or suspended state
• the requested signal is not supported by the system upon which the job is executing
• the job is in the process of provisioning
• you attempt to use admin-resume on a job that was suspended
• you attempt to use resume on a job that was admin-suspended

like, read the room, qsig said no. 🔥

👑 Required Privilege 👑

Manager or Operator privilege is required to use the admin-suspend, admin-resume, suspend, or resume signals. unprivileged users can absolutely still use other signals though — you're not locked out entirely, don't worry 🫶

---

🎀 OPTIONS 🎀

• -s — PBS sends SIGTERM to the job. the classic, the default vibe.
• -s <signal> — PBS sends signal signal to the job. you pick, you choose, you slay.
• --version — the qsig command returns its PBS version information and exits. and heads up: this option can only be used alone. no tagging it along with other stuff. 🙈

---

🧚 SIGNALS 🧚

you can send standard signals to a job, or the special signals described below. 🌈

the signal argument can be in any of these formats:

• a signal name, e.g. SIGKILL
• the signal name without the SIG prefix, e.g. KILL
• an unsigned signal number, e.g. 9

also the signal name SIGNULL is allowed — in that case the server sends the signal 0 to the job, which has no effect. literally nothing happens. it's a vibe check and the vibe is silence 💀

💜 Special Signals 💜

the following special signals are all lower-case, and have no associated signal number. keep that in mind:

• admin-suspend — suspends a job and puts its vnodes into the maintenance state. the job is put into the S state and its processes are suspended. when suspended, a job is not executing and is not charged for walltime. 🎀 Syntax: qsig -s admin-suspend <job ID>
• admin-resume — resumes a job that was suspended using the admin-suspend signal, without waiting for its scheduler. Cannot be used on jobs that were suspended with suspend signal. When the last admin-suspended job has been admin_resumed, the vnode leaves the maintenance state. 👑 Syntax: qsig -s admin-resume <job ID>
• suspend — suspends specified job(s). Job goes into suspended (S) state. When suspended, a job is not executing and is not charged for walltime. ✨
• resume — Marks specified job(s) for resumption by a scheduler when there are sufficient resources. If you use qsig -s resume on a job that was suspended using qsig -s suspend , the job is resumed when there are sufficient resources. Cannot be used on jobs that were suspended with admin_suspend signal. 🌸

💀 notice the pattern: admin-suspend pairs with admin-resume, and suspend pairs with resume. do not cross the streams. the manpage says no and honestly same.

---

🍓 OPERANDS 🍓

the qsig command accepts one or more job ID operands. (yes, plural, go off.) 🫶

for a job, this has the form:

<sequence number>[.<server name>][@<server name>]

for a job array, job ID takes the form:

<sequence number>[][.<server name>][@<server name>]

⚠️ and note that some shells require that you enclose a job array identifier in double quotes. don't get caught out by your own shell bestie, that's so embarrassing 😭

---

🌈 STANDARD ERROR 🌈

the qsig command writes a diagnostic messages to standard error for each error occurrence. so if things go wrong, it will tell you — every single time. 🔥

---

⭐ EXIT STATUS ⭐

• Zero — upon successful processing of all the operands presented to the qsig command. slay 💅
• Greater than zero — if the qsig command fails to process any operand. not slay 💀

---

🦋 SEE ALSO 🦋

qsub(1B), pbs_sigjob(3B), pbs_resources(7B)

like, go read those too. i'm not saying it's required, but i'm also not not saying that. 👑

---

mwah 💖 that's the whole page. this one's from the Local channel, dated 6 May 2020, and it's the qsig(1B) page — go signal something responsibly bestie, and remember: admin-suspend every job individually or the maintenance state will humble you 🎀