> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bash Timed Pipeline
A Bash timed pipeline utilizes the `time` reserved word to measure and report the execution time and system resource utilization of a command pipeline. Because `time` is a shell keyword rather than an external executable (like `/usr/bin/time`), it evaluates the entire pipeline's execution context, waiting for all constituent commands to terminate before calculating the aggregate resource usage.
## Syntax
```bash theme={"dark"}
time [-p] command1 | command2 | ...
```
* `-p`: Forces the output to conform to the POSIX standard format.
## Execution Mechanics
When the `time` keyword precedes a pipeline, Bash alters its standard execution flow:
1. **Process Spawning:** Bash spawns subshells for the commands in the pipeline.
2. **Blocking:** The shell blocks and waits for the termination of *all* processes within the pipeline, regardless of their individual exit statuses.
3. **Aggregation:** Bash aggregates the timing statistics from the kernel for all processes in the pipeline.
4. **Output Routing:** The timing statistics are written directly to standard error (`stderr`), bypassing standard output (`stdout`). This ensures the timing data does not interfere with the pipeline's standard data stream.
5. **Exit Status:** The exit status of the timed pipeline is the exit status of the pipeline itself (typically the exit status of the last command, unless `set -o pipefail` is active).
## Redirection Mechanics
Because `time` is a shell reserved word, standard file descriptor redirection applied at the end of a pipeline affects only the commands within the pipeline, not the `time` keyword itself. For example, executing `time command1 | command2 2> time.txt` redirects the standard error of `command2`, but the timing statistics generated by `time` will bypass this redirection and print directly to the terminal.
To successfully redirect the standard error output of the `time` keyword, the entire timed pipeline must be enclosed within a command group or a subshell. The redirection is then applied to the enclosing structure:
```bash theme={"dark"}
# Redirecting using a command group (executes in the current shell environment)
{ time command1 | command2; } 2> time.txt
# Redirecting using a subshell (spawns a child process)
(time command1 | command2) 2> time.txt
```
## Reported Metrics
By default, the `time` keyword reports three specific metrics:
* **real:** Wall-clock time elapsed from the pipeline's invocation to its complete termination.
* **user:** Total amount of CPU time spent executing in user space across all processes in the pipeline.
* **sys:** Total amount of CPU time spent executing in kernel space (system calls) across all processes in the pipeline.
*Note: In a multi-core system, the sum of `user` and `sys` time can exceed the `real` time if the pipeline's constituent commands execute concurrently on different CPU cores.*
## Output Formatting
The output format of the `time` keyword is controlled by the `TIMEFORMAT` shell variable. It does not need to be exported to the environment for the `time` reserved word to recognize and use it. If `TIMEFORMAT` is unset, Bash uses a default human-readable format.
The variable accepts format specifiers prefixed with `%`:
```bash theme={"dark"}
# Customizing TIMEFORMAT to output specific metrics
TIMEFORMAT="Real: %R, User: %U, Sys: %S, CPU: %P%%"
time command1 | command2
```
Common `TIMEFORMAT` specifiers:
* `%R`: Elapsed real time in seconds.
* `%U`: Number of CPU seconds spent in user mode.
* `%S`: Number of CPU seconds spent in system mode.
* `%P`: CPU percentage, computed as `(%U + %S) / %R`.
## Keyword vs. External Command
The distinction between the Bash keyword and the external binary is critical when evaluating pipelines.
```bash theme={"dark"}
# Bash keyword: Times the entire pipeline (command1 AND command2)
time command1 | command2
# External binary: Times ONLY command1.
# A standard pipe (|) only redirects stdout. The stderr output of /usr/bin/time
# (which contains the timing statistics) is not redirected by the pipe and
# will print directly to the terminal, while command1's stdout goes to command2.
/usr/bin/time command1 | command2
```
To force the external binary to time an entire pipeline, the pipeline must be explicitly wrapped in a subshell or a new shell instance:
```bash theme={"dark"}
/usr/bin/time sh -c 'command1 | command2'
```
Tired of Poor Bash Skills? Fix That With Deep Grasping!
Learn More
