1jobs(1)                          User Commands                         jobs(1)
2
3
4

NAME

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

SYNOPSIS

9   sh
10       jobs [-p | -l] [% job_id...]
11
12
13       jobs -x command [arguments]
14
15
16       fg [% job_id...]
17
18
19       bg [% job_id...]
20
21
22       stop % job_id...
23
24
25       stop pid...
26
27
28   csh
29       jobs [-l]
30
31
32       fg [% job_id]
33
34
35       bg [% job_id]...
36
37
38       notify [% job_id]...
39
40
41       stop % job_id...
42
43
44       stop pid...
45
46
47   ksh
48       jobs [-lnp] [% job_id...]
49
50
51       fg [% job_id...]
52
53
54       bg [% job_id...]
55
56
57       stop % job_id...
58
59
60       stop pid...
61
62
63   ksh93
64       jobs [-lnp] [job_id...]
65
66
67       fg [job_id...]
68
69
70       bg [job_id...]
71
72

DESCRIPTION

74   sh
75       When Job Control is enabled, the Bourne shell built-in jobs reports all
76       jobs that are stopped or executing in the  background.  If  %job_id  is
77       omitted,  all  jobs  that  are  stopped or running in the background is
78       reported. The following options modify or enhance the output of jobs:
79
80       -l    Reports the process group ID and working directory of the jobs.
81
82
83       -p    Reports only the process group ID of the jobs.
84
85
86       -x    Replaces any job_id found in command or arguments with the corre‐
87             sponding  process  group ID, and then executes command passing it
88             arguments.
89
90
91
92       When the shell is invoked as jsh, Job Control is enabled in addition to
93       all  of  the  functionality  described previously for sh. Typically Job
94       Control is enabled for  the  interactive  shell  only.  Non-interactive
95       shells  typically  do  not  benefit from the added functionality of Job
96       Control.
97
98
99       With Job Control enabled every command or pipeline the user  enters  at
100       the terminal is called a job_id. All jobs exist in one of the following
101       states: foreground, background or stopped. These terms are  defined  as
102       follows:
103
104           1.     A  job  in  the  foreground has read and write access to the
105                  controlling terminal.
106
107           2.     A job in the background is denied read access and has condi‐
108                  tional   write  access  to  the  controlling  terminal  (see
109                  stty(1))
110
111           3.     A stopped job is a job that has been placed in  a  suspended
112                  state,  usually  as  a  result of a SIGTSTP signal (see sig‐
113                  nal.h(3HEAD)).
114
115
116       Every job that the shell starts is assigned a positive integer,  called
117       a  job_id number which is tracked by the shell and are used as an iden‐
118       tifier to indicate a specific job. Additionally, the shell keeps  track
119       of  the  current  and previous jobs. The current job is the most recent
120       job to be started or restarted. The previous job is the first  non-cur‐
121       rent job.
122
123
124       The acceptable syntax for a Job Identifier is of the form:
125
126
127       %job_id
128
129
130       where job_id can be specified in any of the following formats:
131
132       % or +       for the current job
133
134
135       for the previous job
136
137
138       ?<string>    specify  the  job for which the command line uniquely con‐
139                    tains string.
140
141
142       n            for job number n, where n is a job number
143
144
145       pref         where pref is a unique prefix of  the  command  name  (for
146                    example,  if  the  command  ls −l name were running in the
147                    background, it could be referred to as %ls);  pref  cannot
148                    contain blanks unless it is quoted.
149
150
151
152       When  Job Control is enabled, fg resumes the execution of a stopped job
153       in the foreground, also moves an  executing  background  job  into  the
154       foreground. If %job_id is omitted the current job is assumed.
155
156
157       When  Job Control is enabled, bg resumes the execution of a stopped job
158       in the background. If %job_id is omitted the current job is assumed.
159
160
161       stop stops the execution of a background job(s) by using its job_id, or
162       of any process by using its pid; see ps(1).
163
164   csh
165       The  C shell built-in, jobs, without an argument, lists the active jobs
166       under job control.
167
168       -l    List process IDs, in addition to the normal information.
169
170
171
172       The shell associates a numbered job_id with each  command  sequence  to
173       keep track of those commands that are running in the background or have
174       been stopped with TSTP signals (typically Control-Z). When a command or
175       command  sequence  (semicolon-separated  list)  is started in the back‐
176       ground using the & metacharacter, the shell displays a  line  with  the
177       job number in brackets and a list of associated process numbers:
178
179
180       [1] 1234
181
182
183       To see the current list of jobs, use the jobs built-in command. The job
184       most recently stopped (or put into the background if none are  stopped)
185       is referred to as the current job and is indicated with a `+'. The pre‐
186       vious job is indicated with a `'; when the current job  is  terminated
187       or  moved  to the foreground, this job takes its place (becomes the new
188       current job).
189
190
191       To manipulate jobs, refer to the bg, fg, kill,  stop,  and  %  built-in
192       commands.
193
194
195       A  reference  to  a  job begins with a `%'. By itself, the percent sign
196       refers to the current job.
197
198       % %+ %%     The current job.
199
200
201       %−          The previous job.
202
203
204       %j          Refer to job j as in: `kill -9 %j'. j can be a job  number,
205                   or  a  string  that  uniquely specifies the command line by
206                   which it was started; `fg %vi' might bring a stopped vi job
207                   to the foreground, for instance.
208
209
210       %?string    Specify  the  job  for which the command line uniquely con‐
211                   tains string.
212
213
214
215       A job running in the background stops when it attempts to read from the
216       terminal.  Background jobs can normally produce output, but this can be
217       suppressed using the `stty tostop' command.
218
219
220       fg brings the current or specified job_id into the foreground.
221
222
223       bg runs the current or specified jobs in the background.
224
225
226       stop stops the execution of a background job(s) by using its job_id, or
227       of any process by using its pid; see ps(1).
228
229
230       notify  notifies the user asynchronously when the status of the current
231       job or specified jobs changes.
232
233   ksh
234       jobs displays the status of the jobs that were started in  the  current
235       shell  environment.  When jobs reports the termination status of a job,
236       the shell removes its process ID from the list of those  known  in  the
237       current shell execution environment.
238
239
240       job_id  specifies  the jobs for which the status is to be displayed. If
241       no job_id is specified, the status information for all  jobs  are  dis‐
242       played.
243
244
245       The following options modify or enhance the output of jobs:
246
247       -l    (The  letter  ell.)  Provides  more  information  about  each job
248             listed. This information includes the job  number,  current  job,
249             process group ID, state and the command that formed the job.
250
251
252       -n    Displays  only  jobs that have stopped or exited since last noti‐
253             fied.
254
255
256       -p    Displays only the process IDs for the process  group  leaders  of
257             the selected jobs.
258
259
260
261       By  default,  jobs displays the status of all the stopped jobs, running
262       background jobs, and all jobs whose status has  changed  and  have  not
263       been reported by the shell.
264
265
266       If  the  monitor option of the set command is turned on, an interactive
267       shell associates a job with each pipeline. It keeps a table of  current
268       jobs,  printed by the jobs command, and assigns them small integer num‐
269       bers. When a job is started asynchronously with &, the shell  prints  a
270       line which looks like:
271
272
273       [1] 1234
274
275
276       indicating that the job, which was started asynchronously, was job num‐
277       ber 1 and had one (top-level) process, whose process id was 1234.
278
279
280       If you are running a job and wish to do something else you can hit  the
281       key  ^Z  (Control-Z)  which sends a STOP signal to the current job. The
282       shell then normally indicates that the job has been "Stopped" (see OUT‐
283       PUT below), and print another prompt. You can then manipulate the state
284       of this job, putting it in the background with the bg command,  or  run
285       some  other  commands  and  then eventually bring the job back into the
286       foreground with the foreground command fg. A ^Z  takes  effect  immedi‐
287       ately and is like an interrupt, in that pending output and unread input
288       are discarded when it is typed.
289
290
291       There are several ways to refer to jobs in the  shell.  A  job  can  be
292       referred  to  by  the process id of any process of the job or by one of
293       the following:
294
295       %number     The job with the specified number.
296
297
298       %string     Any job whose command line begins with string;  works  only
299                   in the interactive mode when the history file is active.
300
301
302       %?string    Any  job  whose command line contains string; works only in
303                   the interactive mode when the history file is active.
304
305
306       %%          Current job.
307
308
309       %+          Equivalent to %%.
310
311
312       %−          Previous job.
313
314
315
316       The shell learns immediately whenever a process changes state. It  nor‐
317       mally  informs  you  whenever  a job becomes blocked so that no further
318       progress is possible, but only just before it prints a prompt. This  is
319       done  so that it does not otherwise disturb your work. When the monitor
320       mode is on, each background job that completes triggers  any  trap  set
321       for  CHLD.  When  you  try to leave the shell while jobs are running or
322       stopped, you are warned that `You have stopped (running) jobs.' You can
323       use  the  jobs  command to see what they are. If you do this or immedi‐
324       ately try to exit again, the shell does not warn you a second time, and
325       the stopped jobs are terminated.
326
327
328       fg  moves  a background job from the current environment into the fore‐
329       ground. Using fg to place a job in the foreground removes  its  process
330       ID from the list of those known in the current shell execution environ‐
331       ment. The fg command is available only on systems that support job con‐
332       trol.  If  job_id is not specified, the current job is brought into the
333       foreground.
334
335
336       bg resumes suspended jobs from the current environment by running  them
337       as background jobs. If the job specified by job_id is already a running
338       background job, bg has no effect and exits successfully.  Using  bg  to
339       place  a job into the background causes its process ID to become `known
340       in the current shell execution environment, as if it had  been  started
341       as  an  asynchronous  list. The bg command is available only on systems
342       that support job control. If job_id is not specified, the  current  job
343       is placed in the background.
344
345
346       stop stops the execution of a background job(s) by using its job_id, or
347       of any process by using its pid. See ps(1).
348
349   ksh93
350       jobs displays information about specified jobs that were started by the
351       current  shell environment on standard output. The information contains
352       the job number enclosed in [...], the status, and the command line that
353       started the job.
354
355
356       If  job_id  is  omitted,  jobs displays the status of all stopped jobs,
357       background jobs, and all jobs  whose  status  has  changed  since  last
358       reported by the shell.
359
360
361       When  jobs  reports  the termination status of a job, the shell removes
362       the job from the list of known jobs in the current shell environment.
363
364
365       The following options modify or enhances the output of jobs:
366
367       -l    Displays process IDs after the job  number  in  addition  to  the
368             usual information.
369
370
371       -n    Displays  only  the  jobs whose status has changed since the last
372             prompt was displayed.
373
374
375       -p    Displays the process group leader IDs for the specified jobs.
376
377
378
379       job_id can be specified to jobs, fg, and bg as one of the following:
380
381       number      The process id of job.
382
383
384       -number     The process group id of job.
385
386
387       %number     The job number.
388
389
390       %string     The job whose name begins with string.
391
392
393       %?string    The job whose name contains string.
394
395
396       %+          The current job.
397       %%
398
399       %-          The previous job.
400
401
402
403       fg places the specified jobs into the foreground in sequence and  sends
404       a  CONT  signal  to  start each running. If job_id is omitted, the most
405       recently started or stopped background job is moved to the foreground.
406
407
408       bg places the specified jobs into the background and sends a CONT  sig‐
409       nal  to  start  them  running.  If job_id is omitted, the most recently
410       started or stopped background job is resumed or continued in the  back‐
411       ground.
412

OUTPUT

414       If the -p option is specified, the output consists of one line for each
415       process ID:
416
417
418       "%d\n", "process ID"
419
420
421       Otherwise, if the -l option is not specified, the output is a series of
422       lines of the form:
423
424
425       "[%d] %c %s %s\n", job-number, current, state, command
426
427
428       where the fields are as follows:
429
430       current       The  character + identifies the job that would be used as
431                     a default for the fg or bg commands. This job can also be
432                     specified  using  the  job_id  %+ or %% . The character 
433                     identifies the job that would become the default  if  the
434                     current  default  job  were to exit; this job can also be
435                     specified using the job_id %−  .  For  other  jobs,  this
436                     field is a space character. At most, one job can be iden‐
437                     tified with + and at most one job can be identified  with
438                     . If there is any suspended job, then the current job is
439                     a suspended job. If there  are  at  least  two  suspended
440                     jobs, then the previous job is also a suspended job.
441
442
443       job-number    A  number  that can be used to identify the process group
444                     to the wait, fg, bg,  and  kill  utilities.  Using  these
445                     utilities, the job can be identified by prefixing the job
446                     number with %.
447
448
449       state         One of the following strings in the POSIX Locale:
450
451                     Running             Indicates that the job has  not  been
452                                         suspended  by  a  signal  and has not
453                                         exited.
454
455
456                     Done                Indicates that the job completed  and
457                                         returned exit status zero.
458
459
460                     Done(code)          Indicates that the job completed nor‐
461                                         mally and that  it  exited  with  the
462                                         specified non-zero exit status, code,
463                                         expressed as a decimal number.
464
465
466                     Stopped             Indicates that the job was stopped.
467
468
469                     Stopped(SIGTSTP)    Indicates that the job was  suspended
470                                         by the SIGTSTP signal.
471
472
473                     Stopped(SIGSTOP)    Indicates  that the job was suspended
474                                         by the SIGSTOP signal.
475
476
477                     Stopped(SIGTTIN)    Indicates that the job was  suspended
478                                         by the SIGTTIN signal.
479
480
481                     Stopped(SIGTTOU)    Indicates  that the job was suspended
482                                         by the SIGTTOU signal.
483
484                     The implementation can substitute the string Suspended in
485                     place  of Stopped. If the job was terminated by a signal,
486                     the format of state is unspecified,  but  it  is  visibly
487                     distinct  from  all of the other state formats shown here
488                     and indicates the name or description of the signal caus‐
489                     ing the termination.
490
491
492       command       The associated command that was specified to the shell.
493
494
495
496       If  the -l option is specified, a field containing the process group ID
497       is inserted before the state field. Also, more processes in  a  process
498       group  can  be  output on separate lines, using only the process ID and
499       command fields.
500

ENVIRONMENT VARIABLES

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

EXIT STATUS

507   sh, csh, ksh
508       The following exit values are returned for jobs, fg, and bg:
509
510       0     Successful completion.
511
512
513       >0    An error occurred.
514
515
516   ksh93
517       The following exit values are returned for jobs:
518
519       0     The information for each job is written to standard output.
520
521
522       >0    One or more jobs does not exist.
523
524
525
526       The following exit values are returned for fg:
527
528       exit status of last job    One or more jobs has been brought  into  the
529                                  foreground.
530
531
532       non-zero                   One  or more jobs does not exist or has com‐
533                                  pleted.
534
535
536
537       The following exit values are returned for bg:
538
539       0     All background jobs are started.
540
541
542       >0    One more jobs does not exist or there are no background jobs.
543
544

ATTRIBUTES

546       See attributes(5) for descriptions of the following attributes:
547
548   csh, sh, ksh
549       ┌─────────────────────────────┬─────────────────────────────┐
550       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
551       ├─────────────────────────────┼─────────────────────────────┤
552       │Availability                 │SUNWcsu                      │
553       ├─────────────────────────────┼─────────────────────────────┤
554       │Interface Stability          │Committed                    │
555       ├─────────────────────────────┼─────────────────────────────┤
556       │Standard                     │See standards(5).            │
557       └─────────────────────────────┴─────────────────────────────┘
558
559   ksh93
560       ┌─────────────────────────────┬─────────────────────────────┐
561       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
562       ├─────────────────────────────┼─────────────────────────────┤
563       │Availability                 │SUNWcsu                      │
564       ├─────────────────────────────┼─────────────────────────────┤
565       │Interface Stability          │Uncommitted                  │
566       └─────────────────────────────┴─────────────────────────────┘
567

SEE ALSO

569       csh(1),   kill(1),   ksh(1),   ksh93(1),   ps(1),    sh(1),    stop(1),
570       shell_builtins(1),  stty(1),  wait(1),  signal.h(3HEAD), attributes(5),
571       environ(5), standards(5)
572
573
574
575SunOS 5.11                        2 Nov 2007                           jobs(1)
Impressum