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 May 1, 2025 +.Dd May 2, 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 +.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 +.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,49 @@ To include a .Ql - , make it the first or last character listed. +.Ss Job Control +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 suspend the execution of processes, +continue 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 "%?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 string +.Ar 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,10 +2033,16 @@ 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 +or the current job, if no +.Ar job_id Ns s +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 @@ -2349,10 +2399,15 @@ .It Va HISTSIZE The number of previous commands that are accessible. .El -.It Ic fg Op Ar job -Move the specified -.Ar job -or the current job to the foreground. +.It Ic fg Op Ar job_id +Move the job with specified +.Ar job_id +or the current job, if no +.Ar job_id Ns s +are given, to the foreground. +Refer to +.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 @@ -2430,33 +2485,120 @@ 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 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 +See +.Sx Job Control +for a list of job ID forms. +.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. +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. -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 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 fg , +.Ic bg , +.Ic wait +and +.Ic kill +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 "" +.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 +.Xr signal 3 . +.It Suspended ( Ar signal ) +Indicates that the job was suspended by the +.Xr signal 3 +.Ar signal , +which can be either +.Dv SIGTSTP , +.Dv SIGSTOP , +.Dv SIGTTIN +or +.Dv SIGTTOU . +.El +.It Ar 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 +.Ar 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 +2955,18 @@ 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 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 +3081,7 @@ .Xr execve 2 , .Xr getrlimit 2 , .Xr umask 2 , +.Xr signal 3 , .Xr wctype 3 , .Xr editrc 5 , .Xr shells 5