Print this page
13507 some man pages need update following 13405
6308 some man pages are obsolete after moving to ksh builtins
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1/jobs.1.man.txt
+++ new/usr/src/man/man1/jobs.1.man.txt
1 1 JOBS(1) User Commands JOBS(1)
2 2
3 3
4 4
5 5 NAME
6 6 jobs, fg, bg, stop, notify - control process execution
7 7
8 8 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 9 csh
29 10 jobs [-l]
30 11
31 12
32 13 fg [% job_id]
33 14
34 15
35 16 bg [% job_id]...
36 17
37 18
38 19 notify [% job_id]...
39 20
40 21
41 22 stop % job_id...
42 23
43 24
44 25 stop pid...
45 26
46 27
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 28 ksh93
64 29 jobs [-lnp] [job_id...]
65 30
66 31
67 32 fg [job_id...]
68 33
69 34
70 35 bg [job_id...]
71 36
72 37
73 38 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
81 - Reports the process group ID and working directory of the jobs.
82 -
83 -
84 - -p
85 - Reports only the process group ID of the jobs.
86 -
87 -
88 - -x
89 - Replaces any job_id found in command or arguments with the
90 - corresponding process group ID, and then executes command passing
91 - it arguments.
92 -
93 -
94 -
95 - When the shell is invoked as jsh, Job Control is enabled in addition to
96 - all of the functionality described previously for sh. Typically Job
97 - Control is enabled for the interactive shell only. Non-interactive
98 - shells typically do not benefit from the added functionality of Job
99 - Control.
100 -
101 -
102 - With Job Control enabled every command or pipeline the user enters at
103 - the terminal is called a job_id. All jobs exist in one of the following
104 - states: foreground, background or stopped. These terms are defined as
105 - follows:
106 -
107 - 1. A job in the foreground has read and write access to the
108 - controlling terminal.
109 -
110 - 2. A job in the background is denied read access and has
111 - conditional write access to the controlling terminal (see
112 - stty(1))
113 -
114 - 3. A stopped job is a job that has been placed in a suspended
115 - state, usually as a result of a SIGTSTP signal (see
116 - signal.h(3HEAD)).
117 -
118 -
119 - Every job that the shell starts is assigned a positive integer, called
120 - a job_id number which is tracked by the shell and are used as an
121 - identifier to indicate a specific job. Additionally, the shell keeps
122 - track of the current and previous jobs. The current job is the most
123 - recent job to be started or restarted. The previous job is the first
124 - non-current job.
125 -
126 -
127 - The acceptable syntax for a Job Identifier is of the form:
128 -
129 -
130 - %job_id
131 -
132 -
133 - where job_id can be specified in any of the following formats:
134 -
135 - % or +
136 - for the current job
137 -
138 -
139 - -
140 - for the previous job
141 -
142 -
143 - ?<string>
144 - specify the job for which the command line uniquely
145 - contains string.
146 -
147 -
148 - n
149 - for job number n, where n is a job number
150 -
151 -
152 - pref
153 - where pref is a unique prefix of the command name (for
154 - example, if the command ls -l name were running in the
155 - background, it could be referred to as %ls); pref cannot
156 - contain blanks unless it is quoted.
157 -
158 -
159 -
160 - When Job Control is enabled, fg resumes the execution of a stopped job
161 - in the foreground, also moves an executing background job into the
162 - foreground. If %job_id is omitted the current job is assumed.
163 -
164 -
165 - When Job Control is enabled, bg resumes the execution of a stopped job
166 - in the background. If %job_id is omitted the current job is assumed.
167 -
168 -
169 - stop stops the execution of a background job(s) by using its job_id, or
170 - of any process by using its pid; see ps(1).
171 -
172 39 csh
173 40 The C shell built-in, jobs, without an argument, lists the active jobs
174 41 under job control.
175 42
176 43 -l
177 44 List process IDs, in addition to the normal information.
178 45
179 46
180 47
181 48 The shell associates a numbered job_id with each command sequence to
182 49 keep track of those commands that are running in the background or have
183 50 been stopped with TSTP signals (typically Control-Z). When a command or
184 51 command sequence (semicolon-separated list) is started in the
185 52 background using the & metacharacter, the shell displays a line with
186 53 the job number in brackets and a list of associated process numbers:
187 54
188 55
189 56 [1] 1234
190 57
191 58
192 59 To see the current list of jobs, use the jobs built-in command. The job
193 60 most recently stopped (or put into the background if none are stopped)
194 61 is referred to as the current job and is indicated with a `+'. The
195 62 previous job is indicated with a `-'; when the current job is
196 63 terminated or moved to the foreground, this job takes its place
197 64 (becomes the new current job).
198 65
199 66
200 67 To manipulate jobs, refer to the bg, fg, kill, stop, and % built-in
201 68 commands.
202 69
203 70
204 71 A reference to a job begins with a `%'. By itself, the percent sign
205 72 refers to the current job.
206 73
207 74 % %+ %%
208 75 The current job.
209 76
210 77
211 78 %-
212 79 The previous job.
213 80
214 81
215 82 %j
216 83 Refer to job j as in: `kill -9 %j'. j can be a job number,
217 84 or a string that uniquely specifies the command line by
218 85 which it was started; `fg %vi' might bring a stopped vi job
219 86 to the foreground, for instance.
220 87
221 88
222 89 %?string
223 90 Specify the job for which the command line uniquely
224 91 contains string.
225 92
226 93
227 94
228 95 A job running in the background stops when it attempts to read from the
229 96 terminal. Background jobs can normally produce output, but this can be
230 97 suppressed using the `stty tostop' command.
231 98
232 99
233 100 fg brings the current or specified job_id into the foreground.
234 101
235 102
|
↓ open down ↓ |
54 lines elided |
↑ open up ↑ |
236 103 bg runs the current or specified jobs in the background.
237 104
238 105
239 106 stop stops the execution of a background job(s) by using its job_id, or
240 107 of any process by using its pid; see ps(1).
241 108
242 109
243 110 notify notifies the user asynchronously when the status of the current
244 111 job or specified jobs changes.
245 112
246 - ksh
247 - jobs displays the status of the jobs that were started in the current
248 - shell environment. When jobs reports the termination status of a job,
249 - the shell removes its process ID from the list of those known in the
250 - current shell execution environment.
251 -
252 -
253 - job_id specifies the jobs for which the status is to be displayed. If
254 - no job_id is specified, the status information for all jobs are
255 - displayed.
256 -
257 -
258 - The following options modify or enhance the output of jobs:
259 -
260 - -l
261 - (The letter ell.) Provides more information about each job
262 - listed. This information includes the job number, current job,
263 - process group ID, state and the command that formed the job.
264 -
265 -
266 - -n
267 - Displays only jobs that have stopped or exited since last
268 - notified.
269 -
270 -
271 - -p
272 - Displays only the process IDs for the process group leaders of
273 - the selected jobs.
274 -
275 -
276 -
277 - By default, jobs displays the status of all the stopped jobs, running
278 - background jobs, and all jobs whose status has changed and have not
279 - been reported by the shell.
280 -
281 -
282 - If the monitor option of the set command is turned on, an interactive
283 - shell associates a job with each pipeline. It keeps a table of current
284 - jobs, printed by the jobs command, and assigns them small integer
285 - numbers. When a job is started asynchronously with &, the shell prints
286 - a line which looks like:
287 -
288 -
289 - [1] 1234
290 -
291 -
292 - indicating that the job, which was started asynchronously, was job
293 - number 1 and had one (top-level) process, whose process id was 1234.
294 -
295 -
296 - If you are running a job and wish to do something else you can hit the
297 - key ^Z (Control-Z) which sends a STOP signal to the current job. The
298 - shell then normally indicates that the job has been "Stopped" (see
299 - OUTPUT below), and print another prompt. You can then manipulate the
300 - state of this job, putting it in the background with the bg command, or
301 - run some other commands and then eventually bring the job back into the
302 - foreground with the foreground command fg. A ^Z takes effect
303 - immediately and is like an interrupt, in that pending output and unread
304 - input are discarded when it is typed.
305 -
306 -
307 - There are several ways to refer to jobs in the shell. A job can be
308 - referred to by the process id of any process of the job or by one of
309 - the following:
310 -
311 - %number
312 - The job with the specified number.
313 -
314 -
315 - %string
316 - Any job whose command line begins with string; works only
317 - in the interactive mode when the history file is active.
318 -
319 -
320 - %?string
321 - Any job whose command line contains string; works only in
322 - the interactive mode when the history file is active.
323 -
324 -
325 - %%
326 - Current job.
327 -
328 -
329 - %+
330 - Equivalent to %%.
331 -
332 -
333 - %-
334 - Previous job.
335 -
336 -
337 -
338 - The shell learns immediately whenever a process changes state. It
339 - normally informs you whenever a job becomes blocked so that no further
340 - progress is possible, but only just before it prints a prompt. This is
341 - done so that it does not otherwise disturb your work. When the monitor
342 - mode is on, each background job that completes triggers any trap set
343 - for CHLD. When you try to leave the shell while jobs are running or
344 - stopped, you are warned that `You have stopped (running) jobs.' You can
345 - use the jobs command to see what they are. If you do this or
346 - immediately try to exit again, the shell does not warn you a second
347 - time, and the stopped jobs are terminated.
348 -
349 -
350 - fg moves a background job from the current environment into the
351 - foreground. Using fg to place a job in the foreground removes its
352 - process ID from the list of those known in the current shell execution
353 - environment. The fg command is available only on systems that support
354 - job control. If job_id is not specified, the current job is brought
355 - into the foreground.
356 -
357 -
358 - bg resumes suspended jobs from the current environment by running them
359 - as background jobs. If the job specified by job_id is already a running
360 - background job, bg has no effect and exits successfully. Using bg to
361 - place a job into the background causes its process ID to become `known
362 - in the current shell execution environment, as if it had been started
363 - as an asynchronous list. The bg command is available only on systems
364 - that support job control. If job_id is not specified, the current job
365 - is placed in the background.
366 -
367 -
368 - stop stops the execution of a background job(s) by using its job_id, or
369 - of any process by using its pid. See ps(1).
370 -
371 113 ksh93
372 114 jobs displays information about specified jobs that were started by the
373 115 current shell environment on standard output. The information contains
374 116 the job number enclosed in [...], the status, and the command line that
375 117 started the job.
376 118
377 119
378 120 If job_id is omitted, jobs displays the status of all stopped jobs,
379 121 background jobs, and all jobs whose status has changed since last
380 122 reported by the shell.
381 123
382 124
383 125 When jobs reports the termination status of a job, the shell removes
384 126 the job from the list of known jobs in the current shell environment.
385 127
386 128
387 129 The following options modify or enhances the output of jobs:
388 130
389 131 -l
390 132 Displays process IDs after the job number in addition to the
391 133 usual information.
392 134
393 135
394 136 -n
395 137 Displays only the jobs whose status has changed since the last
396 138 prompt was displayed.
397 139
398 140
399 141 -p
400 142 Displays the process group leader IDs for the specified jobs.
401 143
402 144
403 145
404 146 job_id can be specified to jobs, fg, and bg as one of the following:
405 147
406 148 number
407 149 The process id of job.
408 150
409 151
410 152 -number
411 153 The process group id of job.
412 154
413 155
414 156 %number
415 157 The job number.
416 158
417 159
418 160 %string
419 161 The job whose name begins with string.
420 162
421 163
422 164 %?string
423 165 The job whose name contains string.
424 166
425 167
426 168 %+
427 169 %%
428 170 The current job.
429 171
430 172
431 173 %-
432 174 The previous job.
433 175
434 176
435 177
436 178 fg places the specified jobs into the foreground in sequence and sends
437 179 a CONT signal to start each running. If job_id is omitted, the most
438 180 recently started or stopped background job is moved to the foreground.
439 181
440 182
441 183 bg places the specified jobs into the background and sends a CONT
442 184 signal to start them running. If job_id is omitted, the most recently
443 185 started or stopped background job is resumed or continued in the
444 186 background.
445 187
446 188 OUTPUT
447 189 If the -p option is specified, the output consists of one line for each
448 190 process ID:
449 191
450 192
451 193 "%d\n", "process ID"
452 194
453 195
454 196 Otherwise, if the -l option is not specified, the output is a series of
455 197 lines of the form:
456 198
457 199
458 200 "[%d] %c %s %s\n", job-number, current, state, command
459 201
460 202
461 203 where the fields are as follows:
462 204
463 205 current
464 206 The character + identifies the job that would be used as
465 207 a default for the fg or bg commands. This job can also be
466 208 specified using the job_id %+ or %% . The character -
467 209 identifies the job that would become the default if the
468 210 current default job were to exit; this job can also be
469 211 specified using the job_id %- . For other jobs, this
470 212 field is a space character. At most, one job can be
471 213 identified with + and at most one job can be identified
472 214 with -. If there is any suspended job, then the current
473 215 job is a suspended job. If there are at least two
474 216 suspended jobs, then the previous job is also a suspended
475 217 job.
476 218
477 219
478 220 job-number
479 221 A number that can be used to identify the process group
480 222 to the wait, fg, bg, and kill utilities. Using these
481 223 utilities, the job can be identified by prefixing the job
482 224 number with %.
483 225
484 226
485 227 state
486 228 One of the following strings in the POSIX Locale:
487 229
488 230 Running
489 231 Indicates that the job has not been
490 232 suspended by a signal and has not
491 233 exited.
492 234
493 235
494 236 Done
495 237 Indicates that the job completed and
496 238 returned exit status zero.
497 239
498 240
499 241 Done(code)
500 242 Indicates that the job completed
501 243 normally and that it exited with the
502 244 specified non-zero exit status, code,
503 245 expressed as a decimal number.
504 246
505 247
506 248 Stopped
507 249 Indicates that the job was stopped.
508 250
509 251
510 252 Stopped(SIGTSTP)
511 253 Indicates that the job was suspended
512 254 by the SIGTSTP signal.
513 255
514 256
515 257 Stopped(SIGSTOP)
516 258 Indicates that the job was suspended
517 259 by the SIGSTOP signal.
518 260
519 261
520 262 Stopped(SIGTTIN)
521 263 Indicates that the job was suspended
522 264 by the SIGTTIN signal.
523 265
524 266
525 267 Stopped(SIGTTOU)
526 268 Indicates that the job was suspended
527 269 by the SIGTTOU signal.
528 270
529 271 The implementation can substitute the string Suspended in
530 272 place of Stopped. If the job was terminated by a signal,
531 273 the format of state is unspecified, but it is visibly
532 274 distinct from all of the other state formats shown here
533 275 and indicates the name or description of the signal
534 276 causing the termination.
535 277
536 278
537 279 command
538 280 The associated command that was specified to the shell.
539 281
540 282
541 283
542 284 If the -l option is specified, a field containing the process group ID
|
↓ open down ↓ |
162 lines elided |
↑ open up ↑ |
543 285 is inserted before the state field. Also, more processes in a process
544 286 group can be output on separate lines, using only the process ID and
545 287 command fields.
546 288
547 289 ENVIRONMENT VARIABLES
548 290 See environ(5) for descriptions of the following environment variables
549 291 that affect the execution of jobs, fg, and bg: LANG, LC_ALL, LC_CTYPE,
550 292 LC_MESSAGES, and NLSPATH.
551 293
552 294 EXIT STATUS
553 - sh, csh, ksh
295 + csh
554 296 The following exit values are returned for jobs, fg, and bg:
555 297
556 298 0
557 299 Successful completion.
558 300
559 301
560 302 >0
561 303 An error occurred.
562 304
563 305
564 306 ksh93
565 307 The following exit values are returned for jobs:
566 308
567 309 0
568 310 The information for each job is written to standard output.
569 311
570 312
571 313 >0
572 314 One or more jobs does not exist.
573 315
574 316
575 317
576 318 The following exit values are returned for fg:
577 319
578 320 exit status of last job
579 321 One or more jobs has been brought into the
580 322 foreground.
581 323
582 324
583 325 non-zero
584 326 One or more jobs does not exist or has
585 327 completed.
586 328
587 329
588 330
589 331 The following exit values are returned for bg:
590 332
591 333 0
|
↓ open down ↓ |
28 lines elided |
↑ open up ↑ |
592 334 All background jobs are started.
593 335
594 336
595 337 >0
596 338 One more jobs does not exist or there are no background jobs.
597 339
598 340
599 341 ATTRIBUTES
600 342 See attributes(5) for descriptions of the following attributes:
601 343
602 - csh, sh, ksh
344 + csh
603 345
604 -
605 -
606 346 +--------------------+-------------------+
607 347 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
608 348 +--------------------+-------------------+
609 349 |Interface Stability | Committed |
610 350 +--------------------+-------------------+
611 351 |Standard | See standards(5). |
612 352 +--------------------+-------------------+
613 353
614 354 ksh93
615 355
616 -
617 -
618 356 +--------------------+-----------------+
619 357 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
620 358 +--------------------+-----------------+
621 359 |Interface Stability | Uncommitted |
622 360 +--------------------+-----------------+
623 361
624 362 SEE ALSO
625 - csh(1), kill(1), ksh(1), ksh93(1), ps(1), sh(1), stop(1),
626 - shell_builtins(1), stty(1), wait(1), signal.h(3HEAD), attributes(5),
627 - environ(5), standards(5)
363 + csh(1), kill(1), ksh93(1), ps(1), stop(1), shell_builtins(1), stty(1),
364 + wait(1), signal.h(3HEAD), attributes(5), environ(5), standards(5)
628 365
629 366
630 367
631 - November 2, 2007 JOBS(1)
368 + February 9, 2021 JOBS(1)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX