JOBS(1) User Commands JOBS(1)

jobs, fg, bg, stop, notify - control process execution 

jobs [-l]


fg [% job_id]


bg [% job_id]...


notify [% job_id]...


stop % job_id...


stop pid...


jobs [-lnp] [job_id...]


fg [job_id...]


bg [job_id...]

The C shell built-in, jobs, without an argument, lists the active jobs under job control.

-l

List process IDs, in addition to the normal information.

The shell associates a numbered job_id with each command sequence to keep track of those commands that are running in the background or have been stopped with TSTP signals (typically Control-Z). When a command or command sequence (semicolon-separated list) is started in the background using the & metacharacter, the shell displays a line with the job number in brackets and a list of associated process numbers:

[1] 1234

To see the current list of jobs, use the jobs built-in command. The job most recently stopped (or put into the background if none are stopped) is referred to as the current job and is indicated with a `+'. The previous job is indicated with a `−'; when the current job is terminated or moved to the foreground, this job takes its place (becomes the new current job).

To manipulate jobs, refer to the bg, fg, kill, stop, and % built-in commands.

A reference to a job begins with a `%'. By itself, the percent sign refers to the current job.

% %+ %%

The current job.

%−

The previous job.

%j

Refer to job j as in: `kill -9 %j'. j can be a job number, or a string that uniquely specifies the command line by which it was started; `fg %vi' might bring a stopped vi job to the foreground, for instance.

%?string

Specify the job for which the command line uniquely contains string.

A job running in the background stops when it attempts to read from the terminal. Background jobs can normally produce output, but this can be suppressed using the `stty tostop' command.

fg brings the current or specified job_id into the foreground.

bg runs the current or specified jobs in the background.

stop stops the execution of a background job(s) by using its job_id, or of any process by using its pid; see ps(1).

notify notifies the user asynchronously when the status of the current job or specified jobs changes.

jobs displays information about specified jobs that were started by the current shell environment on standard output. The information contains the job number enclosed in [...], the status, and the command line that started the job.

If job_id is omitted, jobs displays the status of all stopped jobs, background jobs, and all jobs whose status has changed since last reported by the shell.

When jobs reports the termination status of a job, the shell removes the job from the list of known jobs in the current shell environment.

The following options modify or enhances the output of jobs:

-l

Displays process IDs after the job number in addition to the usual information.

-n

Displays only the jobs whose status has changed since the last prompt was displayed.

-p

Displays the process group leader IDs for the specified jobs.

job_id can be specified to jobs, fg, and bg as one of the following:

number

The process id of job.

-number

The process group id of job.

%number

The job number.

%string

The job whose name begins with string.

%?string

The job whose name contains string.

%+
%%

The current job.

%-

The previous job.

fg places the specified jobs into the foreground in sequence and sends a CONT signal to start each running. If job_id is omitted, the most recently started or stopped background job is moved to the foreground.

bg places the specified jobs into the background and sends a CONT signal to start them running. If job_id is omitted, the most recently started or stopped background job is resumed or continued in the background.

If the -p option is specified, the output consists of one line for each process ID:

"%d\n", "process ID"

Otherwise, if the -l option is not specified, the output is a series of lines of the form:

"[%d] %c %s %s\n", job-number, current, state, command

where the fields are as follows:

current

The character + identifies the job that would be used as a default for the fg or bg commands. This job can also be specified using the job_id %+ or %% . The character − identifies the job that would become the default if the current default job were to exit; this job can also be specified using the job_id %− . For other jobs, this field is a space character. At most, one job can be identified with + and at most one job can be identified with −. If there is any suspended job, then the current job is a suspended job. If there are at least two suspended jobs, then the previous job is also a suspended job.

job-number

A number that can be used to identify the process group to the wait, fg, bg, and kill utilities. Using these utilities, the job can be identified by prefixing the job number with %.

state

One of the following strings in the POSIX Locale:

Running

Indicates that the job has not been suspended by a signal and has not exited.

Done

Indicates that the job completed and returned exit status zero.

Done(code)

Indicates that the job completed normally and that it exited with the specified non-zero exit status, code, expressed as a decimal number.

Stopped

Indicates that the job was stopped.

Stopped(SIGTSTP)

Indicates that the job was suspended by the SIGTSTP signal.

Stopped(SIGSTOP)

Indicates that the job was suspended by the SIGSTOP signal.

Stopped(SIGTTIN)

Indicates that the job was suspended by the SIGTTIN signal.

Stopped(SIGTTOU)

Indicates that the job was suspended by the SIGTTOU signal.

The implementation can substitute the string Suspended in place of Stopped. If the job was terminated by a signal, the format of state is unspecified, but it is visibly distinct from all of the other state formats shown here and indicates the name or description of the signal causing the termination.

command

The associated command that was specified to the shell.

If the -l option is specified, a field containing the process group ID is inserted before the state field. Also, more processes in a process group can be output on separate lines, using only the process ID and command fields.

See environ(5) for descriptions of the following environment variables that affect the execution of jobs, fg, and bg: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

The following exit values are returned for jobs, fg, and bg:

0

Successful completion.

>0

An error occurred.

The following exit values are returned for jobs:

0

The information for each job is written to standard output.

>0

One or more jobs does not exist.

The following exit values are returned for fg:

exit status of last job

One or more jobs has been brought into the foreground.

non-zero

One or more jobs does not exist or has completed.

The following exit values are returned for bg:

0

All background jobs are started.

>0

One more jobs does not exist or there are no background jobs.

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Committed
Standard See standards(5).

ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Uncommitted

csh(1), kill(1), ksh93(1), ps(1), stop(1), shell_builtins(1), stty(1), wait(1), signal.h(3HEAD), attributes(5), environ(5), standards(5)
February 9, 2021