1JOBS(1P)                   POSIX Programmer's Manual                  JOBS(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       jobs — display status of jobs in the current session
14

SYNOPSIS

16       jobs [−l|−p] [job_id...]
17

DESCRIPTION

19       The jobs utility shall display the status of jobs that were started  in
20       the  current shell environment; see Section 2.12, Shell Execution Envi‐
21       ronment.
22
23       When jobs reports the termination status of  a  job,  the  shell  shall
24       remove  its  process  ID  from the list of those ``known in the current
25       shell execution environment''; see Section 2.9.3.1, Examples.
26

OPTIONS

28       The jobs utility shall  conform  to  the  Base  Definitions  volume  of
29       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
30
31       The following options shall be supported:
32
33       −l        (The  letter  ell.)  Provide  more information about each job
34                 listed. This information shall include the job  number,  cur‐
35                 rent  job,  process  group  ID,  state,  and the command that
36                 formed the job.
37
38       −p        Display only the process IDs for the process group leaders of
39                 the selected jobs.
40
41       By  default,  the  jobs utility shall display the status of all stopped
42       jobs, running background jobs and all jobs whose status has changed and
43       have not been reported by the shell.
44

OPERANDS

46       The following operand shall be supported:
47
48       job_id    Specifies  the  jobs for which the status is to be displayed.
49                 If no job_id is given, the status information  for  all  jobs
50                 shall  be displayed. The format of job_id is described in the
51                 Base Definitions volume of POSIX.1‐2008, Section  3.204,  Job
52                 Control Job ID.
53

STDIN

55       Not used.
56

INPUT FILES

58       None.
59

ENVIRONMENT VARIABLES

61       The following environment variables shall affect the execution of jobs:
62
63       LANG      Provide  a  default  value for the internationalization vari‐
64                 ables that are unset or null. (See the Base Definitions  vol‐
65                 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
66                 ables for the precedence  of  internationalization  variables
67                 used to determine the values of locale categories.)
68
69       LC_ALL    If  set  to  a non-empty string value, override the values of
70                 all the other internationalization variables.
71
72       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
73                 bytes of text data as characters (for example, single-byte as
74                 opposed to multi-byte characters in arguments).
75
76       LC_MESSAGES
77                 Determine the locale that should be used to affect the format
78                 and contents of diagnostic messages written to standard error
79                 and informative messages written to standard output.
80
81       NLSPATH   Determine the location of message catalogs for the processing
82                 of LC_MESSAGES.
83

ASYNCHRONOUS EVENTS

85       Default.
86

STDOUT

88       If the −p option is specified, the output shall consist of one line for
89       each process ID:
90
91           "%d\n", <process ID>
92
93       Otherwise, if the −l option is not specified, the  output  shall  be  a
94       series of lines of the form:
95
96           "[%d] %c %s %s\n", <job-number>, <current>, <state>, <command>
97
98       where the fields shall be as follows:
99
100       <current> The  character '+' identifies the job that would be used as a
101                 default for the fg or bg utilities;  this  job  can  also  be
102                 specified  using  the  job_id  %+ or "%%".  The character '−'
103                 identifies the job that would become the default if the  cur‐
104                 rent default job were to exit; this job can also be specified
105                 using the job_id %−. For other jobs, this field is a <space>.
106                 At  most  one  job can be identified with '+' and at most one
107                 job can be identified with '−'.  If there  is  any  suspended
108                 job,  then the current job shall be a suspended job. If there
109                 are at least two suspended jobs, then the previous  job  also
110                 shall be a suspended job.
111
112       <job-number>
113                 A  number  that  can be used to identify the process group to
114                 the wait, fg, bg, and kill utilities. Using these  utilities,
115                 the  job  can  be identified by prefixing the job number with
116                 '%'.
117
118       <state>   One of the following strings (in the POSIX locale):
119
120                 Running   Indicates that the job has not been suspended by  a
121                           signal and has not exited.
122
123                 Done      Indicates  that the job completed and returned exit
124                           status zero.
125
126                 Done(code)
127                           Indicates that the job completed normally and  that
128                           it  exited with the specified non-zero exit status,
129                           code, expressed as a decimal number.
130
131                 Stopped   Indicates that the job was suspended by the SIGTSTP
132                           signal.
133
134                 Stopped (SIGTSTP)
135                           Indicates that the job was suspended by the SIGTSTP
136                           signal.
137
138                 Stopped (SIGSTOP)
139                           Indicates that the job was suspended by the SIGSTOP
140                           signal.
141
142                 Stopped (SIGTTIN)
143                           Indicates that the job was suspended by the SIGTTIN
144                           signal.
145
146                 Stopped (SIGTTOU)
147                           Indicates that the job was suspended by the SIGTTOU
148                           signal.
149
150                 The  implementation  may  substitute  the string Suspended in
151                 place of Stopped.  If the job was terminated by a signal, the
152                 format  of  <state>  is  unspecified, but it shall be visibly
153                 distinct from all of the other <state> formats shown here and
154                 shall  indicate the name or description of the signal causing
155                 the termination.
156
157       <command> The associated command that was given to the shell.
158
159       If the −l option is specified, a field containing the process group  ID
160       shall  be  inserted before the <state> field. Also, more processes in a
161       process group may be output on separate lines, using only  the  process
162       ID and <command> fields.
163

STDERR

165       The standard error shall be used only for diagnostic messages.
166

OUTPUT FILES

168       None.
169

EXTENDED DESCRIPTION

171       None.
172

EXIT STATUS

174       The following exit values shall be returned:
175
176        0    Successful completion.
177
178       >0    An error occurred.
179

CONSEQUENCES OF ERRORS

181       Default.
182
183       The following sections are informative.
184

APPLICATION USAGE

186       The −p option is the only portable way to find out the process group of
187       a job because different implementations have different  strategies  for
188       defining  the  process  group of the job. Usage such as $(jobs −p) pro‐
189       vides a way of referring to the process group of the job in  an  imple‐
190       mentation-independent way.
191
192       The  jobs utility does not work as expected when it is operating in its
193       own utility execution  environment  because  that  environment  has  no
194       applicable  jobs  to  manipulate. See the APPLICATION USAGE section for
195       bg.  For this reason, jobs is generally implemented as a shell  regular
196       built-in.
197

EXAMPLES

199       None.
200

RATIONALE

202       Both "%%" and "%+" are used to refer to the current job. Both forms are
203       of equal validity—the "%%" mirroring "$$" and "%+" mirroring the output
204       of  jobs.   Both forms reflect historical practice of the KornShell and
205       the C shell with job control.
206
207       The job control features provided by bg, fg, and jobs are based on  the
208       KornShell.  The standard developers examined the characteristics of the
209       C shell versions of these utilities and found that  differences  exist.
210       Despite  widespread  use  of  the  C shell, the KornShell versions were
211       selected for this volume of POSIX.1‐2008 to maintain a degree  of  uni‐
212       formity  with  the rest of the KornShell features selected (such as the
213       very popular command line editing features).
214
215       The jobs utility is not dependent on the job control option, as are the
216       seemingly  related bg and fg utilities because jobs is useful for exam‐
217       ining background jobs, regardless of the condition of job control. When
218       the  user  has invoked a set +m command and job control has been turned
219       off, jobs can still be used to examine the background  jobs  associated
220       with  that  current  session.  Similarly, kill can then be used to kill
221       background jobs with kill %<background job number>.
222
223       The output for terminated jobs is left unspecified to accommodate vari‐
224       ous historical systems. The following formats have been witnessed:
225
226        1. Killed(signal name)
227
228        2. signal name
229
230        3. signal name(coredump)
231
232        4. signal descriptioncore dumped
233
234       Most  users  should  be  able  to understand these formats, although it
235       means that applications have trouble parsing them.
236
237       The calculation of job IDs was not described since this  would  suggest
238       an implementation, which may impose unnecessary restrictions.
239
240       In  an early proposal, a −n option was included to ``Display the status
241       of jobs that have changed, exited, or stopped  since  the  last  status
242       report''.  It  was  removed because the shell always writes any changed
243       status of jobs before each prompt.
244

FUTURE DIRECTIONS

246       None.
247

SEE ALSO

249       Section 2.12, Shell Execution Environment, bg, fg, kill, wait
250
251       The Base Definitions volume of POSIX.1‐2008, Section 3.204, Job Control
252       Job  ID, Chapter 8, Environment Variables, Section 12.2, Utility Syntax
253       Guidelines
254
256       Portions of this text are reprinted and reproduced in  electronic  form
257       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
258       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
259       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
260       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
261       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
262       event of any discrepancy between this version and the original IEEE and
263       The  Open Group Standard, the original IEEE and The Open Group Standard
264       is the referee document. The original Standard can be  obtained  online
265       at http://www.unix.org/online.html .
266
267       Any  typographical  or  formatting  errors that appear in this page are
268       most likely to have been introduced during the conversion of the source
269       files  to  man page format. To report such errors, see https://www.ker
270       nel.org/doc/man-pages/reporting_bugs.html .
271
272
273
274IEEE/The Open Group                  2013                             JOBS(1P)
Impressum