User Commands jobs(1)
NAME
jobs, fg, bg, stop, notify - control process execution
SYNOPSIS
sh
jobs [-p -l] [% jobid...]
jobs -x command [arguments]
fg [% jobid...]
bg [% jobid...]
stop % jobid...
stop pid...
csh
jobs [-l]
fg [% jobid]
bg [% jobid]...
notify [% jobid]...
stop % jobid...
stop pid...
ksh
jobs [-lnp] [% jobid...]
fg [% jobid...]
bg [% jobid...]
SunOS 5.11 Last change: 2 Nov 2007 1
User Commands jobs(1)
stop % jobid...
stop pid...
ksh93
jobs [-lnp] [jobid...]
fg [jobid...]
bg [jobid...]
DESCRIPTION
sh
When Job Control is enabled, the Bourne shell built-in jobs
reports all jobs that are stopped or executing in the back-
ground. If %jobid 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 jobid 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 jobid. 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.
SunOS 5.11 Last change: 2 Nov 2007 2
User Commands jobs(1)
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 jobid 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:
%jobid
where jobid can be specified in any of the following for-
mats:
% or ] for the current job
- for the previous job
? 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 back-
ground job into the foreground. If %jobid is omitted the
current job is assumed.
SunOS 5.11 Last change: 2 Nov 2007 3
User Commands jobs(1)
When Job Control is enabled, bg resumes the execution of a
stopped job in the background. If %jobid is omitted the
current job is assumed.
stop stops the execution of a background job(s) by using its
jobid, 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 informa-
tion.
The shell associates a numbered jobid with each command
sequence to keep track of those commands that are running in
the background or have been stopped with TSTP signals (typi-
cally 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 com-
mand. The job most recently stopped (or put into the back-
ground if none are stopped) is referred to as the current
job and is indicated with a `]'. The previous job is indi-
cated 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 per-
cent sign refers to the current job.
% %] %% The current job.
%- The previous job.
SunOS 5.11 Last change: 2 Nov 2007 4
User Commands jobs(1)
%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 fore-
ground, 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 jobid into the fore-
ground.
bg runs the current or specified jobs in the background.
stop stops the execution of a background job(s) by using its
jobid, 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 termi-
nation status of a job, the shell removes its process ID
from the list of those known in the current shell execution
environment.
jobid specifies the jobs for which the status is to be
displayed. If no jobid 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.
SunOS 5.11 Last change: 2 Nov 2007 5
User Commands jobs(1)
-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 pro-
cess 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, put-
ting 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 his-
tory file is active.
SunOS 5.11 Last change: 2 Nov 2007 6
User Commands jobs(1)
%?string Any job whose command line contains string;
works only in the interactive mode when the his-
tory 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
jobid 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
jobid 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 jobid is not
specified, the current job is placed in the background.
stop stops the execution of a background job(s) by using its
jobid, or of any process by using its pid. See ps(1).
SunOS 5.11 Last change: 2 Nov 2007 7
User Commands jobs(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 jobid 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 speci-
fied jobs.
jobid 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.
%]
%%
SunOS 5.11 Last change: 2 Nov 2007 8
User Commands jobs(1)
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 jobid 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 jobid 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 com-
mands. This job can also be specified using
the jobid %] or %% . The character - identi-
fies the job that would become the default if
the current default job were to exit; this job
can also be specified using the jobid %- .
For other jobs, this field is a space charac-
ter. 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.
SunOS 5.11 Last change: 2 Nov 2007 9
User Commands jobs(1)
job-number A number that can be used to identify the pro-
cess group to the wait, fg, bg, and kill util-
ities. 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(SIGTIN) Indicates that the job was
suspended by the SIGTIN
signal.
Stopped(SIGTOU) Indicates that the job was
suspended by the SIGTOU
signal.
The implementation can substitute the string
Suspended in place of Stopped. If the job was
SunOS 5.11 Last change: 2 Nov 2007 10
User Commands jobs(1)
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 sig-
nal causing the termination.
command The associated command that was specified to
the shell.
If the -l option is specified, a field containing the pro-
cess 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(5) for descriptions of the following environment
variables that affect the execution of jobs, fg, and bg:
LANG, LCAL, LCTYPE, LCMESAGES, 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.
SunOS 5.11 Last change: 2 Nov 2007 11
User Commands jobs(1)
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 back-
ground jobs.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
csh, sh, ksh
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
Interface Stability Committed
Standard See standards(5).
ksh93
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
Interface Stability Uncommitted
SEE ALSO
csh(1), kill(1), ksh(1), ksh93(1), ps(1), sh(1), stop(1),
shellbuiltins(1), stty(1), wait(1), signal.h(3HEAD), attri-
butes(5), environ(5), standards(5)
SunOS 5.11 Last change: 2 Nov 2007 12
|
