Skip to content
Shell & TerminalDeep Dive Published Updated 7 min readViews unavailable

Shell time: Measure Pipelines Without Confusing Wall and CPU Time

Distinguish Bash's timed pipelines from GNU time's child-command reports, then interpret elapsed, user, and system time with failure-aware examples.

The word time at the start of a shell line might be syntax understood by the shell, or it might name an executable the shell found on PATH. That difference matters when the target is a pipeline. Bash’s reserved word can time the complete pipeline; GNU Time 1.10 is an external program that launches a command. Both can report elapsed, user, and system time, but they do not have the same command boundary or options.

This guide uses the Bash 5.3 Reference Manual for shell behavior, GNU Time 1.10 for the external utility, and the POSIX.1-2024 Issue 8 utility specification for the portable contract. The Bash pipeline example was exercised with macOS’s bundled Bash 3.2.57; that does not make GNU Time flags portable. Check the actual interpreter and external utility on each host before copying the commands.

Real, user, and system measure different things

real (also called elapsed or wall-clock time) is the time between starting and finishing the measured work. It includes waiting for I/O, sleeps, scheduler delays, locks, and other periods when a process is not consuming CPU. user is CPU time spent executing application instructions, and sys is CPU time spent in the operating system on behalf of the process or its accounted children.

User and system CPU seconds can add up to more than elapsed time when multiple processes run on multiple cores at once. A pipeline with two active stages may use CPU concurrently. The %P field in both Bash TIMEFORMAT and GNU Time is derived from (user + system) / real; it is a utilization ratio, not a universal performance score. CPU time near zero with a long real time often points to waiting or a blocked stage, not a broken timer.

These figures answer different questions from a profiler. time does not tell which function or pipeline stage consumed each millisecond, prove that the run was representative, or impose a deadline. Use a profiler or per-stage instrumentation when attribution is required.

Bash’s time reserved word covers the pipeline

In Bash, the reserved word is parsed before a pipeline:

set -o pipefail
TIMEFORMAT='real=%3R user=%3U sys=%3S cpu=%P%%'

time awk 'BEGIN { for (i = 0; i < 500000; i++) s += i; print s }' | wc -l
pipeline_status=$?

printf 'pipeline_status=%s\n' "$pipeline_status"

Bash prints timing statistics after the foreground pipeline completes. It can time shell builtins, functions, and pipelines, not just a separate executable. TIMEFORMAT controls Bash’s output; %R, %U, and %S select elapsed, user, and system seconds, while %P is the CPU percentage. In the example, %% emits a literal percent sign.

pipefail affects the pipeline’s exit status, not its timing. Without it, Bash returns the final stage’s status by default: a successful wc can hide an earlier awk error. With pipefail, the timed pipeline reports a nonzero status when an earlier stage fails. Save $? immediately if you need the result; a later logging command would replace it.

The timing report goes to standard error, separate from the pipeline’s standard output. A redirection that discards or captures standard error can hide the report or mix it with program diagnostics. For stable automation, write timing output to a deliberate log channel and keep it distinct from data being consumed downstream.

This syntax is Bash-specific. In interactive shells, the displayed command may be a reserved word, alias, function, or executable depending on the shell and parser context. In Bash, type -a time helps reveal the available resolution. Do not assume the output format or option parsing from another shell applies to Bash.

GNU Time 1.10 is an external command wrapper

The GNU program has options such as -f and -o; Bash’s reserved word does not provide GNU Time’s resource report. Confirm that time resolves to GNU Time before using these flags:

env time --version

GNU’s manual recommends this form to identify the external implementation. It is especially useful when a shell has its own time syntax or a system supplies a different executable. On macOS, for example, /usr/bin/time is not GNU Time; GNU Time may be installed separately under another name.

To measure the wall duration of a full pipeline with GNU Time, make a shell run that pipeline as the command being timed:

env time -f 'real=%e user=%U sys=%S cpu=%P%%' \
  bash --noprofile --norc -o pipefail -c \
  'awk '\''BEGIN { for (i = 0; i < 500000; i++) s += i; print s }'\'' | wc -l'

Here the external utility starts one Bash process, and that shell runs the foreground pipeline before exiting. The GNU format escapes come from GNU Time 1.10, not Bash’s TIMEFORMAT. Use a reviewed, fixed script body in bash -c; do not interpolate untrusted text into it. If inputs are variable, pass them as positional arguments or use a script file with explicit argument validation.

GNU Time reports its statistics separately from the command’s ordinary output, normally on standard error; -o FILE can direct the report to a file. A plain form such as env time -f ... producer | consumer measures the external producer command, not the whole pipeline to its right. Wrapping the pipeline in a shell makes the pipeline’s wall duration the shell command’s duration. Resource-accounting details for descendants still depend on the operating system and whether the shell waits for them; do not treat detached background work as part of a foreground timing contract.

The GNU %e field is elapsed seconds, %U user CPU seconds, %S system CPU seconds, and %P the CPU percentage based on user plus system divided by elapsed time. GNU Time can report additional resource data, but some systems do not provide every field; its manual notes that unavailable resource information may appear as zero. A zero is not proof that the resource was unused.

POSIX does not erase implementation boundaries

The POSIX.1-2024 time utility specifies elapsed real time and user/system CPU time, with a portable -p output format. It does not grant uniform behavior to every shell’s reserved word or direct utility invocation: when the unquoted word time is the command name of a simple command that includes redirections or is directly part of a pipeline, results (including parsing later words) are unspecified. The specification says these limitations can be avoided by quoting the word, arranging for the command name not to be time (for example, through expansion or by invoking it with env or command), or applying redirections/pipelines to a surrounding compound or grouping command. Keep that utility contract distinct from Bash’s own reserved-word timing grammar.

The POSIX utility is not a promise that GNU’s -f format, memory fields, or every shell’s reserved-word behavior will exist on another platform. If portable output is a requirement, use the specified format and test the target shell/utility pair. If the requirement is specifically “time every stage of this Bash pipeline,” use Bash’s reserved word and document Bash as a dependency.

Diagnose results without over-reading them

If real is high and CPU time low, inspect blocking I/O, network waits, lock contention, and whether one pipeline stage is waiting for another. If user plus system time exceeds real, parallel CPU work is plausible; it is not evidence of a clock error. If the total changes substantially from run to run, control input size, warm-up, cache state, CPU contention, power policy, and environment before comparing builds.

Timing output also does not determine whether the command succeeded. Check the pipeline’s exit status separately, enable pipefail where Bash semantics are intended, and test both an upstream failure and a successful run. An empty consumer output may be valid data, while a zero exit code can still hide a semantic error.

For repeatable measurements, state whether the number represents an entire Bash pipeline, one external command, or a shell wrapper; record the shell and GNU Time versions, the exact workload, environment, and whether background work is excluded. Use elapsed time for user-visible latency, CPU time for consumed processing effort, and a profiler for attribution. Keeping those contracts separate makes a short time report much harder to misinterpret.

The Bash example completed locally under Bash 3.2.57 on macOS 27.0.1, with pipefail enabled and the pipeline status preserved. The local /usr/bin/time was Apple’s BSD-style utility, so GNU Time 1.10 flags and the external wrapper example were not executed on this host; their syntax and format fields were checked against the GNU Time 1.10 manual.

Related:

Sources:

Comments