Jobs built-in

The jobs built-in reports job status.

Synopsis

jobs [-l|-p] [job_id…]

See Job control for an overview of job control in yash-rs. The jobs built-in prints information about jobs the shell is currently controlling, one line for each job. The results follow the format specified by the POSIX.

When the built-in reports a finished job (either exited or signaled), it removes the job from the job list.

Format

An example output of the built-in in the default format is:

[1] - Running              cargo build
[2] + Stopped(SIGTSTP)     vim
[3]   Done                 rm -rf /tmp/foo

The first column is the job number in brackets. The second column indicates the current job (+) or the previous job (-). The third column is the job state, which can be one of:

Running: the job is running in the background
Stopped(signal): the job is stopped by signal
Done: the job has finished with an exit status of zero
Done(n): the job has finished with non-zero exit status n
Killed(signal): the job has been killed by signal
Killed(signal: core dumped): the job has been killed by signal and a core dump was produced

The last column is the command line of the job.

Options

You can use two options to change the output.

The -l (--verbose) option displays additional details by inserting the process ID before each job state. The -p (--pgid-only) option outputs only the process ID of each job. In both cases, the process ID shown is that of the main process in the job, which is also the process group ID if the job is under job control.

The two options are mutually exclusive. (Since 3.3.5) Specifying both is an error.

Operands

Each operand is parsed as a job ID that specifies which job to report. If no operands are given, the built-in prints all jobs.

Errors

If an operand does not specify a valid job, the built-in prints an error message to the standard error and returns a non-zero exit status. An ambiguous job ID (matching multiple jobs) is also an error.

(Since 3.3.5) Specifying both the -l and -p options is an error.

The portable option causes additional errors; see Compatibility.

Exit status

Zero if successful, non-zero if an error occurred.

Examples

Job list includes an example of using the jobs built-in to list jobs.

The built-in with different arguments:

$ vim
[1] + Stopped(SIGTSTP)     vim
$ sleep 60 && echo "1 minute elapsed!"&
[2] 38776
$ jobs
[1] + Stopped(SIGTSTP)     vim
[2] - Running              sleep 60 && echo "1 minute elapsed!"
$ jobs -l
[1] + 37424 Stopped(SIGTSTP)     vim
[2] - 38776 Running              sleep 60 && echo "1 minute elapsed!"
$ jobs -p %2
38776

Compatibility

The long option names (--verbose, --pgid-only) are a non-standard extension.

(Since 3.3.5) When the portable option is set, using a long option name is rejected with an error. Use the corresponding short option instead.

The output format may differ between shells. Specifically:

For a job stopped by SIGTSTP, other shells may omit the signal name and simply print Stopped.
Other shells may report stopped jobs as Suspended instead of Stopped.
The job state format for jobs terminated by a signal is implementation-defined.
With the -l option, shells that manage more than one process per job may print an additional line containing the process ID and name for each process in the job.

The current implementation of this built-in removes finished jobs from the job list after reporting all jobs. This behavior should not be relied upon. The following script shows a “job not found” error in many other shells because the built-in removes the job when processing the first operand so the job is gone when the second is processed:

$ sleep 0&
$ jobs %sleep %sleep

When the built-in is used in a subshell, the built-in reports not only jobs that were started in the subshell but also jobs that were started in the parent shell. This behavior is not portable and is subject to change.

The POSIX standard only defines the -l and -p options. Previous versions of yash supported additional options, which are not yet implemented in yash-rs.

POSIX specifies the options as -l|-p and does not define the behavior when both are used together. Other shells accept the combination, but what they do with it varies from shell to shell. (Since 3.3.5) yash-rs has no reason to prefer either option over the other, so it rejects the combination with an error, whichever order or spelling it is written in.

A portable job ID must start with a %. If an operand does not have a leading %, the built-in assumes one silently, which is not portable.

Yash-rs User Manual