383 lines
14 KiB
HTML
383 lines
14 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>jobs</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="jobs"></a> <a name="tag_04_70"></a><!-- jobs -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_70_01"></a>NAME</h4>
|
|
|
|
<blockquote>jobs - display status of jobs in the current session</blockquote>
|
|
|
|
<h4><a name="tag_04_70_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> jobs</tt> <b>[</b><tt>-l| -p</tt><b>][</b><i>job_id</i><tt>...</tt><b>]</b><tt><img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>jobs</i> utility shall display the status of jobs that were started in the current shell environment; see <a href=
|
|
"xcu_chap02.html#tag_02_12"><i>Shell Execution Environment</i></a> .</p>
|
|
|
|
<p>When <i>jobs</i> reports the termination status of a job, the shell shall remove its process ID from the list of those "known
|
|
in the current shell execution environment''; see <a href="xcu_chap02.html#tag_02_09_03_02"><i>Asynchronous Lists</i></a> .</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>jobs</i> utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>.</p>
|
|
|
|
<p>The following options shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-l</b></dt>
|
|
|
|
<dd>(The letter ell.) Provide more information about each job listed. This information shall include the job number, current job,
|
|
process group ID, state, and the command that formed the job.</dd>
|
|
|
|
<dt><b>-p</b></dt>
|
|
|
|
<dd>Display only the process IDs for the process group leaders of the selected jobs.</dd>
|
|
</dl>
|
|
|
|
<p>By default, the <i>jobs</i> utility shall display the status of all stopped jobs, running background jobs and all jobs whose
|
|
status has changed and have not been reported by the shell.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operand shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>job_id</i></dt>
|
|
|
|
<dd>Specifies the jobs for which the status is to be displayed. If no <i>job_id</i> is given, the status information for all jobs
|
|
shall be displayed. The format of <i>job_id</i> is described in the Base Definitions volume of IEEE Std 1003.1-2001, <a
|
|
href="../basedefs/xbd_chap03.html#tag_03_203">Section 3.203, Job Control Job ID</a>.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>jobs</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
|
|
opposed to multi-byte characters in arguments).</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and
|
|
informative messages written to standard output.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>If the <b>-p</b> option is specified, the output shall consist of one line for each process ID:</p>
|
|
|
|
<pre>
|
|
<tt>"%d\n", <</tt><i>process ID</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>Otherwise, if the <b>-l</b> option is not specified, the output shall be a series of lines of the form:</p>
|
|
|
|
<pre>
|
|
<tt>"[%d] %c %s %s\n", <</tt><i>job-number</i><tt>>, <</tt><i>current</i><tt>>, <</tt><i>state</i><tt>>, <</tt><i>command</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where the fields shall be as follows:</p>
|
|
|
|
<dl compact>
|
|
<dt><<i>current</i>></dt>
|
|
|
|
<dd>The character <tt>'+'</tt> identifies the job that would be used as a default for the <a href=
|
|
"../utilities/fg.html"><i>fg</i></a> or <a href="../utilities/bg.html"><i>bg</i></a> utilities; this job can also be specified
|
|
using the <i>job_id</i> %+ or <tt>"%%"</tt> . The character <tt>'-'</tt> identifies the job that would become the default if the
|
|
current default job were to exit; this job can also be specified using the <i>job_id</i> %-. For other jobs, this field is a
|
|
<space>. At most one job can be identified with <tt>'+'</tt> and at most one job can be identified with <tt>'-'</tt> . If
|
|
there is any suspended job, then the current job shall be a suspended job. If there are at least two suspended jobs, then the
|
|
previous job also shall be a suspended job.</dd>
|
|
|
|
<dt><<i>job-number</i>></dt>
|
|
|
|
<dd>A number that can be used to identify the process group to the <a href="../utilities/wait.html"><i>wait</i></a>, <a href=
|
|
"../utilities/fg.html"><i>fg</i></a>, <a href="../utilities/bg.html"><i>bg</i></a>, and <a href=
|
|
"../utilities/kill.html"><i>kill</i></a> utilities. Using these utilities, the job can be identified by prefixing the job number
|
|
with <tt>'%'</tt> .</dd>
|
|
|
|
<dt><<i>state</i>></dt>
|
|
|
|
<dd>One of the following strings (in the POSIX locale):
|
|
|
|
<dl compact>
|
|
<dt><b>Running</b></dt>
|
|
|
|
<dd>Indicates that the job has not been suspended by a signal and has not exited.</dd>
|
|
|
|
<dt><b>Done</b></dt>
|
|
|
|
<dd>Indicates that the job completed and returned exit status zero.</dd>
|
|
|
|
<dt><b>Done</b>(<i>code</i>)</dt>
|
|
|
|
<dd>Indicates that the job completed normally and that it exited with the specified non-zero exit status, <i>code</i>, expressed as
|
|
a decimal number.</dd>
|
|
|
|
<dt><b>Stopped</b></dt>
|
|
|
|
<dd>Indicates that the job was suspended by the SIGTSTP signal.</dd>
|
|
|
|
<dt><b>Stopped</b> (<b>SIGTSTP</b>)</dt>
|
|
|
|
<dd><br>
|
|
Indicates that the job was suspended by the SIGTSTP signal.</dd>
|
|
|
|
<dt><b>Stopped</b> (<b>SIGSTOP</b>)</dt>
|
|
|
|
<dd><br>
|
|
Indicates that the job was suspended by the SIGSTOP signal.</dd>
|
|
|
|
<dt><b>Stopped</b> (<b>SIGTTIN</b>)</dt>
|
|
|
|
<dd><br>
|
|
Indicates that the job was suspended by the SIGTTIN signal.</dd>
|
|
|
|
<dt><b>Stopped</b> (<b>SIGTTOU</b>)</dt>
|
|
|
|
<dd><br>
|
|
Indicates that the job was suspended by the SIGTTOU signal.</dd>
|
|
</dl>
|
|
|
|
<p>The implementation may substitute the string <b>Suspended</b> in place of <b>Stopped</b>. If the job was terminated by a signal,
|
|
the format of <<i>state</i>> is unspecified, but it shall be visibly distinct from all of the other <<i>state</i>>
|
|
formats shown here and shall indicate the name or description of the signal causing the termination.</p>
|
|
</dd>
|
|
|
|
<dt><<i>command</i>></dt>
|
|
|
|
<dd>The associated command that was given to the shell.</dd>
|
|
</dl>
|
|
|
|
<p>If the <b>-l</b> option is specified, a field containing the process group ID shall be inserted before the <<i>state</i>>
|
|
field. Also, more processes in a process group may be output on separate lines, using only the process ID and
|
|
<<i>command</i>> fields.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_11"></a>STDERR</h4>
|
|
|
|
<blockquote>
|
|
<p>The standard error shall be used only for diagnostic messages.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_12"></a>OUTPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_13"></a>EXTENDED DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_14"></a>EXIT STATUS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following exit values shall be returned:</p>
|
|
|
|
<dl compact>
|
|
<dt> 0</dt>
|
|
|
|
<dd>Successful completion.</dd>
|
|
|
|
<dt>>0</dt>
|
|
|
|
<dd>An error occurred.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_15"></a>CONSEQUENCES OF ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_04_70_16"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <b>-p</b> option is the only portable way to find out the process group of a job because different implementations have
|
|
different strategies for defining the process group of the job. Usage such as $( <i>jobs</i> <b>-p</b>) provides a way of referring
|
|
to the process group of the job in an implementation-independent way.</p>
|
|
|
|
<p>The <i>jobs</i> utility does not work as expected when it is operating in its own utility execution environment because that
|
|
environment has no applicable jobs to manipulate. See the APPLICATION USAGE section for <a href="bg.html"><i>bg</i></a> . For this
|
|
reason, <i>jobs</i> is generally implemented as a shell regular built-in.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_17"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_18"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>Both <tt>"%%"</tt> and <tt>"%+"</tt> are used to refer to the current job. Both forms are of equal validity-the <tt>"%%"</tt>
|
|
mirroring <tt>"$$"</tt> and <tt>"%+"</tt> mirroring the output of <i>jobs</i>. Both forms reflect historical practice of the
|
|
KornShell and the C shell with job control.</p>
|
|
|
|
<p>The job control features provided by <a href="../utilities/bg.html"><i>bg</i></a>, <a href="../utilities/fg.html"><i>fg</i></a>,
|
|
and <i>jobs</i> are based on the KornShell. The standard developers examined the characteristics of the C shell versions of these
|
|
utilities and found that differences exist. Despite widespread use of the C shell, the KornShell versions were selected for this
|
|
volume of IEEE Std 1003.1-2001 to maintain a degree of uniformity with the rest of the KornShell features selected (such
|
|
as the very popular command line editing features).</p>
|
|
|
|
<p>The <i>jobs</i> utility is not dependent on the job control option, as are the seemingly related <a href=
|
|
"../utilities/bg.html"><i>bg</i></a> and <a href="../utilities/fg.html"><i>fg</i></a> utilities because <i>jobs</i> is useful for
|
|
examining background jobs, regardless of the condition of job control. When the user has invoked a <a href=
|
|
"../utilities/set.html"><i>set</i></a> <b>+m</b> command and job control has been turned off, <i>jobs</i> can still be
|
|
used to examine the background jobs associated with that current session. Similarly, <a href=
|
|
"../utilities/kill.html"><i>kill</i></a> can then be used to kill background jobs with <a href=
|
|
"../utilities/kill.html"><i>kill</i></a>% <<i>background job number</i>>.</p>
|
|
|
|
<p>The output for terminated jobs is left unspecified to accommodate various historical systems. The following formats have been
|
|
witnessed:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p><b>Killed</b>( <i>signal name</i>)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p><i>signal name</i></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p><i>signal name</i>( <b>coredump</b>)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p><i>signal description</i>- <b>core dumped</b></p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>Most users should be able to understand these formats, although it means that applications have trouble parsing them.</p>
|
|
|
|
<p>The calculation of job IDs was not described since this would suggest an implementation, which may impose unnecessary
|
|
restrictions.</p>
|
|
|
|
<p>In an early proposal, a <b>-n</b> option was included to "Display the status of jobs that have changed, exited, or stopped
|
|
since the last status report". It was removed because the shell always writes any changed status of jobs before each prompt.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_19"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_20"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="xcu_chap02.html#tag_02_12"><i>Shell Execution Environment</i></a> , <a href="bg.html"><i>bg</i></a> , <a href=
|
|
"fg.html"><i>fg</i></a> , <a href="kill.html"><i>kill</i>()</a> , <a href="wait.html"><i>wait</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_21"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_70_22"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>This utility is marked as part of the User Portability Utilities option.</p>
|
|
|
|
<p>The JC shading is removed as job control is mandatory in this issue.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|