1 .\" 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3 .\" permission to reproduce portions of its copyrighted documentation. 4 .\" Original documentation from The Open Group can be obtained online at 5 .\" http://www.opengroup.org/bookstore/. 6 .\" 7 .\" The Institute of Electrical and Electronics Engineers and The Open 8 .\" Group, have given us permission to reprint portions of their 9 .\" documentation. 10 .\" 11 .\" In the following statement, the phrase ``this text'' refers to portions 12 .\" of the system documentation. 13 .\" 14 .\" Portions of this text are reprinted and reproduced in electronic form 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16 .\" Standard for Information Technology -- Portable Operating System 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy 20 .\" between these versions and the original IEEE and The Open Group 21 .\" Standard, the original IEEE and The Open Group Standard is the referee 22 .\" document. The original Standard can be obtained online at 23 .\" http://www.opengroup.org/unix/online.html. 24 .\" 25 .\" This notice shall appear on any product containing this material. 26 .\" 27 .\" The contents of this file are subject to the terms of the 28 .\" Common Development and Distribution License (the "License"). 29 .\" You may not use this file except in compliance with the License. 30 .\" 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32 .\" or http://www.opensolaris.org/os/licensing. 33 .\" See the License for the specific language governing permissions 34 .\" and limitations under the License. 35 .\" 36 .\" When distributing Covered Code, include this CDDL HEADER in each 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38 .\" If applicable, add the following below this CDDL HEADER, with the 39 .\" fields enclosed by brackets "[]" replaced with your own identifying 40 .\" information: Portions Copyright [yyyy] [name of copyright owner] 41 .\" 42 .\" 43 .\" Copyright 1989 AT&T 44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved 45 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures 46 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved 47 .\" Copyright 2021 OmniOS Community Edition (OmniOSce) Association. 48 .\" 49 .TH JOBS 1 "Feb 9, 2021" 50 .SH NAME 51 jobs, fg, bg, stop, notify \- control process execution 52 .SH SYNOPSIS 53 54 .SS "csh" 55 .nf 56 \fBjobs\fR [\fB-l\fR] 57 .fi 58 59 .LP 60 .nf 61 \fBfg\fR [% \fIjob_id\fR] 62 .fi 63 64 .LP 65 .nf 66 \fBbg\fR [% \fIjob_id\fR]... 67 .fi 68 69 .LP 70 .nf 71 \fBnotify\fR [% \fIjob_id\fR]... 72 .fi 73 74 .LP 75 .nf 76 \fBstop\fR % \fIjob_id\fR... 77 .fi 78 79 .LP 80 .nf 81 \fBstop\fR \fIpid\fR... 82 .fi 83 84 .SS "ksh93" 85 .nf 86 \fBjobs\fR [\fB-lnp\fR] [\fIjob_id\fR...] 87 .fi 88 89 .LP 90 .nf 91 \fBfg\fR [\fIjob_id\fR...] 92 .fi 93 94 .LP 95 .nf 96 \fBbg\fR [\fIjob_id\fR...] 97 .fi 98 99 .SH DESCRIPTION 100 .SS "csh" 101 The C shell built-in, \fBjobs\fR, without an argument, lists the active jobs 102 under job control. 103 .sp 104 .ne 2 105 .na 106 \fB\fB-l\fR\fR 107 .ad 108 .RS 6n 109 List process \fBID\fRs, in addition to the normal information. 110 .RE 111 112 .sp 113 .LP 114 The shell associates a numbered \fIjob_id\fR with each command sequence to keep 115 track of those commands that are running in the background or have been stopped 116 with \fBTSTP\fR signals (typically Control-Z). When a command or command 117 sequence (semicolon-separated list) is started in the background using the 118 \fB&\fR metacharacter, the shell displays a line with the job number in 119 brackets and a list of associated process numbers: 120 .sp 121 .LP 122 \fB[1] 1234\fR 123 .sp 124 .LP 125 To see the current list of jobs, use the \fBjobs\fR built-in command. The job 126 most recently stopped (or put into the background if none are stopped) is 127 referred to as the \fBcurrent\fR job and is indicated with a `\fB+\fR'. The 128 previous job is indicated with a `\fB\(mi\fR\&'; when the current job is 129 terminated or moved to the foreground, this job takes its place (becomes the 130 new current job). 131 .sp 132 .LP 133 To manipulate jobs, refer to the \fBbg\fR, \fBfg\fR, \fBkill\fR, \fBstop\fR, 134 and \fB%\fR built-in commands. 135 .sp 136 .LP 137 A reference to a job begins with a `\fB%\fR'. By itself, the percent sign 138 refers to the current job. 139 .sp 140 .ne 2 141 .na 142 \fB\fB%\fR \fB%+\fR \fB%%\fR\fR 143 .ad 144 .RS 12n 145 The current job. 146 .RE 147 148 .sp 149 .ne 2 150 .na 151 \fB\fB%\(mi\fR\fR 152 .ad 153 .RS 12n 154 The previous job. 155 .RE 156 157 .sp 158 .ne 2 159 .na 160 \fB\fB%\fR\fIj\fR\fR 161 .ad 162 .RS 12n 163 Refer to job \fIj\fR as in: `\fBkill\fR \fB-9\fR \fB%\fR\fIj\fR'. \fIj\fR can 164 be a job number, or a string that uniquely specifies the command line by which 165 it was started; `\fBfg %vi\fR' might bring a stopped \fBvi\fR job to the 166 foreground, for instance. 167 .RE 168 169 .sp 170 .ne 2 171 .na 172 \fB\fB%?\fR\fIstring\fR\fR 173 .ad 174 .RS 12n 175 Specify the job for which the command line uniquely contains \fIstring\fR. 176 .RE 177 178 .sp 179 .LP 180 A job running in the background stops when it attempts to read from the 181 terminal. Background jobs can normally produce output, but this can be 182 suppressed using the `\fBstty tostop\fR' command. 183 .sp 184 .LP 185 \fBfg\fR brings the current or specified \fIjob_id\fR into the foreground. 186 .sp 187 .LP 188 \fBbg\fR runs the current or specified jobs in the background. 189 .sp 190 .LP 191 \fBstop\fR stops the execution of a background job(s) by using its 192 \fIjob_id\fR, or of any process by using its \fIpid\fR; see \fBps\fR(1). 193 .sp 194 .LP 195 \fBnotify\fR notifies the user asynchronously when the status of the current 196 job or specified jobs changes. 197 .SS "ksh93" 198 \fBjobs\fR displays information about specified jobs that were started by the 199 current shell environment on standard output. The information contains the job 200 number enclosed in \fB[...]\fR, the status, and the command line that started 201 the job. 202 .sp 203 .LP 204 If \fIjob_id\fR is omitted, \fBjobs\fR displays the status of all stopped jobs, 205 background jobs, and all jobs whose status has changed since last reported by 206 the shell. 207 .sp 208 .LP 209 When \fBjobs\fR reports the termination status of a job, the shell removes the 210 job from the list of known jobs in the current shell environment. 211 .sp 212 .LP 213 The following options modify or enhances the output of \fBjobs\fR: 214 .sp 215 .ne 2 216 .na 217 \fB\fB-l\fR\fR 218 .ad 219 .RS 6n 220 Displays process IDs after the job number in addition to the usual information. 221 .RE 222 223 .sp 224 .ne 2 225 .na 226 \fB\fB-n\fR\fR 227 .ad 228 .RS 6n 229 Displays only the jobs whose status has changed since the last prompt was 230 displayed. 231 .RE 232 233 .sp 234 .ne 2 235 .na 236 \fB\fB-p\fR\fR 237 .ad 238 .RS 6n 239 Displays the process group leader IDs for the specified jobs. 240 .RE 241 242 .sp 243 .LP 244 \fIjob_id\fR can be specified to \fBjobs\fR, \fBfg\fR, and \fBbg\fR as one of 245 the following: 246 .sp 247 .ne 2 248 .na 249 \fB\fInumber\fR\fR 250 .ad 251 .RS 12n 252 The process id of \fBjob\fR. 253 .RE 254 255 .sp 256 .ne 2 257 .na 258 \fB\fB-\fR\fInumber\fR\fR 259 .ad 260 .RS 12n 261 The process group id of \fBjob\fR. 262 .RE 263 264 .sp 265 .ne 2 266 .na 267 \fB\fB%\fR\fInumber\fR\fR 268 .ad 269 .RS 12n 270 The job number. 271 .RE 272 273 .sp 274 .ne 2 275 .na 276 \fB\fB%\fR\fIstring\fR\fR 277 .ad 278 .RS 12n 279 The job whose name begins with \fIstring\fR. 280 .RE 281 282 .sp 283 .ne 2 284 .na 285 \fB\fB%?\fR\fIstring\fR\fR 286 .ad 287 .RS 12n 288 The job whose name contains \fIstring\fR. 289 .RE 290 291 .sp 292 .ne 2 293 .na 294 \fB\fB%+\fR\fR 295 .ad 296 .br 297 .na 298 \fB\fB%%\fR\fR 299 .ad 300 .RS 12n 301 The current job. 302 .RE 303 304 .sp 305 .ne 2 306 .na 307 \fB\fB%-\fR\fR 308 .ad 309 .RS 12n 310 The previous job. 311 .RE 312 313 .sp 314 .LP 315 \fBfg\fR places the specified jobs into the foreground in sequence and sends a 316 \fBCONT\fR signal to start each running. If \fIjob_id\fR is omitted, the most 317 recently started or stopped background job is moved to the foreground. 318 .sp 319 .LP 320 \fBbg\fR places the specified jobs into the background and sends a \fBCONT\fR 321 signal to start them running. If \fIjob_id\fR is omitted, the most recently 322 started or stopped background job is resumed or continued in the background. 323 .SH OUTPUT 324 If the \fB-p\fR option is specified, the output consists of one line for each 325 process \fBID\fR: 326 .sp 327 .LP 328 \fB"%d\en",\fR \fI"process ID"\fR 329 .sp 330 .LP 331 Otherwise, if the \fB-l\fR option is not specified, the output is a series of 332 lines of the form: 333 .sp 334 .LP 335 \fB"[%d] %c %s %s\en"\fR, \fIjob-number\fR, \fIcurrent\fR, \fIstate\fR, 336 \fIcommand\fR 337 .sp 338 .LP 339 where the fields are as follows: 340 .sp 341 .ne 2 342 .na 343 \fB\fIcurrent\fR\fR 344 .ad 345 .RS 14n 346 The character \fB+\fR identifies the job that would be used as a default for 347 the \fBfg\fR or \fBbg\fR commands. This job can also be specified using the 348 \fIjob_id\fR \fB%+\fR or \fB%%\fR \fB\&.\fR The character \fB\(mi\fR identifies 349 the job that would become the default if the current default job were to exit; 350 this job can also be specified using the \fIjob_id\fR \fB%\(mi\fR \fB\&.\fR For 351 other jobs, this field is a space character. At most, one job can be identified 352 with \fB+\fR and at most one job can be identified with \fB\(mi\fR\&. If there 353 is any suspended job, then the current job is a suspended job. If there are at 354 least two suspended jobs, then the previous job is also a suspended job. 355 .RE 356 357 .sp 358 .ne 2 359 .na 360 \fB\fIjob-number\fR\fR 361 .ad 362 .RS 14n 363 A number that can be used to identify the process group to the \fBwait\fR, 364 \fBfg\fR, \fBbg,\fR and \fBkill\fR utilities. Using these utilities, the job 365 can be identified by prefixing the job number with \fB%\fR. 366 .RE 367 368 .sp 369 .ne 2 370 .na 371 \fB\fIstate\fR\fR 372 .ad 373 .RS 14n 374 One of the following strings in the POSIX Locale: 375 .sp 376 .ne 2 377 .na 378 \fB\fBRunning\fR\fR 379 .ad 380 .RS 20n 381 Indicates that the job has not been suspended by a signal and has not exited. 382 .RE 383 384 .sp 385 .ne 2 386 .na 387 \fB\fBDone\fR\fR 388 .ad 389 .RS 20n 390 Indicates that the job completed and returned exit status zero. 391 .RE 392 393 .sp 394 .ne 2 395 .na 396 \fB\fBDone\fR(\fIcode\fR)\fR 397 .ad 398 .RS 20n 399 Indicates that the job completed normally and that it exited with the specified 400 \fBnon-zero\fR exit status, \fIcode\fR, expressed as a decimal number. 401 .RE 402 403 .sp 404 .ne 2 405 .na 406 \fB\fBStopped\fR\fR 407 .ad 408 .RS 20n 409 Indicates that the job was stopped. 410 .RE 411 412 .sp 413 .ne 2 414 .na 415 \fB\fBStopped(SIGTSTP)\fR\fR 416 .ad 417 .RS 20n 418 Indicates that the job was suspended by the \fBSIGTSTP\fR signal. 419 .RE 420 421 .sp 422 .ne 2 423 .na 424 \fB\fBStopped(SIGSTOP)\fR\fR 425 .ad 426 .RS 20n 427 Indicates that the job was suspended by the \fBSIGSTOP\fR signal. 428 .RE 429 430 .sp 431 .ne 2 432 .na 433 \fB\fBStopped(SIGTTIN)\fR\fR 434 .ad 435 .RS 20n 436 Indicates that the job was suspended by the \fBSIGTTIN\fR signal. 437 .RE 438 439 .sp 440 .ne 2 441 .na 442 \fB\fBStopped(SIGTTOU)\fR\fR 443 .ad 444 .RS 20n 445 Indicates that the job was suspended by the \fBSIGTTOU\fR signal. 446 .RE 447 448 The implementation can substitute the string \fBSuspended\fR in place of 449 \fBStopped\fR. If the job was terminated by a signal, the format of \fBstate\fR 450 is unspecified, but it is visibly distinct from all of the other \fBstate\fR 451 formats shown here and indicates the name or description of the signal causing 452 the termination. 453 .RE 454 455 .sp 456 .ne 2 457 .na 458 \fB\fIcommand\fR\fR 459 .ad 460 .RS 14n 461 The associated command that was specified to the shell. 462 .RE 463 464 .sp 465 .LP 466 If the \fB-l\fR option is specified, a field containing the process group 467 \fBID\fR is inserted before the \fBstate\fR field. Also, more processes in a 468 process group can be output on separate lines, using only the process \fBID\fR 469 and \fBcommand\fR fields. 470 .SH ENVIRONMENT VARIABLES 471 See \fBenviron\fR(5) for descriptions of the following environment variables 472 that affect the execution of \fBjobs\fR, \fBfg\fR, and \fBbg\fR: \fBLANG\fR, 473 \fBLC_ALL\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR. 474 .SH EXIT STATUS 475 .SS "csh" 476 The following exit values are returned for \fBjobs\fR, \fBfg\fR, and \fBbg\fR: 477 .sp 478 .ne 2 479 .na 480 \fB\fB0\fR\fR 481 .ad 482 .RS 6n 483 Successful completion. 484 .RE 485 486 .sp 487 .ne 2 488 .na 489 \fB\fB>0\fR\fR 490 .ad 491 .RS 6n 492 An error occurred. 493 .RE 494 495 .SS "ksh93" 496 The following exit values are returned for \fBjobs\fR: 497 .sp 498 .ne 2 499 .na 500 \fB\fB0\fR\fR 501 .ad 502 .RS 6n 503 The information for each job is written to standard output. 504 .RE 505 506 .sp 507 .ne 2 508 .na 509 \fB\fB>0\fR\fR 510 .ad 511 .RS 6n 512 One or more jobs does not exist. 513 .RE 514 515 .sp 516 .LP 517 The following exit values are returned for \fBfg\fR: 518 .sp 519 .ne 2 520 .na 521 \fB\fBexit status of last job\fR\fR 522 .ad 523 .RS 27n 524 One or more jobs has been brought into the foreground. 525 .RE 526 527 .sp 528 .ne 2 529 .na 530 \fB\fBnon-zero\fR\fR 531 .ad 532 .RS 27n 533 One or more jobs does not exist or has completed. 534 .RE 535 536 .sp 537 .LP 538 The following exit values are returned for \fBbg\fR: 539 .sp 540 .ne 2 541 .na 542 \fB\fB0\fR\fR 543 .ad 544 .RS 6n 545 All background jobs are started. 546 .RE 547 548 .sp 549 .ne 2 550 .na 551 \fB\fB>0\fR\fR 552 .ad 553 .RS 6n 554 One more jobs does not exist or there are no background jobs. 555 .RE 556 557 .SH ATTRIBUTES 558 See \fBattributes\fR(5) for descriptions of the following attributes: 559 .SS "csh" 560 .TS 561 box; 562 c | c 563 l | l . 564 ATTRIBUTE TYPE ATTRIBUTE VALUE 565 _ 566 Interface Stability Committed 567 _ 568 Standard See \fBstandards\fR(5). 569 .TE 570 571 .SS "ksh93" 572 .TS 573 box; 574 c | c 575 l | l . 576 ATTRIBUTE TYPE ATTRIBUTE VALUE 577 _ 578 Interface Stability Uncommitted 579 .TE 580 581 .SH SEE ALSO 582 \fBcsh\fR(1), \fBkill\fR(1), \fBksh93\fR(1), \fBps\fR(1), 583 \fBstop\fR(1), \fBshell_builtins\fR(1), \fBstty\fR(1), 584 \fBwait\fR(1), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBenviron\fR(5), 585 \fBstandards\fR(5)