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 +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