usr/src/man/man1/jobs.1

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
   3 .\" Copyright 1989 AT&T
   4 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
   5 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
   6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   7 .\" http://www.opengroup.org/bookstore/.
   8 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   9 .\"  This notice shall appear on any product containing this material.
  10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  11 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  12 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  13 .TH JOBS 1 "Nov 2, 2007"
  14 .SH NAME
  15 jobs, fg, bg, stop, notify \- control process execution
  16 .SH SYNOPSIS
  17 .SS "sh"
  18 .LP
  19 .nf
  20 \fBjobs\fR [\fB-p\fR | \fB-l\fR] [% \fIjob_id\fR...]
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBjobs\fR \fB-x\fR \fIcommand\fR [\fIarguments\fR]
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBfg\fR [% \fIjob_id\fR...]
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBbg\fR [% \fIjob_id\fR...]
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBstop\fR % \fIjob_id\fR...
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBstop\fR \fIpid\fR...
  46 .fi
  47
  48 .SS "csh"
  49 .LP
  50 .nf
  51 \fBjobs\fR [\fB-l\fR]
  52 .fi
  53
  54 .LP
  55 .nf
  56 \fBfg\fR [% \fIjob_id\fR]
  57 .fi
  58
  59 .LP
  60 .nf
  61 \fBbg\fR [% \fIjob_id\fR]...
  62 .fi
  63
  64 .LP
  65 .nf
  66 \fBnotify\fR [% \fIjob_id\fR]...
  67 .fi
  68
  69 .LP
  70 .nf
  71 \fBstop\fR % \fIjob_id\fR...
  72 .fi
  73
  74 .LP
  75 .nf
  76 \fBstop\fR \fIpid\fR...
  77 .fi
  78
  79 .SS "ksh"
  80 .LP
  81 .nf
  82 \fBjobs\fR [\fB-lnp\fR] [% \fIjob_id\fR...]
  83 .fi
  84
  85 .LP
  86 .nf
  87 \fBfg\fR [% \fIjob_id\fR...]
  88 .fi
  89
  90 .LP
  91 .nf
  92 \fBbg\fR [% \fIjob_id\fR...]
  93 .fi
  94
  95 .LP
  96 .nf
  97 \fBstop\fR % \fIjob_id\fR...
  98 .fi
  99
 100 .LP
 101 .nf
 102 \fBstop\fR \fIpid\fR...
 103 .fi
 104
 105 .SS "ksh93"
 106 .LP
 107 .nf
 108 \fBjobs\fR [\fB-lnp\fR] [\fIjob_id\fR...]
 109 .fi
 110
 111 .LP
 112 .nf
 113 \fBfg\fR [\fIjob_id\fR...]
 114 .fi
 115
 116 .LP
 117 .nf
 118 \fBbg\fR [\fIjob_id\fR...]
 119 .fi
 120
 121 .SH DESCRIPTION
 122 .SS "sh"
 123 .sp
 124 .LP
 125 When Job Control is enabled, the Bourne shell built-in \fBjobs\fR reports all
 126 jobs that are stopped or executing in the background. If \fB%\fR\fIjob_id\fR is
 127 omitted, all jobs that are stopped or running in the background is reported.
 128 The following options modify or enhance the output of \fBjobs\fR:
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fB-l\fR\fR
 133 .ad
 134 .RS 6n
 135 Reports the process group \fBID\fR and working directory of the jobs.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fB-p\fR\fR
 142 .ad
 143 .RS 6n
 144 Reports only the process group \fBID\fR of the jobs.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fB-x\fR\fR
 151 .ad
 152 .RS 6n
 153 Replaces any \fIjob_id\fR found in \fIcommand\fR or \fIarguments\fR with the
 154 corresponding process group \fBID\fR, and then executes \fIcommand\fR passing
 155 it \fIarguments\fR.
 156 .RE
 157
 158 .sp
 159 .LP
 160 When the shell is invoked as \fBjsh\fR, Job Control is enabled in addition to
 161 all of the functionality described previously for \fBsh\fR. Typically Job
 162 Control is enabled for the interactive shell only. Non-interactive shells
 163 typically do not benefit from the added functionality of Job Control.
 164 .sp
 165 .LP
 166 With Job Control enabled every command or pipeline the user enters at the
 167 terminal is called a \fIjob_id\fR. All jobs exist in one of the following
 168 states: foreground, background or stopped. These terms are defined as follows:
 169 .RS +4
 170 .TP
 171 1.
 172 A job in the \fBforeground\fR has read and write access to the controlling
 173 terminal.
 174 .RE
 175 .RS +4
 176 .TP
 177 2.
 178 A job in the \fBbackground\fR is denied read access and has conditional
 179 write access to the controlling terminal (see \fBstty\fR(1))
 180 .RE
 181 .RS +4
 182 .TP
 183 3.
 184 A \fBstopped\fR job is a job that has been placed in a suspended state,
 185 usually as a result of a \fBSIGTSTP\fR signal (see \fBsignal.h\fR(3HEAD)).
 186 .RE
 187 .sp
 188 .LP
 189 Every job that the shell starts is assigned a positive integer, called a
 190 \fIjob_id number\fR which is tracked by the shell and are used as an identifier
 191 to indicate a specific job. Additionally, the shell keeps track of the
 192 \fBcurrent\fR and \fBprevious\fR jobs. The \fBcurrent job\fR is the most recent
 193 job to be started or restarted. The \fBprevious job\fR is the first non-current
 194 job.
 195 .sp
 196 .LP
 197 The acceptable syntax for a Job Identifier is of the form:
 198 .sp
 199 .LP
 200 \fB%\fR\fIjob_id\fR
 201 .sp
 202 .LP
 203 where \fIjob_id\fR can be specified in any of the following formats:
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fB%\fR or \fB+\fR\fR
 208 .ad
 209 .RS 13n
 210 for the current job
 211 .RE
 212
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fB\(mi\fR\fR
 217 .ad
 218 .RS 13n
 219 for the previous job
 220 .RE
 221
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fB?\fR\fI<string>\fR\fR
 226 .ad
 227 .RS 13n
 228 specify the job for which the command line uniquely contains \fIstring\fR.
 229 .RE
 230
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fIn\fR\fR
 235 .ad
 236 .RS 13n
 237 for job number \fIn\fR, where \fIn\fR is a job number
 238 .RE
 239
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fIpref\fR\fR
 244 .ad
 245 .RS 13n
 246 where \fIpref\fR is a unique prefix of the command name (for example, if the
 247 command \fBls \(mil name\fR were running in the background, it could be
 248 referred to as \fB%ls\fR); \fIpref\fR cannot contain blanks unless it is
 249 quoted.
 250 .RE
 251
 252 .sp
 253 .LP
 254 When Job Control is enabled, \fBfg\fR resumes the execution of a stopped job in
 255 the foreground, also moves an executing background job into the foreground. If
 256 \fB%\fR\fIjob_id\fR is omitted the current job is assumed.
 257 .sp
 258 .LP
 259 When Job Control is enabled, \fBbg\fR resumes the execution of a stopped job in
 260 the background. If \fB%\fR\fIjob_id\fR is omitted the current job is assumed.
 261 .sp
 262 .LP
 263 \fBstop\fR stops the execution of a background job(s) by using its
 264 \fIjob_id\fR, or of any process by using its \fIpid\fR; see \fBps\fR(1).
 265 .SS "csh"
 266 .sp
 267 .LP
 268 The C shell built-in, \fBjobs\fR, without an argument, lists the active jobs
 269 under job control.
 270 .sp
 271 .ne 2
 272 .na
 273 \fB\fB-l\fR\fR
 274 .ad
 275 .RS 6n
 276 List process \fBID\fRs, in addition to the normal information.
 277 .RE
 278
 279 .sp
 280 .LP
 281 The shell associates a numbered \fIjob_id\fR with each command sequence to keep
 282 track of those commands that are running in the background or have been stopped
 283 with \fBTSTP\fR signals (typically Control-Z). When a command or command
 284 sequence (semicolon-separated list) is started in the background using the
 285 \fB&\fR metacharacter, the shell displays a line with the job number in
 286 brackets and a list of associated process numbers:
 287 .sp
 288 .LP
 289 \fB[1] 1234\fR
 290 .sp
 291 .LP
 292 To see the current list of jobs, use the \fBjobs\fR built-in command. The job
 293 most recently stopped (or put into the background if none are stopped) is
 294 referred to as the \fBcurrent\fR job and is indicated with a `\fB+\fR'. The
 295 previous job is indicated with a `\fB\(mi\fR\&'; when the current job is
 296 terminated or moved to the foreground, this job takes its place (becomes the
 297 new current job).
 298 .sp
 299 .LP
 300 To manipulate jobs, refer to the \fBbg\fR, \fBfg\fR, \fBkill\fR, \fBstop\fR,
 301 and \fB%\fR built-in commands.
 302 .sp
 303 .LP
 304 A reference to a job begins with a `\fB%\fR'. By itself, the percent sign
 305 refers to the current job.
 306 .sp
 307 .ne 2
 308 .na
 309 \fB\fB%\fR \fB%+\fR \fB%%\fR\fR
 310 .ad
 311 .RS 12n
 312 The current job.
 313 .RE
 314
 315 .sp
 316 .ne 2
 317 .na
 318 \fB\fB%\(mi\fR\fR
 319 .ad
 320 .RS 12n
 321 The previous job.
 322 .RE
 323
 324 .sp
 325 .ne 2
 326 .na
 327 \fB\fB%\fR\fIj\fR\fR
 328 .ad
 329 .RS 12n
 330 Refer to job \fIj\fR as in: `\fBkill\fR \fB-9\fR \fB%\fR\fIj\fR'. \fIj\fR can
 331 be a job number, or a string that uniquely specifies the command line by which
 332 it was started; `\fBfg %vi\fR' might bring a stopped \fBvi\fR job to the
 333 foreground, for instance.
 334 .RE
 335
 336 .sp
 337 .ne 2
 338 .na
 339 \fB\fB%?\fR\fIstring\fR\fR
 340 .ad
 341 .RS 12n
 342 Specify the job for which the command line uniquely contains \fIstring\fR.
 343 .RE
 344
 345 .sp
 346 .LP
 347 A job running in the background stops when it attempts to read from the
 348 terminal. Background jobs can normally produce output, but this can be
 349 suppressed using the `\fBstty tostop\fR' command.
 350 .sp
 351 .LP
 352 \fBfg\fR brings the current or specified \fIjob_id\fR into the foreground.
 353 .sp
 354 .LP
 355 \fBbg\fR runs the current or specified jobs in the background.
 356 .sp
 357 .LP
 358 \fBstop\fR stops the execution of a background job(s) by using its
 359 \fIjob_id\fR, or of any process by using its \fIpid\fR; see \fBps\fR(1).
 360 .sp
 361 .LP
 362 \fBnotify\fR notifies the user asynchronously when the status of the current
 363 job or specified jobs changes.
 364 .SS "ksh"
 365 .sp
 366 .LP
 367 \fBjobs\fR displays the status of the jobs that were started in the current
 368 shell environment. When \fBjobs\fR reports the termination status of a job, the
 369 shell removes its process \fBID\fR from the list of those known in the current
 370 shell execution environment.
 371 .sp
 372 .LP
 373 \fIjob_id\fR specifies the jobs for which the status is to be displayed. If no
 374 \fIjob_id\fR is specified, the status information for all jobs are displayed.
 375 .sp
 376 .LP
 377 The following options modify or enhance the output of \fBjobs\fR:
 378 .sp
 379 .ne 2
 380 .na
 381 \fB\fB-l\fR\fR
 382 .ad
 383 .RS 6n
 384 (The letter ell.) Provides more information about each job listed. This
 385 information includes the job number, current job, process group \fBID\fR, state
 386 and the command that formed the job.
 387 .RE
 388
 389 .sp
 390 .ne 2
 391 .na
 392 \fB\fB-n\fR\fR
 393 .ad
 394 .RS 6n
 395 Displays only jobs that have stopped or exited since last notified.
 396 .RE
 397
 398 .sp
 399 .ne 2
 400 .na
 401 \fB\fB-p\fR\fR
 402 .ad
 403 .RS 6n
 404 Displays only the process \fBID\fRs for the process group leaders of the
 405 selected jobs.
 406 .RE
 407
 408 .sp
 409 .LP
 410 By default, \fBjobs\fR displays the status of all the stopped jobs, running
 411 background jobs, and all jobs whose status has changed and have not been
 412 reported by the shell.
 413 .sp
 414 .LP
 415 If the \fBmonitor\fR option of the \fBset\fR command is turned on, an
 416 interactive shell associates a \fBjob\fR with each pipeline. It keeps a table
 417 of current jobs, printed by the \fBjobs\fR command, and assigns them small
 418 integer numbers. When a job is started asynchronously with \fB&\fR, the shell
 419 prints a line which looks like:
 420 .sp
 421 .LP
 422 \fB[1]\fR \fB1234\fR
 423 .sp
 424 .LP
 425 indicating that the job, which was started asynchronously, was job number
 426 \fB1\fR and had one (top-level) process, whose process id was \fB1234\fR.
 427 .sp
 428 .LP
 429 If you are running a job and wish to do something else you can hit the key ^Z
 430 (Control-Z) which sends a \fBSTOP\fR signal to the current job. The shell then
 431 normally indicates that the job has been "\fBStopped\fR" (see \fBOUTPUT\fR
 432 below), and print another prompt. You can then manipulate the state of this
 433 job, putting it in the background with the \fBbg\fR command, or run some other
 434 commands and then eventually bring the job back into the foreground with the
 435 foreground command \fBfg\fR. A ^Z takes effect immediately and is like an
 436 interrupt, in that pending output and unread input are discarded when it is
 437 typed.
 438 .sp
 439 .LP
 440 There are several ways to refer to jobs in the shell. A job can be referred to
 441 by the process id of any process of the job or by one of the following:
 442 .sp
 443 .ne 2
 444 .na
 445 \fB\fB%\fR\fInumber\fR\fR
 446 .ad
 447 .RS 12n
 448 The job with the specified number.
 449 .RE
 450
 451 .sp
 452 .ne 2
 453 .na
 454 \fB\fB%\fR\fIstring\fR\fR
 455 .ad
 456 .RS 12n
 457 Any job whose command line begins with \fIstring\fR; works only in the
 458 interactive mode when the history file is active.
 459 .RE
 460
 461 .sp
 462 .ne 2
 463 .na
 464 \fB\fB%?\fR\fIstring\fR\fR
 465 .ad
 466 .RS 12n
 467 Any job whose command line contains \fIstring\fR; works only in the interactive
 468 mode when the history file is active.
 469 .RE
 470
 471 .sp
 472 .ne 2
 473 .na
 474 \fB\fB%%\fR\fR
 475 .ad
 476 .RS 12n
 477 Current job.
 478 .RE
 479
 480 .sp
 481 .ne 2
 482 .na
 483 \fB\fB%+\fR\fR
 484 .ad
 485 .RS 12n
 486 Equivalent to \fB%%\fR.
 487 .RE
 488
 489 .sp
 490 .ne 2
 491 .na
 492 \fB\fB%\(mi\fR\fR
 493 .ad
 494 .RS 12n
 495 Previous job.
 496 .RE
 497
 498 .sp
 499 .LP
 500 The shell learns immediately whenever a process changes state. It normally
 501 informs you whenever a job becomes blocked so that no further progress is
 502 possible, but only just before it prints a prompt. This is done so that it does
 503 not otherwise disturb your work. When the monitor mode is on, each background
 504 job that completes triggers any trap set for \fBCHLD\fR. When you try to leave
 505 the shell while jobs are running or stopped, you are warned that `You have
 506 stopped (running) jobs.' You can use the \fBjobs\fR command to see what they
 507 are. If you do this or immediately try to exit again, the shell does not warn
 508 you a second time, and the stopped jobs are terminated.
 509 .sp
 510 .LP
 511 \fBfg\fR moves a background job from the current environment into the
 512 foreground. Using \fBfg\fR to place a job in the foreground removes its process
 513 \fBID\fR from the list of those known in the current shell execution
 514 environment. The \fBfg\fR command is available only on systems that support job
 515 control. If \fIjob_id\fR is not specified, the current job is brought into the
 516 foreground.
 517 .sp
 518 .LP
 519 \fBbg\fR resumes suspended jobs from the current environment by running them as
 520 background jobs. If the job specified by \fIjob_id\fR is already a running
 521 background job, \fBbg\fR has no effect and exits successfully. Using \fBbg\fR
 522 to place a job into the background causes its process \fBID\fR to become `known
 523 in the current shell execution environment, as if it had been started as an
 524 asynchronous list. The \fBbg\fR command is available only on systems that
 525 support job control. If \fIjob_id\fR is not specified, the current job is
 526 placed in the background.
 527 .sp
 528 .LP
 529 \fBstop\fR stops the execution of a background job(s) by using its
 530 \fIjob_id\fR, or of any process by using its \fIpid\fR. See \fBps\fR(1).
 531 .SS "ksh93"
 532 .sp
 533 .LP
 534 \fBjobs\fR displays information about specified jobs that were started by the
 535 current shell environment on standard output. The information contains the job
 536 number enclosed in \fB[...]\fR, the status, and the command line that started
 537 the job.
 538 .sp
 539 .LP
 540 If \fIjob_id\fR is omitted, \fBjobs\fR displays the status of all stopped jobs,
 541 background jobs, and all jobs whose status has changed since last reported by
 542 the shell.
 543 .sp
 544 .LP
 545 When \fBjobs\fR reports the termination status of a job, the shell removes the
 546 job from the list of known jobs in the current shell environment.
 547 .sp
 548 .LP
 549 The following options modify or enhances the output of \fBjobs\fR:
 550 .sp
 551 .ne 2
 552 .na
 553 \fB\fB-l\fR\fR
 554 .ad
 555 .RS 6n
 556 Displays process IDs after the job number in addition to the usual information.
 557 .RE
 558
 559 .sp
 560 .ne 2
 561 .na
 562 \fB\fB-n\fR\fR
 563 .ad
 564 .RS 6n
 565 Displays only the jobs whose status has changed since the last prompt was
 566 displayed.
 567 .RE
 568
 569 .sp
 570 .ne 2
 571 .na
 572 \fB\fB-p\fR\fR
 573 .ad
 574 .RS 6n
 575 Displays the process group leader IDs for the specified jobs.
 576 .RE
 577
 578 .sp
 579 .LP
 580 \fIjob_id\fR can be specified to \fBjobs\fR, \fBfg\fR, and \fBbg\fR as one of
 581 the following:
 582 .sp
 583 .ne 2
 584 .na
 585 \fB\fInumber\fR\fR
 586 .ad
 587 .RS 12n
 588 The process id of \fBjob\fR.
 589 .RE
 590
 591 .sp
 592 .ne 2
 593 .na
 594 \fB\fB-\fR\fInumber\fR\fR
 595 .ad
 596 .RS 12n
 597 The process group id of \fBjob\fR.
 598 .RE
 599
 600 .sp
 601 .ne 2
 602 .na
 603 \fB\fB%\fR\fInumber\fR\fR
 604 .ad
 605 .RS 12n
 606 The job number.
 607 .RE
 608
 609 .sp
 610 .ne 2
 611 .na
 612 \fB\fB%\fR\fIstring\fR\fR
 613 .ad
 614 .RS 12n
 615 The job whose name begins with \fIstring\fR.
 616 .RE
 617
 618 .sp
 619 .ne 2
 620 .na
 621 \fB\fB%?\fR\fIstring\fR\fR
 622 .ad
 623 .RS 12n
 624 The job whose name contains \fIstring\fR.
 625 .RE
 626
 627 .sp
 628 .ne 2
 629 .na
 630 \fB\fB%+\fR\fR
 631 .ad
 632 .br
 633 .na
 634 \fB\fB%%\fR\fR
 635 .ad
 636 .RS 12n
 637 The current job.
 638 .RE
 639
 640 .sp
 641 .ne 2
 642 .na
 643 \fB\fB%-\fR\fR
 644 .ad
 645 .RS 12n
 646 The previous job.
 647 .RE
 648
 649 .sp
 650 .LP
 651 \fBfg\fR places the specified jobs into the foreground in sequence and sends a
 652 \fBCONT\fR signal to start each running. If \fIjob_id\fR is omitted, the most
 653 recently started or stopped background job is moved to the foreground.
 654 .sp
 655 .LP
 656 \fBbg\fR places the specified jobs into the background and sends a \fBCONT\fR
 657 signal to start them running. If \fIjob_id\fR is omitted, the most recently
 658 started or stopped background job is resumed or continued in the background.
 659 .SH OUTPUT
 660 .sp
 661 .LP
 662 If the \fB-p\fR option is specified, the output consists of one line for each
 663 process \fBID\fR:
 664 .sp
 665 .LP
 666 \fB"%d\en",\fR \fI"process ID"\fR
 667 .sp
 668 .LP
 669 Otherwise, if the \fB-l\fR option is not specified, the output is a series of
 670 lines of the form:
 671 .sp
 672 .LP
 673 \fB"[%d] %c %s %s\en"\fR, \fIjob-number\fR, \fIcurrent\fR, \fIstate\fR,
 674 \fIcommand\fR
 675 .sp
 676 .LP
 677 where the fields are as follows:
 678 .sp
 679 .ne 2
 680 .na
 681 \fB\fIcurrent\fR\fR
 682 .ad
 683 .RS 14n
 684 The character \fB+\fR identifies the job that would be used as a default for
 685 the \fBfg\fR or \fBbg\fR commands. This job can also be specified using the
 686 \fIjob_id\fR \fB%+\fR or \fB%%\fR \fB\&.\fR The character \fB\(mi\fR identifies
 687 the job that would become the default if the current default job were to exit;
 688 this job can also be specified using the \fIjob_id\fR \fB%\(mi\fR \fB\&.\fR For
 689 other jobs, this field is a space character. At most, one job can be identified
 690 with \fB+\fR and at most one job can be identified with \fB\(mi\fR\&. If there
 691 is any suspended job, then the current job is a suspended job. If there are at
 692 least two suspended jobs, then the previous job is also a suspended job.
 693 .RE
 694
 695 .sp
 696 .ne 2
 697 .na
 698 \fB\fIjob-number\fR\fR
 699 .ad
 700 .RS 14n
 701 A number that can be used to identify the process group to the \fBwait\fR,
 702 \fBfg\fR, \fBbg,\fR and \fBkill\fR utilities. Using these utilities, the job
 703 can be identified by prefixing the job number with \fB%\fR.
 704 .RE
 705
 706 .sp
 707 .ne 2
 708 .na
 709 \fB\fIstate\fR\fR
 710 .ad
 711 .RS 14n
 712 One of the following strings in the POSIX Locale:
 713 .sp
 714 .ne 2
 715 .na
 716 \fB\fBRunning\fR\fR
 717 .ad
 718 .RS 20n
 719 Indicates that the job has not been suspended by a signal and has not exited.
 720 .RE
 721
 722 .sp
 723 .ne 2
 724 .na
 725 \fB\fBDone\fR\fR
 726 .ad
 727 .RS 20n
 728 Indicates that the job completed and returned exit status zero.
 729 .RE
 730
 731 .sp
 732 .ne 2
 733 .na
 734 \fB\fBDone\fR(\fIcode\fR)\fR
 735 .ad
 736 .RS 20n
 737 Indicates that the job completed normally and that it exited with the specified
 738 \fBnon-zero\fR exit status, \fIcode\fR, expressed as a decimal number.
 739 .RE
 740
 741 .sp
 742 .ne 2
 743 .na
 744 \fB\fBStopped\fR\fR
 745 .ad
 746 .RS 20n
 747 Indicates that the job was stopped.
 748 .RE
 749
 750 .sp
 751 .ne 2
 752 .na
 753 \fB\fBStopped(SIGTSTP)\fR\fR
 754 .ad
 755 .RS 20n
 756 Indicates that the job was suspended by the \fBSIGTSTP\fR signal.
 757 .RE
 758
 759 .sp
 760 .ne 2
 761 .na
 762 \fB\fBStopped(SIGSTOP)\fR\fR
 763 .ad
 764 .RS 20n
 765 Indicates that the job was suspended by the \fBSIGSTOP\fR signal.
 766 .RE
 767
 768 .sp
 769 .ne 2
 770 .na
 771 \fB\fBStopped(SIGTTIN)\fR\fR
 772 .ad
 773 .RS 20n
 774 Indicates that the job was suspended by the \fBSIGTTIN\fR signal.
 775 .RE
 776
 777 .sp
 778 .ne 2
 779 .na
 780 \fB\fBStopped(SIGTTOU)\fR\fR
 781 .ad
 782 .RS 20n
 783 Indicates that the job was suspended by the \fBSIGTTOU\fR signal.
 784 .RE
 785
 786 The implementation can substitute the string \fBSuspended\fR in place of
 787 \fBStopped\fR. If the job was terminated by a signal, the format of \fBstate\fR
 788 is unspecified, but it is visibly distinct from all of the other \fBstate\fR
 789 formats shown here and indicates the name or description of the signal causing
 790 the termination.
 791 .RE
 792
 793 .sp
 794 .ne 2
 795 .na
 796 \fB\fIcommand\fR\fR
 797 .ad
 798 .RS 14n
 799 The associated command that was specified to the shell.
 800 .RE
 801
 802 .sp
 803 .LP
 804 If the \fB-l\fR option is specified, a field containing the process group
 805 \fBID\fR is inserted before the \fBstate\fR field. Also, more processes in a
 806 process group can be output on separate lines, using only the process \fBID\fR
 807 and \fBcommand\fR fields.
 808 .SH ENVIRONMENT VARIABLES
 809 .sp
 810 .LP
 811 See \fBenviron\fR(5) for descriptions of the following environment variables
 812 that affect the execution of \fBjobs\fR, \fBfg\fR, and \fBbg\fR: \fBLANG\fR,
 813 \fBLC_ALL\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 814 .SH EXIT STATUS
 815 .SS "sh, csh, ksh"
 816 .sp
 817 .LP
 818 The following exit values are returned for \fBjobs\fR, \fBfg\fR, and \fBbg\fR:
 819 .sp
 820 .ne 2
 821 .na
 822 \fB\fB0\fR\fR
 823 .ad
 824 .RS 6n
 825 Successful completion.
 826 .RE
 827
 828 .sp
 829 .ne 2
 830 .na
 831 \fB\fB>0\fR\fR
 832 .ad
 833 .RS 6n
 834 An error occurred.
 835 .RE
 836
 837 .SS "ksh93"
 838 .sp
 839 .LP
 840 The following exit values are returned for \fBjobs\fR:
 841 .sp
 842 .ne 2
 843 .na
 844 \fB\fB0\fR\fR
 845 .ad
 846 .RS 6n
 847 The information for each job is written to standard output.
 848 .RE
 849
 850 .sp
 851 .ne 2
 852 .na
 853 \fB\fB>0\fR\fR
 854 .ad
 855 .RS 6n
 856 One or more jobs does not exist.
 857 .RE
 858
 859 .sp
 860 .LP
 861 The following exit values are returned for \fBfg\fR:
 862 .sp
 863 .ne 2
 864 .na
 865 \fB\fBexit status of last job\fR\fR
 866 .ad
 867 .RS 27n
 868 One or more jobs has been brought into the foreground.
 869 .RE
 870
 871 .sp
 872 .ne 2
 873 .na
 874 \fB\fBnon-zero\fR\fR
 875 .ad
 876 .RS 27n
 877 One or more jobs does not exist or has completed.
 878 .RE
 879
 880 .sp
 881 .LP
 882 The following exit values are returned for \fBbg\fR:
 883 .sp
 884 .ne 2
 885 .na
 886 \fB\fB0\fR\fR
 887 .ad
 888 .RS 6n
 889 All background jobs are started.
 890 .RE
 891
 892 .sp
 893 .ne 2
 894 .na
 895 \fB\fB>0\fR\fR
 896 .ad
 897 .RS 6n
 898 One more jobs does not exist or there are no background jobs.
 899 .RE
 900
 901 .SH ATTRIBUTES
 902 .sp
 903 .LP
 904 See \fBattributes\fR(5) for descriptions of the following attributes:
 905 .SS "csh, sh, ksh"
 906 .sp
 907
 908 .sp
 909 .TS
 910 box;
 911 c | c
 912 l | l .
 913 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 914 _
 915 Interface Stability     Committed
 916 _
 917 Standard        See \fBstandards\fR(5).
 918 .TE
 919
 920 .SS "ksh93"
 921 .sp
 922
 923 .sp
 924 .TS
 925 box;
 926 c | c
 927 l | l .
 928 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 929 _
 930 Interface Stability     Uncommitted
 931 .TE
 932
 933 .SH SEE ALSO
 934 .sp
 935 .LP
 936 \fBcsh\fR(1), \fBkill\fR(1), \fBksh\fR(1), \fBksh93\fR(1), \fBps\fR(1),
 937 \fBsh\fR(1), \fBstop\fR(1), \fBshell_builtins\fR(1), \fBstty\fR(1),
 938 \fBwait\fR(1), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBenviron\fR(5),
 939 \fBstandards\fR(5)