stop man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

JOBS(1)								       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 corre‐
	     sponding  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 condi‐
		  tional   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 sig‐
		  nal.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 iden‐
       tifier 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-cur‐
       rent 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 con‐
		    tains 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 back‐
       ground 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 pre‐
       vious 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 con‐
		   tains 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  dis‐
       played.

       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 noti‐
	     fied.

       -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 num‐
       bers. 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 num‐
       ber 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 OUT‐
       PUT 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  immedi‐
       ately 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  nor‐
       mally  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 immedi‐
       ately 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 fore‐
       ground. Using fg to place a job in the foreground removes  its  process
       ID from the list of those known in the current shell execution environ‐
       ment. The fg command is available only on systems that support job con‐
       trol.  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  sig‐
       nal  to	start  them  running.  If job_id is omitted, the most recently
       started or stopped background job is resumed or continued in the	 back‐
       ground.

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 iden‐
		     tified 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 nor‐
					 mally 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 caus‐
		     ing 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(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.

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 com‐
				  pleted.

       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
       See attributes(5) for descriptions of the following attributes:

   csh, sh, ksh
       ┌────────────────────┬───────────────────┐
       │  ATTRIBUTE TYPE    │  ATTRIBUTE VALUE	│
       ├────────────────────┼───────────────────┤
       │Interface Stability │ Committed		│
       ├────────────────────┼───────────────────┤
       │Standard	    │ See standards(5). │
       └────────────────────┴───────────────────┘

   ksh93
       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Uncommitted     │
       └────────────────────┴─────────────────┘

SEE ALSO
       csh(1),	 kill(1),   ksh(1),   ksh93(1),	  ps(1),    sh(1),    stop(1),
       shell_builtins(1),  stty(1),  wait(1),  signal.h(3HEAD), attributes(5),
       environ(5), standards(5)

				  Nov 2, 2007			       JOBS(1)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net