Page MenuHomeFreeBSD
Files F142163041

D49895.id167211.diff
No OneTemporary
Actions

D49895.id167211.diff
View Options

diff --git a/bin/sh/sh.1 b/bin/sh/sh.1
--- a/bin/sh/sh.1
+++ b/bin/sh/sh.1
@@ -31,7 +31,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd November 17, 2025
+.Dd November 27, 2025
.Dt SH 1
.Os
.Sh NAME
@@ -254,10 +254,9 @@
.It Fl l
Force the shell to act as if it has been invoked as a login shell.
.It Fl m Li monitor
-Turn on job control (set automatically when interactive).
-A new process group is created for each pipeline (called a job).
-It is possible to suspend jobs or to have them run in the foreground or
-in the background.
+Turn on Job Control (see
+.Sx Job Control ) .
+Set automatically when interactive.
In a non-interactive shell,
this option can be set even if no terminal is available
and is useful to place processes in separate process groups.
@@ -1120,7 +1119,9 @@
Any changes do not affect the parent shell environment.
.Pp
A subshell environment may be implemented as a child process or differently.
-If job control is enabled in an interactive shell,
+If job control (see
+.Sx Job Control )
+is enabled in an interactive shell,
commands grouped in parentheses can be suspended and continued as a unit.
.Pp
For compatibility with other shells,
@@ -1940,6 +1941,51 @@
To include a
.Ql - ,
make it the first or last character listed.
+.Ss Job Control
+A job is a set of processes, comprising a shell pipeline
+(see
+.Sx Pipelines ) ,
+and any processes descended from it, that are all
+in the same process group.
+.Pp
+A job control is a facility that allows users to
+selectively suspend the execution of processes,
+continue their execution at a later point,
+and run them in the foreground or in the background.
+.Pp
+A job ID is a handle that is used to refer to a job.
+It can take any of the following forms:
+.Bl -tag -width "%?string"
+.It Cm %%
+Current job.
+.It Cm %+
+Current job.
+.It Cm %-
+Previous job.
+.It Cm % Ns Ar n
+Job number
+.Ar n .
+.It Cm % Ns Ar string
+Job whose command begins with
+.Ar string .
+.It Cm %? Ns Ar string
+Job whose command contains
+.Ar string .
+.El
+.Pp
+The job control built-in commands
+are:
+.Ic bg ,
+.Ic fg ,
+.Ic jobid
+and
+.Ic jobs .
+Commands that accept job ID as an argument:
+.Ic kill ,
+.Ic wait .
+See
+.Sx Built-in Commands
+section below.
.Ss Built-in Commands
This section lists the built-in commands.
.Bl -tag -width indent
@@ -1993,6 +2039,9 @@
Continue the specified jobs
(or the current job if no jobs are given)
in the background.
+See
+.Sx Job Control
+for a list of job ID forms.
.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc
List or alter key bindings for the line editor.
This command is documented in
@@ -2353,6 +2402,9 @@
Move the specified
.Ar job
or the current job to the foreground.
+See
+.Sx Job Control
+for a list of job ID forms.
.It Ic getopts Ar optstring var
Parse command-line options and arguments.
The first argument
@@ -2436,19 +2488,106 @@
If the
.Ar job
argument is omitted, use the current job.
+See
+.Sx Job Control
+for a list of job ID forms.
.It Ic jobs Oo Fl lps Oc Op Ar job ...
Print information about the specified jobs, or all jobs if no
.Ar job
argument is given.
-The information printed includes job ID, status and command name.
+See
+.Sx Job Control
+for a list of job ID forms.
.Pp
If the
.Fl l
-option is specified, the PID of each job is also printed.
+option is not specified, the output line is the following
+for each job:
+.Dl Oo Ar job_number Oc Ar current Ar state Ar command
+where:
+.Bl -tag -width "job_number"
+.It Ar job_number
+A number that can be used to identify the process group to the
+.Ic bg ,
+.Ic fg ,
+.Ic kill
+and
+.Ic wait
+commands.
+Using these commands, the job can be identified by prefixing
+the
+.Ar job_number
+with
+.Cm % .
+See also
+.Sx Job Control .
+.It Ar current
+One of the following characters:
+.Bl -tag -width "<space>"
+.It Cm +
+Identifies the job that would be used as a default for the
+.Ic fg
+or
+.Ic bg
+commands.
+At most one job can be identified with it.
+.It Cm -
+Identifies the job that would become the default if the
+current default job were to exit.
+At most one job can be identified with it.
+.It Cm Ao space Ac
+For all other jobs that are neither marked with
+.Cm +
+nor
+.Cm - .
+.El
+.It Ar state
+One of the following strings, describing the current job state:
+.Bl -tag -width "Suspended (signal)"
+.It Running
+Indicates that the job has not been suspended by a signal and
+has not exited.
+.It Done
+Indicates that the job completed and returned exit status zero.
+.It Done Ns ( Ar code )
+Indicates that the job completed normally and that it exited
+with the specified non-zero exit status,
+.Ar code ,
+expressed as a decimal number.
+.It Suspended
+Indicates that the job was suspended by the
+.Dv SIGTSTP
+signal (see
+.Xr signal 3 ) .
+.It Suspended ( Ar signal )
+Indicates that the job was suspended by the
+.Ar signal ,
+which can be either
+.Dv SIGTSTP ,
+.Dv SIGSTOP ,
+.Dv SIGTTIN
+or
+.Dv SIGTTOU .
+See
+.Xr signal 3
+for signals meaning.
+.El
+.It Ar command
+The associated command that was given to the shell.
+.El
+.Pp
+If the
+.Fl l
+option is specified, the PID of the job is
+inserted before the
+.Ar state
+field.
+.Pp
If the
.Fl p
option is specified, only the process IDs for the process group leaders
are printed, one per line.
+.Pp
If the
.Fl s
option is specified, only the PIDs of the job commands are printed, one per
@@ -2456,7 +2595,11 @@
.It Ic kill
A built-in equivalent of
.Xr kill 1
-that additionally supports sending signals to jobs.
+that additionally supports sending signals to jobs,
+by means of specifying their job IDs (see the possible
+forms of job ID in
+.Sx Job Control )
+as arguments.
.It Ic local Oo Ar variable ... Oc Op Fl
See the
.Sx Functions
@@ -2941,6 +3084,7 @@
.Xr execve 2 ,
.Xr getrlimit 2 ,
.Xr umask 2 ,
+.Xr signal 3 ,
.Xr wctype 3 ,
.Xr editrc 5 ,
.Xr shells 5

File Metadata

Mime Type
text/plain
Expires
Sat, Jan 17, 3:41 PM (14 h, 25 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
26303088
Default Alt Text
D49895.id167211.diff (5 KB)

Event Timeline