Signals · XB Field Notes

Process groups select signal recipients, not a family tree

Fri, 24 Sep 2027 00:00:00 +0000

A process group is a kernel-maintained set of processes identified by a process group ID, or PGID. It provides a target for operations such as delivering a signal to a job. Parent-child relationships and group membership are separate: related processes can occupy different groups, and a group’s leader does not need to remain alive for other members to continue belonging to it.

When it breaks

Signaling a process does not automatically signal its children. Signaling its group selects current group members, not every descendant in the process tree. A child that starts another session or group can be outside that target. Conversely, multiple siblings can deliberately share a group even though neither sibling is the other’s parent.

Group delivery also does not guarantee a uniform response. One member can use the signal’s default action, another can install a handler, and another can ignore or block an eligible signal. The operation therefore does not atomically stop a job or prove that all its work completed. Per-process dispositions and the application’s shutdown protocol still determine the outcome.

The leader’s exit is not the group’s exit. A PGID can remain meaningful while another member survives, even after the leader is reaped. Supervisors that watch only the leader’s status may report completion while a member continues running. Group identity should be combined with actual lifecycle management rather than treated as a permanent identifier for all work launched together.

Check it quickly

Save this as groups.py and run python3 groups.py in a disposable Linux environment with Python 3.11 or later. The recorded run used Linux 6.12.76 and Python 3.11.2. Python’s process_group option assigns groups before execution, while start_new_session requests a new session. Every signaled process is a child created by this fixture:

import os,signal,subprocess,sys

worker=r'''
import os,signal,sys
if sys.argv[1]=='ignore-term':signal.signal(signal.SIGTERM,signal.SIG_IGN)
signal.signal(signal.SIGUSR1,lambda *_:print('USR1',flush=True))
print(os.getpid(),os.getpgrp(),os.getsid(0),flush=True)
while True:signal.pause()
'''
children=[]
def launch(role,**settings):
 process=subprocess.Popen([sys.executable,'-c',worker,role],stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True,**settings)
 children.append(process)
 identity=tuple(map(int,process.stdout.readline().split()))
 assert len(identity)==3 and identity[0]==process.pid
 return process,identity
try:
 leader,first=launch('default',process_group=0)
 member,second=launch('ignore-term',process_group=leader.pid)
 outsider,third=launch('default',start_new_session=True)
 group=leader.pid
 assert first[1]==second[1]==group and first[2]==second[2]==os.getsid(0)
 assert third==(outsider.pid,outsider.pid,outsider.pid)
 assert group!=os.getpgrp() and third[1]!=group
 print('two sibling children share a group; another sibling starts a separate session and group')
 os.killpg(group,signal.SIGTERM)
 assert leader.wait(timeout=5)==-signal.SIGTERM
 assert member.poll() is None and outsider.poll() is None
 assert os.getpgid(member.pid)==group
 print('group TERM terminates the default recipient, leaves the ignoring member alive, and excludes the other group')
 os.killpg(group,signal.SIGUSR1)
 assert member.stdout.readline().strip()=='USR1'
 print('the group remains addressable after its leader has exited and been reaped')
 os.killpg(group,signal.SIGKILL)
 assert member.wait(timeout=5)==-signal.SIGKILL
 assert outsider.poll() is None
 outsider.terminate();assert outsider.wait(timeout=5)==-signal.SIGTERM
 print('cleanup reaps all three children; signaling a group did not signal the whole family tree')
finally:
 for process in children:
 if process.poll() is None:process.kill();process.wait()

The first child starts a new process group whose PGID equals its PID. The second child joins that group within the controller’s session. The third child starts a separate session, becoming both its session leader and process-group leader. The script reads actual PID, PGID, and session ID values rather than assuming the requested arrangement took effect.

All three are siblings launched by the same controller. The first two share a signal target, while the third does not. This configuration makes the difference between parenthood and group membership explicit. The script also asserts that the target PGID differs from the controller’s own group, so the group operation cannot accidentally target its controlling process.

Sending TERM to the shared group terminates the first child, which uses the default disposition. The second deliberately ignores TERM and remains alive, as does the child outside the group. The controller waits for and reaps the first child, then confirms that the surviving member still reports the departed leader’s PID as its PGID.

A subsequent group-directed USR1 reaches that surviving member, whose installed handler prints an acknowledgment. This establishes that the group remains addressable after the leader has exited. The example uses a handler acknowledgment for this particular request instead of inferring application response solely from the signal-sending call’s successful return.

Finally, KILL terminates the remaining group member while leaving the separate-session child alive. The controller terminates that third child individually and reaps all three. Cleanup also handles an assertion failure. The result demonstrates selective group targeting and differing dispositions, without requiring a terminal or sending a signal to unrelated host processes.

Separate sessions, terminals, and supervision

setpgid changes membership subject to session and process-state restrictions. setsid creates a new session and group for an eligible caller; a process-group leader cannot use it directly. Creating a session does not change who a process’s parent is. Reparenting, terminal association, and group selection are related operational concerns, but they are not one interchangeable action.

An interactive shell with job control typically places a pipeline in its own group and assigns the terminal’s foreground PGID. The terminal driver delivers configured control-character signals to that foreground group. A noninteractive shell does not universally create one group per pipeline, so the grouping policy must be verified in the actual launch mode.

Signal permissions remain per recipient. Linux documents group-send success as delivery to at least one eligible process; it is not acknowledgment from every member. Use the appropriate service manager or an explicit child-management protocol when completion matters, and observe exits or application acknowledgments. A convenient group target helps control a job, but does not replace tracking its real members and outcomes.

Sources

setpgid(2), process-group membership, inheritance, and session restrictions, checked 2026-09-12.
setsid(2), creating a session and group, with process-group-leader restrictions, checked 2026-09-12.
kill(2), group-directed delivery, permission checks, and success semantics, checked 2026-09-12.
credentials(7), process IDs, groups, sessions, and controlling terminals, checked 2026-09-12.

Shell traps turn a signal into a cleanup step

Tue, 12 Jan 2027 00:00:00 +0000

A trap lets a shell arrange an action for a signal or a shell event. It is useful for removing temporary files and coordinating shutdown, but it does not make interruption atomic or guarantee cleanup under every termination. In Bash, trap is a builtin, and EXIT is a shell event rather than an operating system signal. A reliable design names the exits it handles and preserves evidence of why execution stopped.

Separate a signal handler from the exit handler

trap 'cleanup' INT TERM replaces the default action for those signals. If the handler simply returns, the shell can continue executing; installing a handler does not inherently mean shutdown. One clear Bash pattern has the signal handlers explicitly exit, with a shared EXIT handler doing cleanup. Normal completion and explicit exit also reach that handler.

Returning from a function or a sourced file is not the same as terminating the shell. A top-level return in an ordinary executed script is not a general exit mechanism. Nor should a script assume that an unhandled fatal signal will always trigger EXIT across shells. Handle the intended termination signals explicitly and test with the actual interpreter used by the service.

trap - INT restores the default action; trap '' INT ignores the signal. They are different policies. Noninteractive shells can also inherit ignored signals that they cannot reset or trap, so launcher behavior matters. Inspect registered actions with trap -p when diagnosis requires confirming what was installed.

Preserve the reason for leaving

At entry to the exit handler, save $? before another command overwrites it. Cleanup that ends with an unconditional exit 1 converts successful work into failure and hides distinct error codes. Exiting with the saved value preserves the initiating outcome. Cleanup failures still need visible diagnostics and a deliberate policy, especially if the main work succeeded.

The example chooses 130 for handled INT and 143 for handled TERM, following Bash’s familiar signal-status convention. Those are explicit normal exits, not proof that the process was actually killed by a signal. A supervisor using the process API can distinguish the two. Here, disabling the exit trap and ignoring INT and TERM during the short cleanup prevents those handlers from reentering it.

When it breaks

SIGKILL cannot be caught, and SIGSTOP cannot be caught or used as a cleanup opportunity. Power loss, crashes, and forced termination can leave resources behind. A trap is therefore not a replacement for crash-safe writes, transactional updates, or a separately defined recovery procedure. Restrict removal to paths the script owns; a partially initialized variable must never become a broad deletion target.

Timing also matters. Bash can defer a trapped signal while waiting for a synchronous foreground command to finish. When it is waiting through the wait builtin for an asynchronous command, a trapped signal instead interrupts that wait before the handler runs. Registering a trap does not establish an immediate shutdown deadline for arbitrary blocking work.

Terminal Ctrl-C sends INT to the foreground process group, whereas signaling one PID targets that process. A child may therefore see the signal in one test but not the other. Scripts managing workers must define signal forwarding, waiting, and ownership of those workers. Killing unrelated processes or treating the shell’s exit as proof that every descendant stopped is not cleanup.

Check it quickly

Run this with Python 3, Bash, and standard Unix utilities. Each case starts a separate Bash process that creates one file in a private temporary directory. Signals target only that new shell itself. Python owns the outer directory and removes the deliberately retained KILL artifact afterward.

import os
import signal
import subprocess
import tempfile
from pathlib import Path

script = r'''
demo_file=$1
cleanup() {
 demo_status=$?
 trap - EXIT
 trap '' INT TERM
 rm -f -- "$demo_file"
 printf 'cleanup=%s\n' "$demo_status"
 exit "$demo_status"
}
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
: > "$demo_file" || exit 1
case "$2" in
 normal) exit 7 ;;
 *) kill "-$2" "$$" ;;
esac
exit 99
'''
with tempfile.TemporaryDirectory(prefix="bash-trap-demo-") as directory:
 for mode, expected in [("normal", 7), ("TERM", 143),
 ("INT", 130), ("KILL", -signal.SIGKILL)]:
 target = Path(directory) / mode
 result = subprocess.run(
 ["bash", "--noprofile", "--norc", "-c", script,
 "trap-demo", str(target), mode],
 env=dict(os.environ, BASH_ENV=""),
 text=True, capture_output=True, timeout=5,
 )
 cleaned = result.stdout == f"cleanup={expected}\n"
 remains = target.exists()
 assert result.returncode == expected, result
 assert (cleaned, remains) == (mode != "KILL", mode == "KILL"), result
 assert not result.stderr, result
 print(f"{mode}: rc={result.returncode} cleaned={cleaned} remains={remains}")

Expect return codes 7, 143, and 130 with cleanup observed and no remaining file. KILL yields Python’s negative signal return code, normally -9, with no cleanup output and a remaining file. An invoking shell would conventionally report 137 instead. The contrast verifies preserved status and the uncatchable boundary; it does not test worker forwarding, terminal process groups, or delayed traps around long-running commands.

Sources

Bash signals, signal handling while waiting and foreground process groups, checked 2026-09-07.
POSIX trap, exit events, inherited signal dispositions, and trap actions, checked 2026-09-07.

A signal has a disposition, a mask, and delivery rules

Mon, 23 Nov 2026 00:00:00 +0000

Signals notify processes or threads of events using kernel-defined delivery rules. A signal’s disposition selects a default action, an installed handler, or ignoring it where permitted. A thread’s mask can block delivery of eligible signals while they remain pending. Separating disposition, masking, and pending state is essential when a program appears to miss repeated notifications or fails to stop as expected.

When it breaks

Ordinary signals are not a reliable event counter. Several occurrences of one standard signal can coalesce while it is already pending. An application that treats each SIGUSR1 as one queued work item can therefore lose that counting relationship. Real-time signals have queuing semantics, but their resources are finite and still require a deliberate application protocol.

Signal names do not promise application features. SIGHUP commonly requests reload in particular daemons, but its default action is termination. SIGTERM also terminates by default; it becomes a graceful shutdown request only when the application implements the necessary behavior. Successfully sending a signal does not prove that configuration reloaded or that in-flight work drained.

SIGKILL and SIGSTOP cannot be caught, ignored, or blocked. KILL provides no opportunity for application cleanup, and even it should not be described as guaranteeing instantaneous resource release in every kernel state. A supervisor must observe actual completion. Use symbolic signal names instead of assuming all numerical assignments are identical across platforms.

Check it quickly

Save the following as signals.py and run python3 signals.py in a disposable Linux environment. The recorded run used Linux 6.12.76 and Python 3.11.2. The script signals only itself and children it creates, restores its original mask, and confines cleanup markers to a temporary directory:

from pathlib import Path
from tempfile import TemporaryDirectory
import errno,os,signal,subprocess,sys

watched={signal.SIGUSR1,signal.SIGRTMIN}
old=signal.pthread_sigmask(signal.SIG_BLOCK,watched)
try:
 for _ in range(5):os.kill(os.getpid(),signal.SIGUSR1)
 assert signal.SIGUSR1 in signal.sigpending()
 assert signal.sigwait({signal.SIGUSR1})==signal.SIGUSR1
 assert signal.sigtimedwait({signal.SIGUSR1},0) is None
 for _ in range(3):os.kill(os.getpid(),signal.SIGRTMIN)
 for _ in range(3):assert signal.sigtimedwait({signal.SIGRTMIN},0).si_signo==signal.SIGRTMIN
 assert signal.sigtimedwait({signal.SIGRTMIN},0) is None
 print('five blocked standard signals coalesce into one; three blocked real-time signals remain queued')
finally:signal.pthread_sigmask(signal.SIG_SETMASK,old)
for sig in [signal.SIGKILL,signal.SIGSTOP]:
 try:signal.signal(sig,signal.SIG_IGN)
 except OSError as error:assert error.errno==errno.EINVAL
 else:raise AssertionError('uncatchable signal accepted a disposition change')
old=signal.pthread_sigmask(signal.SIG_BLOCK,{signal.SIGKILL,signal.SIGSTOP})
assert not {signal.SIGKILL,signal.SIGSTOP}&signal.pthread_sigmask(signal.SIG_BLOCK,set())
signal.pthread_sigmask(signal.SIG_SETMASK,old)
print('SIGKILL and SIGSTOP cannot be ignored or added to the blocked mask')
worker=r'''
from pathlib import Path
import signal,sys
if int(sys.argv[1]):signal.signal(signal.SIGTERM,lambda *_:sys.exit(0))
try:
 print('ready',flush=True)
 while True:signal.pause()
finally:Path(sys.argv[2]).write_text('cleanup')
'''
with TemporaryDirectory(prefix='xbcatm-signals-') as directory:
 for name,sig,handled,expected,cleaned in [
 ('hup-default',signal.SIGHUP,False,-signal.SIGHUP,False),
 ('term-default',signal.SIGTERM,False,-signal.SIGTERM,False),
 ('term-handled',signal.SIGTERM,True,0,True),
 ('kill',signal.SIGKILL,True,-signal.SIGKILL,False)]:
 marker=Path(directory)/name
 process=subprocess.Popen([sys.executable,'-c',worker,str(int(handled)),str(marker)],stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True)
 try:
 assert process.stdout.readline().strip()=='ready'
 os.kill(process.pid,sig);output,error=process.communicate(timeout=5)
 assert process.returncode==expected,(name,process.returncode,error)
 assert marker.exists()==cleaned,name
 print(name,'returncode',process.returncode,'cleanup',cleaned)
 finally:
 if process.poll() is None:process.kill();process.wait()

First, the script blocks SIGUSR1, sends it to itself five times, and confirms it is pending. One synchronous wait consumes it; a second zero-time wait finds nothing. Blocking before sending makes this demonstration deterministic. It establishes coalescing of a pending standard signal, not a timing-dependent guess based on how many asynchronous callbacks happened to print.

The same experiment sends three instances of SIGRTMIN while blocked. Three waits retrieve three instances, followed by an empty wait. This contrasts the queuing rules using synchronous consumption. The test does not measure queue capacity, priority across different real-time signal numbers, or delivery of an application payload.

Attempts to ignore KILL and STOP fail with EINVAL. Adding them to the blocked mask also leaves them absent from the actual mask. These checks distinguish a rejected disposition change from a mask request whose unmaskable members are ignored; neither operation makes those signals controllable by the application.

Four child-process cases then separate sending from cleanup. Default HUP and default TERM terminate their children without creating the marker in Python’s finally block. A child with an explicit TERM handler exits through Python and creates the marker. A final child has that same TERM handler, but KILL terminates it without running the cleanup.

The recorded Python subprocess return codes are negative for signal termination: minus the terminating signal number. The handled TERM case exits normally with zero. Those values are Python’s process-status representation, not a universal shell exit-code convention. The fixture checks both the status and marker so neither one alone substitutes for observing the cleanup behavior.

Put work in the appropriate execution context

In native signal handlers, only async-signal-safe operations are suitable. Ordinary logging, allocation, and many library calls can deadlock or corrupt state if interrupted midway. A common design records a minimal notification and lets normal program flow perform coordinated shutdown. The exact mechanism should fit the runtime and its supported event loop.

Python handlers run through the interpreter’s signal machinery in the main thread, rather than executing arbitrary Python inside the low-level C handler. This is why the small TERM example can raise SystemExit. It is not a model for doing arbitrary work in a C handler, nor a guarantee that a long-running native operation will promptly yield to Python cleanup.

Define the expected response, an observation mechanism, and an appropriate deadline when controlling a service. A reload should expose evidence that the new configuration took effect; a shutdown should stop admissions, finish or abandon work according to policy, and report completion. Escalation changes termination behavior, but cannot retroactively supply cleanup the application never implemented.

Sources

signal(7), default actions, masks, standard coalescing, and real-time queues, checked 2026-09-12.
signal-safety(7), async-signal-safe restrictions for native signal handlers, checked 2026-09-12.
Python 3.11 signal documentation, Python handler execution, synchronous waiting, and signal masks, checked 2026-09-12.
kill(2), signal delivery permissions and return semantics, checked 2026-09-12.