Tribblix: manual page: jobs.1

JOBS(1) User Commands JOBS(1)

NAME

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

SYNOPSIS

sh
jobs [-p | -l] [% job_id...]

jobs -x command [arguments]

fg [% job_id...]

bg [% job_id...]

stop % job_id...

stop pid...

csh
jobs [-l]

fg [% job_id]

bg [% job_id]...

notify [% job_id]...

stop % job_id...

stop pid...

ksh
jobs [-lnp] [% job_id...]

fg [% job_id...]

bg [% job_id...]

stop % job_id...

stop pid...

ksh93
jobs [-lnp] [job_id...]

fg [job_id...]

bg [job_id...]

DESCRIPTION

sh
When Job Control is enabled, the Bourne shell built-in jobs reports
all jobs that are stopped or executing in the background. If %job_id
is omitted, all jobs that are stopped or running in the background is
reported. The following options modify or enhance the output of
jobs:

-l
Reports the process group ID and working directory of the jobs.

-p
Reports only the process group ID of the jobs.

-x
Replaces any job_id found in command or arguments with the
corresponding process group ID, and then executes command
passing it arguments.

When the shell is invoked as jsh, Job Control is enabled in addition
to all of the functionality described previously for sh. Typically
Job Control is enabled for the interactive shell only. Non-
interactive shells typically do not benefit from the added
functionality of Job Control.

With Job Control enabled every command or pipeline the user enters at
the terminal is called a job_id. All jobs exist in one of the
following states: foreground, background or stopped. These terms are
defined as follows:

1. A job in the foreground has read and write access to the
controlling terminal.

2. A job in the background is denied read access and has
conditional write access to the controlling terminal (see
stty(1))

3. A stopped job is a job that has been placed in a suspended
state, usually as a result of a SIGTSTP signal (see
signal.h(3HEAD)).

Every job that the shell starts is assigned a positive integer,
called a job_id number which is tracked by the shell and are used as
an identifier to indicate a specific job. Additionally, the shell
keeps track of the current and previous jobs. The current job is the
most recent job to be started or restarted. The previous job is the
first non-current job.

The acceptable syntax for a Job Identifier is of the form:

%job_id

where job_id can be specified in any of the following formats:

% or +
for the current job

-
for the previous job

?<string>
specify the job for which the command line uniquely
contains string.

n
for job number n, where n is a job number

pref
where pref is a unique prefix of the command name (for
example, if the command ls -l name were running in the
background, it could be referred to as %ls); pref cannot
contain blanks unless it is quoted.

When Job Control is enabled, fg resumes the execution of a stopped
job in the foreground, also moves an executing background job into
the foreground. If %job_id is omitted the current job is assumed.

When Job Control is enabled, bg resumes the execution of a stopped
job in the background. If %job_id is omitted the current job is
assumed.

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).

csh
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.

ksh
jobs displays the status of the jobs that were started in the current
shell environment. When jobs reports the termination status of a job,
the shell removes its process ID from the list of those known in the
current shell execution environment.

job_id specifies the jobs for which the status is to be displayed. If
no job_id is specified, the status information for all jobs are
displayed.

The following options modify or enhance the output of jobs:

-l
(The letter ell.) Provides more information about each job
listed. This information includes the job number, current job,
process group ID, state and the command that formed the job.

-n
Displays only jobs that have stopped or exited since last
notified.

-p
Displays only the process IDs for the process group leaders of
the selected jobs.

By default, jobs displays the status of all the stopped jobs, running
background jobs, and all jobs whose status has changed and have not
been reported by the shell.

If the monitor option of the set command is turned on, an interactive
shell associates a job with each pipeline. It keeps a table of
current jobs, printed by the jobs command, and assigns them small
integer numbers. When a job is started asynchronously with &, the
shell prints a line which looks like:

[1] 1234

indicating that the job, which was started asynchronously, was job
number 1 and had one (top-level) process, whose process id was 1234.

If you are running a job and wish to do something else you can hit
the key ^Z (Control-Z) which sends a STOP signal to the current job.
The shell then normally indicates that the job has been "Stopped"
(see OUTPUT below), and print another prompt. You can then manipulate
the state of this job, putting it in the background with the bg
command, or run some other commands and then eventually bring the job
back into the foreground with the foreground command fg. A ^Z takes
effect immediately and is like an interrupt, in that pending output
and unread input are discarded when it is typed.

There are several ways to refer to jobs in the shell. A job can be
referred to by the process id of any process of the job or by one of
the following:

%number
The job with the specified number.

%string
Any job whose command line begins with string; works only
in the interactive mode when the history file is active.

%?string
Any job whose command line contains string; works only in
the interactive mode when the history file is active.

%%
Current job.

%+
Equivalent to %%.

%-
Previous job.

The shell learns immediately whenever a process changes state. It
normally informs you whenever a job becomes blocked so that no
further progress is possible, but only just before it prints a
prompt. This is done so that it does not otherwise disturb your work.
When the monitor mode is on, each background job that completes
triggers any trap set for CHLD. When you try to leave the shell while
jobs are running or stopped, you are warned that `You have stopped
(running) jobs.' You can use the jobs command to see what they are.
If you do this or immediately try to exit again, the shell does not
warn you a second time, and the stopped jobs are terminated.

fg moves a background job from the current environment into the
foreground. Using fg to place a job in the foreground removes its
process ID from the list of those known in the current shell
execution environment. The fg command is available only on systems
that support job control. If job_id is not specified, the current job
is brought into the foreground.

bg resumes suspended jobs from the current environment by running
them as background jobs. If the job specified by job_id is already a
running background job, bg has no effect and exits successfully.
Using bg to place a job into the background causes its process ID to
become `known in the current shell execution environment, as if it
had been started as an asynchronous list. The bg command is available
only on systems that support job control. If job_id is not specified,
the current job is placed 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).

ksh93
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.

OUTPUT

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.

ENVIRONMENT VARIABLES

See environ(7) 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.

EXIT STATUS

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

0
Successful completion.

>0
An error occurred.

ksh93
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.

ATTRIBUTES