Page MenuHomeFreeBSD
Files F148891124

D49895.1789101679.diff
No OneTemporary
Actions

Size
7 KB
Referenced Files
None
Subscribers
None

D49895.1789101679.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 March 8, 2025
+.Dd April 18, 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,50 @@
To include a
.Ql - ,
make it the first or last character listed.
+.Ss Job Control
+.Pp
+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
+Job control is a facility that allows users selectively
+to stop (suspend) the execution of processes,
+continue (resume) their execution at a later point,
+to run them in the foreground or in the background.
+.Pp
+Job ID is a handle that is used to refer to a job.
+It can be any of the following forms:
+.Bl -tag -width indent
+.It Li %%
+current job.
+.It Li %+
+current job.
+.It Li %-
+previous job.
+.It Li % Ns Em n
+job number
+.Em n .
+.It Li % Ns Em string
+job whose command begins with
+.Em string .
+.It Li %? Ns Em string
+job whose command contains string
+.Em string .
+.El
+.Pp
+The job control
+.Sx Built-in Commands
+are:
+.Ic jobs ,
+.Ic jobid ,
+.Ic fg
+and
+.Ic bg .
+The commands, that accept job ID as an argument:
+.Ic kill ,
+.Ic wait .
.Ss Built-in Commands
This section lists the built-in commands.
.Bl -tag -width indent
@@ -1989,9 +2034,14 @@
Also see the
.Sx Aliases
subsection.
-.It Ic bg Op Ar job ...
-Continue the specified jobs
-(or the current job if no jobs are given)
+.It Ic bg Op Ar job_id ...
+Continue the jobs with specified
+.Ar job_id Ns s
+(see
+.Sx Job Control )
+(or the current job if no
+.Ar job_id Ns s
+are given)
in the background.
.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc
List or alter key bindings for the line editor.
@@ -2349,9 +2399,11 @@
.It Va HISTSIZE
The number of previous commands that are accessible.
.El
-.It Ic fg Op Ar job
-Move the specified
-.Ar job
+.It Ic fg Op Ar job_id
+Move the job with specified
+.Ar job_id
+(see
+.Sx Job Control )
or the current job to the foreground.
.It Ic getopts Ar optstring var
Parse command-line options and arguments.
@@ -2430,33 +2482,116 @@
option causes the
.Ic hash
command to delete all the entries in the hash table except for functions.
-.It Ic jobid Op Ar job
-Print the process IDs of the processes in the specified
-.Ar job .
+.It Ic jobid Op Ar job_id
+Print the process IDs of the processes in the job with specified
+.Ar job_id
+(see
+.Sx Job Control ).
If the
-.Ar job
+.Ar job_id
argument is omitted, use the current job.
-.It Ic jobs Oo Fl lps Oc Op Ar job ...
-Print information about the specified jobs, or all jobs if no
-.Ar job
+.It Ic jobs Oo Fl lps Oc Op Ar job_id ...
+Print information about the specified job IDs, or all job IDs if no
+.Ar job_id
argument is given.
-The information printed includes job ID, status and command name.
.Pp
If the
-.Fl l
-option is specified, the PID of each job is also printed.
-If the
.Fl p
option is specified, only the process IDs for the process group leaders
are printed, one per line.
If the
.Fl s
-option is specified, only the PIDs of the job commands are printed, one per
-line.
+option is specified, only the PIDs of the job commands are printed,
+one per line.
+.Pp
+If the
+.Fl l
+option is not specified, the output line is the following
+for each job:
+.Dl [ Em job_number ] Em current Em state Em command
+where:
+.Bl -tag -width indent
+.It Em job_number
+A number that can be used to identify the process group to the
+.Ic fg ,
+.Ic bg ,
+.Ic wait
+and
+.Ic kill
+commands.
+Using these commands, the job can be identified by prefixing
+the
+.Em job_number
+with
+.Li % .
+See also
+.Sx Job Control .
+.It Em current
+One of the following characters:
+.Bl -tag -width indent
+.It Li +
+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 Li -
+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 <space>
+For all other jobs that are neither marked with
+.Li +
+nor
+.Li - .
+.El
+.It Em state
+One of the following strings, describing the current job state:
+.Bl -tag -width indent
+.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 ( Em code )
+Indicates that the job completed normally and that it exited
+with the specified non-zero exit status,
+.Em code ,
+expressed as a decimal number.
+.It Suspended
+Indicates that the job was suspended by the
+.Dv SIGTSTP
+.Xr signal 3 .
+.It Suspended ( Em signal )
+Indicates that the job was suspended by the
+.Xr signal 3
+.Em signal ,
+which can be either
+.Dv SIGTSTP ,
+.Dv SIGSTOP ,
+.Dv SIGTTIN
+or
+.Dv SIGTTOU .
+.El
+.It Em command
+The associated command that was given to the shell.
+.El
+.Pp
+If the
+.Fl l
+option is specified, a field containing the process group ID
+is inserted before the
+.Em state
+field.
.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
@@ -2813,16 +2948,20 @@
option is specified, the
.Ar name
arguments are treated as function names.
-.It Ic wait Op Ar job ...
+.It Ic wait Op Ar job_id ...
Wait for each specified
-.Ar job
+.Ar job_id
+(see
+.Sx Job Control )
to complete and return the exit status of the last process in the
-last specified
-.Ar job .
-If any
-.Ar job
-specified is unknown to the shell, it is treated as if it
-were a known job that exited with exit status 127.
+job with last specified
+.Ar job_id .
+If any job, that has a specified
+.Ar job_id
+is unknown to the shell,
+.Ar job_id
+is treated as if it was a job ID of a known job that
+exited with exit status 127.
If no operands are given, wait for all jobs to complete
and return an exit status of zero.
.El
@@ -2937,6 +3076,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
Fri, Sep 11, 4:41 AM (22 h, 15 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
29549913
Default Alt Text
D49895.1789101679.diff (7 KB)

Event Timeline