bin/ksh/sh.1

.\"	$OpenBSD: sh.1,v 1.157 2023/05/13 18:34:49 jmc Exp $
.\"
.\" Copyright (c) 2015 Jason McIntyre <jmc@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: May 13 2023 $
.Dt SH 1
.Os
.Sh NAME
.Nm sh
.Nd command language interpreter
.Sh SYNOPSIS
.Nm sh
.Op Fl abCefhimnuvx
.Op Fl o Ar option
.Op Fl c Ar string | Fl s | Ar file
.Sh DESCRIPTION
The
.Nm
utility is a
.Em command language interpreter :
it reads one or more commands,
either from the command line or from a file
(a shell script),
and then sets about executing those commands.
Thus it is the
main interface between the user and the operating system.
.Pp
This version of
.Nm
is actually
.Nm ksh
in disguise.
As such, it also supports the features described in
.Xr ksh 1 .
This manual page describes only the parts
relevant to a POSIX compliant
.Nm .
If portability is a concern,
use only those features described in this page.
.Pp
The shell receives input as follows:
.Pp
.Bl -tag -width "-c stringXXX" -offset indent -compact
.It Fl c Ar string
Read commands from
.Ar string .
.It Fl s
Read commands from standard input
(the default).
.It Ar file
Read commands from
.Ar file .
.El
.Pp
The options below can be specified with a
.Sq Cm +
rather than
.Sq Fl ,
meaning to unset the option.
They can also be set or unset using the
.Ic set
command.
Some options have equivalent long names,
indicated at the start of the description,
which can be used with the
.Fl o
option.
.Bl -tag -width Ds
.It Fl a
Allexport.
Variable assignments are exported to all child processes
of the running shell.
If the assignment precedes a command it does not persist
after that command has finished running,
unless the command is a special builtin
or one of the builtins
.Ic getopts
or
.Ic read
makes the assignment.
.It Fl b
Notify.
The user is given notice asynchronously when background jobs complete.
.It Fl C
Noclobber.
Do not permit the redirection operator
.Pq Sq >
to clobber (overwrite) existing files.
.It Fl e
Errexit.
Exit the shell immediately should an error occur or a command fail.
For pipelines and
.Cm &&
and
.Cm ||
constructs, only exit if the last component fails.
Errexit is ignored for
.Ic while ,
.Ic until ,
.Ic if ,
and
.Ic elif
lists and pipelines beginning
.Sq !\& .
.It Fl f
Noglob.
Do not expand file name patterns.
.It Fl h
When a utility is first executed,
hash (record) its location
so that future invocations do not need to search for it.
.It Fl i
Enable behaviour convenient for an interactive shell.
This option is set by default
if the session is attached to a terminal.
.It Fl m
Monitor.
Fully enable job control:
enable the
.Ic bg
and
.Ic fg
builtins;
report completion status when jobs finish;
report when a foreground process stops;
and report when a job changes status.
The processes of a job share their own process group.
This option is set by default for interactive shells.
.It Fl n
Noexec.
Read commands but do not execute them \(en
useful for checking syntax errors in scripts.
This option is ignored for interactive shells.
.It Fl o Ar option
Specify an option by its long name.
Those described below have no equivalent option letter:
.Pp
.Bl -tag -width "ignoreeof" -offset 3n -compact
.It ignoreeof
Ignore an end-of-file
.Pq Sq ^D .
EOF normally logs a user out,
so setting this can prevent accidental logouts
(the user will need to explicitly use the
.Ic exit
command).
.It nolog
Do not enter function definitions into command history.
.It posix
Enable POSIX mode
(see
.Sx STANDARDS ) .
.It vi
Enable
.Xr vi 1
command line editing.
.El
.It Fl u
Nounset.
If a command references an unset parameter,
write an error to standard output instead of executing the command.
This option is ignored for the special parameters
.Sq *
and
.Sq @ .
If the shell is not interactive,
immediately exit.
.It Fl v
Verbose.
Write input to standard error after reading it.
.It Fl x
Xtrace.
Write a trace for each command to standard error after expanding it,
and before executing it.
.El
.Sh BUILTINS
The shell has a number of
.Em built-ins
available:
utilities that are included as part of the shell.
The shell does not need to search for them
and can execute them directly.
.Pp
A number of built-ins are special in that
a syntax error can cause a running shell to abort,
and, after the built-in completes,
variable assignments remain in the current environment.
The following built-ins are special:
.Ic .\& , :\& , break , continue ,
.Ic eval , exec , exit , export ,
.Ic readonly , return , set , shift ,
.Ic times , trap ,
and
.Ic unset .
.Pp
The built-ins available to
.Nm
are listed below.
Unless otherwise indicated,
they exit 0 on success,
and >0 if an error occurs.
.Bl -tag -width 2n
.It Ic .\& Ar file
Execute the commands in
.Ar file ,
in the current environment.
The actual file need not be executable,
and its location is determined by searching
.Ev PATH
if there are no slashes in the filename.
The exit status is that of the last command returned,
or zero if no commands were executed.
If no readable file can be found,
a non-interactive shell will abort;
an interactive shell writes an error message
and returns a non-zero exit status.
.It Ic :\& Op Ar arg ...
The
.Ic :\&
command does nothing \(en
it is a placeholder for when a command is required.
Its exit status is always zero.
.It Ic alias Op Ar name Ns Oo = Ns Ar value Oc Ar ...
Define an alias
.Ar name
to
.Ar value ;
when the shell encounters a command name that is an alias,
its value is substituted.
If
.Ar value
ends in a blank,
the next word is checked for alias substitution too.
If only a
.Ar name
is specified,
display the value of that alias;
if no arguments are given,
list all aliases and their values.
Aliases are visible in the current environment and that of subshells,
but not by the parent process of the current shell
or by utilities invoked by it.
.It Ic bg Op Ar id ...
Select a job by
.Ar id
(see the
.Ic jobs
command, below)
to run in the background.
The default job is
.Qq %+ .
.It Ic break Op Ar n
Exit from the innermost
.Ic for , while ,
or
.Ic until
loop,
or from loop level
.Ar n .
.It Ic cd Oo Fl L | P Oc Op Ar dir
Change the current working directory to
.Ar dir ,
or
.Ev $HOME
by default.
If
.Ar dir
is set to
.Sq - ,
change to the previous working directory and
print the (now current) working directory.
If
.Ar dir
does not begin with a slash or dot,
.Ev CDPATH
is searched for the directory.
.Pp
The options to the
.Ic cd
command are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl L
Do not resolve symbolic links before processing
.Qq ..
components.
.It Fl P
Resolve symbolic links before processing
.Qq ..
components.
.El
.It Ic command Oo Fl p | V | v Oc Ar command Op Ar arg ...
Invoke
.Ar command
(and any optional arguments),
overriding any functions with the same name,
and without any of the properties that special built-ins have.
.Pp
The options to
.Ic command
are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl p
Use a default value for
.Ev PATH
to search for the command.
.It Fl V
Do not invoke
.Ar command ,
but identify how the shell will interpret it
(such as a function or special built-in).
.It Fl v
Do not invoke
.Ar command ,
but identify the pathname the shell will use to run it.
For aliases, a command to define that alias is printed.
For shell reserved words, shell functions, and built-in utilities,
just the name is printed.
.El
.Pp
The exit status is that of
.Ar command ,
or 126 if
.Ar command
could not be invoked,
or 127 if an error occurred in
.Ic command
itself or
.Ar command
could not be found.
If the options
.Fl V
or
.Fl v
are given,
the exit status is 0 on success,
or >0 if an error occurs.
.It Ic continue Op Ar n
Go directly to the next iteration of the innermost
.Ic for , while ,
or
.Ic until
loop,
or from loop level
.Ar n .
.It Ic eval Op Ar arg ...
Concatenate the arguments given
and interpret them as a command.
The exit status is that of the resulting command,
zero if no arguments are given,
or >0 if the resulting command could not be correctly parsed.
.It Ic exec Op Ar command Op Ar arg ...
Replace the shell with
.Ar command
(and any optional arguments),
without creating a new process.
The exit status is that of
.Ar command ,
or 126 if
.Ar command
could not be invoked,
or 127 if
.Ar command
could not be found.
If no command is given but a redirection happens,
the exit status is 1\(en125;
otherwise
.Ic exec
returns 0.
.It Ic exit Op Ar n
Exit the shell with exit status
.Ar n ,
or that of the last command executed.
.It Ic export Oo Fl p Oc Ar name Ns Oo = Ns Ar value Oc Ar ...
Make the variable
.Ar name
visible to subsequently run commands,
optionally setting it to
.Ar value .
.Pp
The options to the
.Ic export
command are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl p
List all exported variables in a manner that can be reinput to the shell.
.El
.It Ic false
Return a false (non-zero) value.
.It Xo
.Ic fc
.Op Fl lnr
.Op Fl e Ar editor
.Op Fl s Op Ar old Ns = Ns Ar new
.Op Ar first Op Ar last
.Xc
Edit commands from command history using
.Xr ed 1 .
After editing,
the new commands are executed by the shell.
.Pp
The options to the
.Ic fc
command are as follows:
.Pp
.Bl -tag -width "-s [old=new]" -offset 3n -compact
.It Fl e Ar editor
Edit commands using
.Ar editor .
See also
.Ev FCEDIT .
.It Fl l
List the command history.
.It Fl ln
List the command history without command numbers.
.It Fl r
Edit or list
.Pq Fl lr
commands in reverse order.
.It Fl s Op Ar old Ns = Ns Ar new
Reexecute a single command
without invoking an editor.
The first occurrence of the string
.Ar old
in the command is replaced by
.Ar new .
.El
.Pp
A range of commands can be specified,
.Ar first
to
.Ar last .
Their format can be numerical,
to select by command number;
.Sq - Ns Ar n ,
to select a command executed that number of commands previous;
or a string which matches the beginning of the command.
If no range is given,
the last command in command history is edited,
or reexecuted
.Pq Fl s ,
or the previous 16 commands in command history are listed
.Pq Fl l .
If
.Ar first
is newer than
.Ar last ,
commands are processed in reverse order
(as if
.Fl r
had been given);
if either are out of range,
the oldest or newest values are used.
.It Ic fg Op Ar id ...
Select a job by
.Ar id
(see the
.Ic jobs
command, below)
to run in the foreground.
The default job is
.Qq %+ .
.It Ic getopts Ar optstring name Op Ar arg ...
When invoked,
.Ic getopts
processes the positional parameters
(or any
.Ar arg
passed to it)
as a list of options and option arguments.
.Ic getopts
sets the variable
.Ar name
to the option found,
.Ev OPTARG
to its argument,
and
.Ev OPTIND
to the index of the next variable to be processed.
.Pp
The string
.Ar optstring
contains a list of acceptable options;
a colon following an option indicates it requires an argument.
If an option not recognised by
.Ar optstring
is found,
.Ar name
is set to
.Sq ?\& ;
if the first character of
.Ar optstring
is a colon,
.Ev OPTARG
is set to the unsupported option,
otherwise an error message is displayed.
.Pp
The following code fragment shows how one might process the arguments
for a command that can take the option
.Fl a
and the option
.Fl o ,
which requires an argument.
.Bd -literal -offset indent
while getopts ao: name
do
	case $name in
	a)	flag=1 ;;
	o)	oarg=$OPTARG ;;
	?)	echo "Usage: ..."; exit 2 ;;
	esac
done
shift $(($OPTIND - 1))
echo "Non-option arguments: " "$@"
.Ed
.It Ic hash Op Fl r | Ar utility
Add
.Ar utility
to the hash list
or remove
.Pq Fl r
all utilities from the hash list.
Without arguments, show the utilities currently hashed.
.It Ic jobs Oo Fl l | p Oc Op Ar id ...
Display the status of all jobs in the current shell environment,
or those selected by
.Ar id .
.Pp
The options to the
.Ic jobs
command are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl l
Additionally display the process group ID.
.It Fl p
Display only the process group ID.
.El
.Pp
Job
.Ar id
can be selected in one of the following ways:
.Pp
.Bl -tag -width "%?string" -offset 3n -compact
.It %%
The current job.
.It %+
The current job.
.It %-
The previous job.
.It % Ns Ar n
Job number
.Ar n .
.It % Ns Ar string
Job with command matching
.Ar string .
.It %? Ns Ar string
Job with command containing
.Ar string .
.El
.It Xo
.Ic kill
.Op Fl l Op Ar signal
.Op Fl s Ar signal
.Oo Fl Ar signal Oc Ar pid ...
.Xc
Send a signal,
by default
.Dv SIGTERM ,
to the process with ID
.Ar pid .
.Pp
The options to the
.Ic kill
command are as follows:
.Pp
.Bl -tag -width "-l [signal]" -offset 3n -compact
.It Fl l Op Ar signal
List all supported signals,
or the signal name corresponding to
.Ar signal
number or the exit status of a command killed by a signal.
.It Fl s Ar signal
Send the process
.Ar signal
name.
.It Fl Ar signal
Send the process
.Ar signal
name or number.
.It Ar pid
A process ID,
process group ID,
or a job ID (see
.Ic jobs ,
above).
The process ID 0 signals all processes in the current process group.
.El
.Pp
The supported signal numbers are:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It " 0"
Do not signal a process,
but determine whether an ID exists.
.It " 1"
.Dv SIGHUP :
Terminal line hangup.
.It " 2"
.Dv SIGINT :
Interrupt a program.
.It " 3"
.Dv SIGQUIT :
Quit a program.
.It " 6"
.Dv SIGABRT :
Call
.Xr abort 3 .
.It " 9"
.Dv SIGKILL :
Kill a program.
Cannot be caught or ignored.
.It "14"
.Dv SIGALRM :
Real-time timer expired.
.It "15"
.Dv SIGTERM :
Software termination signal.
.El
.It Ic pwd Op Fl L | P
Print the current working directory.
.Pp
The options to the
.Ic pwd
command are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl L
Print the logical path to the current working directory
i.e. display symbolic links followed.
.It Fl P
Print the physical path to the current working directory
i.e. display symbolic links resolved.
.El
.Pp
If both options are given,
the last specified is used;
if none are given,
the default is
.Fl L .
.It Ic read Oo Fl r Oc Ar name ...
Read a line from standard input.
The line is split into fields,
with each field assigned to a variable,
.Ar name ,
in turn
(first field assigned to first variable, and so on).
If there are more fields than variables,
the last variable will contain all the remaining fields.
If there are more variables than fields,
the remaining variables are set to empty strings.
A backslash in the input line causes the shell to prompt for further input.
.Pp
The options to the
.Ic read
command are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl r
Ignore backslash sequences.
.El
.It Ic readonly Oo Fl p Oc Ar name Ns Op = Ns Ar value
Mark variable
.Ar name
as readonly,
and optionally set it to
.Ar value .
Readonly variables cannot be later assigned values or unset.
.Pp
The options to the
.Ic readonly
command are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl p
Display the names and values of all readonly variables
in a manner which can be reinput to the shell.
.El
.It Ic return Op Ar n
Exit the current function or
.Ic .\&
script with exit status
.Ar n ,
or that of the last command executed.
.It Xo
.Ic set
.Op Fl abCefhmnuvx
.Op Fl o Op Ar option
.Op Ar arg ...
.Xc
Set options and positional parameters.
Without options or arguments,
display the names and values of all shell variables.
.Pp
The options are described in the options description
at the beginning of this manual.
The sequence
.Ql set -o
displays the current option settings;
the sequence
.Ql set +o
displays,
in a format suitable to be reinput to the shell,
a command suitable to achieve the current option settings.
.Pp
Any arguments are assigned to the positional parameters,
with the special parameter
.Sq #
set to the number of positional parameters.
The sequence
.Ql set --
indicates an end to option processing
(i.e. only arguments follow);
.Ql set --
by itself unsets all positional parameters
and sets
.Sq #
to zero.
.It Ic shift Op Ar n
Shift the positional parameters
.Ar n
times
(by default once).
Parameter 1 takes the value of parameter
.Sq 1+ Ns Ar n ,
parameter 2 takes
.Sq 2+ Ns Ar n ,
and so on.
Parameters
.Sq #
down to
.Sq Po #\(mi Ns Ar n Pc Ns +1
are unset and
.Sq #
is updated to the new number of positional parameters.
If
.Ar n
is 0,
no change occurs.
.It Ic times
Display accumulated process times for the shell (user and system)
and all child processes (user and system).
.It Ic trap Op Ar action signal ...
Perform
.Ar action
whenever
.Ar signal
is caught.
Without arguments,
display a list of all traps and actions,
in a format suitable to be reinput to the shell.
.Pp
If
.Ar action
is
.Sq -
or an integer,
reset
.Ar signal
to its default value;
if it is empty
.Pq Qq ,
ignore
.Ar signal .
If
.Ar signal
is
.Qq EXIT
or 0,
perform
.Ar action
when the shell exits;
otherwise
.Ar signal
should be a signal name
(without the SIG prefix)
or number.
.It Ic true
Return a true (zero) value.
.It Ic type Ar command ...
For each
.Ar command ,
show how the shell would interpret it.
.It Ic ulimit Op Fl f Ar n
Limit the maximum size of a file that can be created to
.Ar n
blocks.
Without arguments,
display the current file size limit.
.It Ic umask Oo Fl S Oc Op Ar mask
Set the file mode creation mask to
.Ar mask .
The creation mask determines the default permissions
a newly created file or directory will have.
If
.Ar mask
is not specified,
display the current creation mask.
.Pp
The options to the
.Ic umask
command are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl S
Display symbolic output.
.El
.Pp
See
.Xr chmod 1
for the format of
.Ar mask .
.It Ic unalias Oo Fl a Oc Ar name ...
Remove the alias definition of alias
.Ar name .
.Pp
The options to the
.Ic unalias
command are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl a
Remove all alias definitions.
.El
.It Ic unset Oo Fl fv Oc Ar name ...
Unset variable or function
.Ar name .
.Pp
The options to the
.Ic unset
command are as follows:
.Pp
.Bl -tag -width Ds -offset 3n -compact
.It Fl f
Treat
.Ar name
as a function.
.It Fl v
Treat
.Ar name
as a variable (the default).
.El
.It Ic wait Op Ar pid ...
Wait until all the processes specified by process or job ID
.Ar pid
have terminated.
If no
.Ar pid
is specified,
wait until all processes have terminated.
The exit status is 0 on success,
1\(en126 if an error occurs,
or 127 if
.Ar pid
was unknown.
.El
.Sh COMMAND HISTORY AND COMMAND LINE EDITING
When a shell is interactive,
it keeps a record of commands run in a
.Em command history ,
either internally in memory or in a file,
as determined by
.Dv HISTFILE .
When
.Cm vi
command line editing mode is enabled
.Pq set -o vi ,
the command line and all the commands in command history
can be edited using commands similar to those of
.Xr vi 1 .
.Pp
There are two modes,
.Em interactive
and
.Em command .
The shell starts in interactive mode.
In this mode text is entered normally.
A
.Aq newline
executes the current command line.
The command line, unless empty, is entered into command history.
The
.Aq ESC
key is used to enter command mode,
where commands similar to those used by
.Xr vi 1
are available.
A Ctrl-L sequence
.Pq ^L
can be used in this mode to
redraw the current command line.
.Pp
Where noted,
some commands may be preceded by a numerical
.Ar count ,
which causes the command to be repeated that number of times.
The term
.Em word
is used to denote a sequence of letters, digits, or underscores;
.Em bigword
denotes a sequence of whitespace delineated characters.
.Pp
The commands for command mode:
.Bl -tag -width "<newline>"
.It Ic =
Display the possible shell word expansion.
.It Ic \e
Perform pathname expansion on the current word,
matching the largest possible unique expansion,
then enter insert mode.
.It Ic *
Perform pathname expansion on the current word,
substituting every possible expansion,
then enter insert mode.
.It Ic @ Ns Ar c
Perform the commands defined by the alias
.No _ Ns Ar c ,
where
.Ar c
is a single letter alphabetical character.
.It Oo Ar count Oc Ns Ic ~
Convert the character from lowercase to upper or vice versa.
.It Oo Ar count Oc Ns Ic .\&
Repeat the most recent non-motion command.
If no
.Ar count
is given, use that of the repeated command,
if any.
.It Oo Ar n Oc Ns Ic v
Use
.Xr vi 1
to edit command number
.Ar n
in command history,
or the current command if none given.
.It Xo
.Oo Ar count Oc Ns Ic l ,
.Oo Ar count Oc Ns Aq space
.Xc
Move right.
.It Oo Ar count Oc Ns Ic h
Move left.
.It Oo Ar count Oc Ns Ic w
Move to the start of the next word.
.It Oo Ar count Oc Ns Ic W
Move to the start of the next big word.
.It Oo Ar count Oc Ns Ic e
Move to the end of the current word,
or the end of the next word if the cursor is currently
at the end of a word.
.It Oo Ar count Oc Ns Ic E
Move to the end of the current bigword,
or the end of the next bigword if the cursor is currently
at the end of a bigword.
.It Oo Ar count Oc Ns Ic b
Move to the start of the current word,
or the start of the next word if the cursor is currently
at the start of a word.
.It Oo Ar count Oc Ns Ic B
Move to the start of the current bigword,
or the start of the next bigword if the cursor is currently
at the start of a bigword.
.It Ic ^
Move to the first non-blank character.
.It Ic $
Move to the end of the current line.
.It Ic 0
Move to the beginning of the current line.
.It Oo Ar count Oc Ns Ic |\&
Move to the beginning of the current line
or the character position specified by
.Ar count .
.It Oo Ar count Oc Ns Ic f Ns Ar c
Move to the next instance of the
character
.Ar c .
.It Oo Ar count Oc Ns Ic F Ns Ar c
Move to the last instance of the
character
.Ar c .
.It Oo Ar count Oc Ns Ic t Ns Ar c
Move to the character before the next instance of the
character
.Ar c .
.It Oo Ar count Oc Ns Ic T Ns Ar c
Move to the character after the last instance of the
character
.Ar c .
.It Oo Ar count Oc Ns Ic ;\&
Repeat the last
.Ic f , F , t ,
or
.Ic T
command.
Ignore any
.Ar count
specified with the last command.
.It Oo Ar count Oc Ns Ic ,\&
Repeat the last
.Ic f , F , t ,
or
.Ic T
command,
but in the opposite direction.
Ignore any
.Ar count
specified with the last command.
.It Ic a
Enter insert mode after the current cursor position.
.It Ic A
Enter insert mode after the end of the current line.
.It Ic i
Enter insert mode at the current cursor position.
.It Ic I
Enter insert mode at the beginning of the current line.
.It Ic R
Enter insert mode at the current cursor position,
replacing any characters thereafter.
.It Oo Ar count Oc Ns Ic c Ns Ar motion
Delete the characters between the cursor and the motion command specified,
then enter insert mode.
A special motion command,
.Ic c ,
may be used to delete the entire line.
The
.Ar count
argument is ignored for the commands
.Ic 0 , ^ , $ ,
and
.Ic c .
If the motion moves towards the beginning of the line,
the character under the cursor is not deleted;
if it moves towards the end of the line,
it is deleted.
.It Ic C
Delete the characters between the cursor and the line end,
then enter insert mode.
.It Ic S
Clear the entire line,
then enter insert mode.
.It Oo Ar count Oc Ns Ic r
Replace the character under the cursor with the next typed character.
With a
.Ar count ,
replace the current character
and the corresponding number of following characters.
.It Oo Ar count Oc Ns Ic _
After the cursor,
append a
.Aq space
and the
.Ar count Ns th
bigword (by default the last entered)
from the previous input line,
then enter insert mode.
.It Oo Ar count Oc Ns Ic x
Delete the character under the cursor,
placing it in the save buffer.
.It Oo Ar count Oc Ns Ic X
Delete the character before the cursor,
placing it in the save buffer.
.It Oo Ar count Oc Ns Ic d Ns Ar motion
Delete the characters between the cursor and the motion command specified,
placing them in the save buffer.
A special motion command,
.Ic d ,
may be used to delete the entire line.
If the motion moves towards the beginning of the line,
the character under the cursor is not deleted.
.It Oo Ar count Oc Ns Ic D
Delete the characters between the cursor and the line end,
placing them in the save buffer.
.It Oo Ar count Oc Ns Ic y Ns Ar motion
Yank (copy) the characters between the cursor and the motion command specified,
placing them in the save buffer.
A special motion command,
.Ic y ,
may be used to yank the entire line.
If the motion moves towards the beginning of the line,
the character under the cursor is not yanked.
.It Oo Ar count Oc Ns Ic Y
Yank (copy) the characters between the cursor and the line end,
placing them in the save buffer.
.It Oo Ar count Oc Ns Ic p
Paste the contents of the save buffer after the cursor.
.It Oo Ar count Oc Ns Ic P
Paste the contents of the save buffer before the cursor.
.It Oo Ar count Oc Ns Ic u
Undo the last change to the edit line.
.It Oo Ar count Oc Ns Ic U
Undo all changes to the edit line.
.It Xo
.Oo Ar count Oc Ns Ic k ,
.Oo Ar count Oc Ns Ic -\&
.Xc
Replace the current command line with the previous entry in history.
.It Xo
.Oo Ar count Oc Ns Ic j ,
.Oo Ar count Oc Ns Ic +\&
.Xc
Replace the current command line with the next entry in history.
.It Oo Ar n Oc Ns Ic G
Replace the current command line with command number
.Ar n
in command history,
or the oldest command if none given.
.It / Ns Ar pattern
Moving backwards through history,
replace the current command line with the first that matches
.Ar pattern .
A
.Sq ^
at the beginning of the pattern searches only for entries beginning with
.Ar pattern .
An empty pattern matches the last search.
.It ? Ns Ar pattern
As above,
but searching forwards.
.It Ic n
Repeat the most recent pattern search.
.It Ic N
Repeat the most recent pattern search,
but in the opposite direction.
.El
.Sh SHELL GRAMMAR
The shell reads its input as described above.
After that it follows a fairly simple chain of operations
to parse that input:
.Bl -dash
.It
The shell breaks the input into
.Em words
and
.Em operators .
Words are the command text the user wishes run;
operators are special characters which describe
how the shell should interact with the commands.
.It
The shell
.Em expands
the command text according to the rules of expansion.
.It
Words are subject to
.Em field splitting ,
where the command text is separated into commands
and arguments to commands.
.It
The shell performs any
.Em redirection .
.It
The shell runs the commands.
Argument names are assigned to
.Em positional parameters ,
with the command name itself assigned parameter 0.
.It
If the command is not being run in the background,
the shell waits for it to complete
and collects its exit status.
.El
.Ss Quoting
Some characters have special meaning to the shell and need
.Em quoting
if the user wants to indicate to the shell not to interpret them as such.
The following characters need quoting if their literal meaning is desired:
.Bd -literal -offset indent
| & ; < > ( ) $ \` \e " \(aq <space> <tab> <newline>
* ? [ # ~ = %
.Ed
.Pp
A backslash
.Pq \e
can be used to quote any character except a newline.
If a newline follows a backslash the shell removes them both,
effectively making the following line part of the current one.
.Pp
A group of characters can be enclosed within single quotes
.Pq \(aq
to quote every character within the quotes.
.Pp
A group of characters can be enclosed within double quotes
.Pq \&"
to quote every character within the quotes
except a backquote
.Pq \`
or a dollar sign
.Pq $ ,
both of which retain their special meaning.
A backslash
.Pq \e
within double quotes retains its special meaning,
but only when followed by a backquote, dollar sign,
double quote, newline, or another backslash.
An at sign
.Pq @
within double quotes has a special meaning
(see
.Sx SPECIAL PARAMETERS ,
below).
.Pp
Similarly command words need to be quoted
if they are not to be interpreted as such.
.Ss Expansion
Shell
.Em variables
are arbitrary names assigned values using the
.Sq =
operator;
the values can be retrieved using the syntax
.No $ Ns Ar variable .
Shell
.Em parameters
are variable names,
numbers,
or any of the characters listed in
.Sx SPECIAL PARAMETERS .
.Pp
The shell is able to
.Em expand
certain elements of its syntax,
allowing for a more concise notation
and providing a convenience to the user.
.Pp
Firstly, tilde expansion occurs on words beginning with the
.Sq ~
character.
Any characters following the tilde,
up to the next colon, slash, or blank,
are taken as a login name
and substituted with that user's home directory,
as defined in
.Xr passwd 5 .
A tilde by itself is expanded to the contents of the variable
.Ev HOME .
This notation can be used in variable assignments,
in the assignment half,
immediately after the equals sign or a colon,
up to the next slash or colon, if any.
.Pp
.Dl PATH=~alice:~bob/jobs
.Pp
Parameter expansion happens after tildes have been expanded,
with the value of the parameter being substituted.
The basic format is:
.Pp
.D1 $ Ns Brq Ar parameter
.Pp
The braces are optional
except for positional parameters 10 and higher,
or where the parameter name is followed by other characters
that would prevent it from being expanded.
If parameter expansion occurs within double quotes,
neither pathname expansion nor field splitting happens afterwards.
.Pp
Some special forms of parameter expansion are available.
In the formats below,
.Ar word
itself is subject to expansion,
and, if omitted,
the empty string is used.
If the colon is omitted,
.Ar word
is substituted only if
.Ar parameter
is unset (not if it is empty).
.Bl -tag -width Ds
.It $ Ns Brq Ar parameter Ns :- Ns Op Ar word
Substitute
.Ar parameter .
If
.Ar parameter
is unset or empty,
substitute
.Ar word .
.It $ Ns Brq Ar parameter Ns := Ns Op Ar word
Substitute
.Ar parameter .
If
.Ar parameter
is unset or empty,
first assign the value of
.Ar word
to
.Ar parameter .
.It $ Ns Brq Ar parameter Ns :? Ns Op Ar word
Substitute
.Ar parameter .
If
.Ar parameter
is unset or empty,
the result of the expansion of
.Ar word
is written to standard error
and the shell exits with a non-zero exit status.
If
.Ar word
is omitted,
the string
.Qq parameter null or not set
is used.
.It $ Ns Brq Ar parameter Ns :+ Ns Op Ar word
Substitute
.Ar word .
If
.Ar parameter
is unset or empty,
substitute the empty string.
.It $ Ns Brq # Ns Ar parameter
The length, in characters, of
.Ar parameter .
.It $ Ns Brq Ar parameter Ns % Ns Op Ar word
Substitute
.Ar parameter ,
deleting the smallest possible suffix matching
.Ar word .
.It $ Ns Brq Ar parameter Ns %% Ns Op Ar word
Substitute
.Ar parameter ,
deleting the largest possible suffix matching
.Ar word .
.It $ Ns Brq Ar parameter Ns # Ns Op Ar word
Substitute
.Ar parameter ,
deleting the smallest possible prefix matching
.Ar word .
.It $ Ns Brq Ar parameter Ns ## Ns Op Ar word
Substitute
.Ar parameter ,
deleting the largest possible prefix matching
.Ar word .
.El
.Pp
Command expansion has a command executed in a subshell
and the results output in its place.
The basic format is:
.Pp
.D1 $ Ns Pq Ar command
or
.D1 \` Ns Ar command Ns \`
.Pp
The results are subject to field splitting and pathname expansion;
no other form of expansion happens.
If
.Ar command
is contained within double quotes,
field splitting does not happen either.
Within backquotes,
a backslash is treated literally unless it follows
a dollar sign, backquote, or another backslash.
Commands can be nested,
though the backquoted version requires backslashes before the backquotes.
If
.Ar command
is run in a subshell in the bracketed version,
the syntax is identical to that of arithmetic expansion.
In that case the shell attempts arithmetic expansion first,
then attempts command substitution if that fails.
Or a non-ambiguous version can be used:
.Pp
.D1 "$( (" Ns Ar command Ns ") )"
.Pp
Arithmetic expansion works similarly,
with an arithmetic expression being evaluated and substituted.
The format is:
.Pp
.D1 $ Ns Pq Pq Ar expression
.Pp
Where
.Ar expression
is an integer or parameter name,
optionally combined with any of the operators described below,
listed and grouped according to precedence:
.Bl -tag -width Ds
.It ()\&
Operators within brackets have highest precedence.
Compare 3+2*4, which is 11,
since multiplication has higher precedence than addition,
and (3+2)*4, which is 20.
.It + - ~ !\&
Unary plus
(indicates a positive value; integers are positive by default),
unary minus (indicates a negative value),
bitwise NOT,
and logical NOT
(the result is 1 if the argument is zero, or 0 otherwise), respectively.
.It * / %
Multiplication, division, and modulus (remainder), respectively.
.It + -
Addition and subtraction, respectively.
.It << >>
Shift left or right, respectively.
.It < <= > >=
Less than, less than or equal to,
greater than, and greater than or equal to, respectively.
The result is 1 if true, or 0 otherwise.
.It == !=
Equal (the result is 1 if both arguments are equal, and 0 otherwise)
and not equal (the result is 0 if both arguments are equal, and 1 otherwise),
respectively.
.It &
Bitwise AND.
.It ^
Bitwise exclusive OR.
.It |
Bitwise inclusive OR.
.It &&
Logical AND.
The result is 1 if both arguments are non-zero, or 0 otherwise.
.It ||
Logical OR.
The result is 1 if either argument is non-zero, or 0 otherwise.
.It Ar expression ? Ns Ar expr1 : Ns Ar expr2
The result is
.Ar expr1
if
.Ar expression
is non-zero,
or
.Ar expr2
otherwise.
.It = *= /= %= += -= <<= >>= &= ^= |=
Assignment.
The notation
.Ar var Ns *= Ns Ar expression
is equivalent to
.Ar var Ns = Ns Ar var Ns * Ns Ar expression .
.El
.Pp
After the various types of expansion listed above have been carried out,
the shell subjects everything that did not occur in double quotes to
.Em field splitting ,
where words are broken up according to the value of the
.Ev IFS
variable.
Each character of
.Ev IFS
is used to split fields;
any
.Ev IFS
characters at the beginning and end of input are ignored.
If
.Ev IFS
is unset, the default value consisting of
.Aq space ,
.Aq tab
and
.Aq newline
is used; if the value of
.Ev IFS
is empty, no field splitting is performed.
.Pp
After field splitting,
the shell matches filename patterns.
.Bl -tag -width Ds
.It ?
A question mark matches any single character.
.It *
An asterisk matches multiple characters.
.It [..]
Matches any character enclosed in the brackets.
The sense is negated if the first character is
.Sq !\& .
A closing bracket can be included in the list of characters to match
by listing it as the first character after the opening bracket
or by quoting it.
Similarly a
.Sq -
should be specified last or quoted so that the shell does not think
it is a character range (see below).
.It [[: Ns Ar class Ns :]]
Matches any character in the following character classes:
.Bd -literal -offset indent
alnum	alpha	blank	cntrl
digit	graph	lower	print
punct	space	upper	xdigit
.Ed
.It Bq Ar x Ns - Ns Ar y
Matches any character in the range between
.Ar x
and
.Ar y ,
inclusive.
.El
.Pp
Slashes and full stops do not match the patterns above
because of their use as path and filename characters.
.Ss Redirection
Redirection is used to open, close, or otherwise manipulate files,
using redirection operators in combination with numerical
.Em file descriptors .
A minimum of ten (0\-9) descriptors are supported;
by convention
standard input is file descriptor 0,
standard output file descriptor 1,
and standard error file descriptor 2.
In the examples given below,
.Ar n
represents a numerical file descriptor.
The target for redirection is
.Ar file
and it is subject to all forms of expansion as listed above,
except pathname expansion.
If any part of the file descriptor or redirection operator is quoted,
they are not recognised.
.Bl -tag -width Ds
.It Oo Ar n Oc Ns < Ns Ar file
Open
.Ar file
for reading on file descriptor
.Ar n ,
by default standard input.
.It Oo Ar n Oc Ns > Ns Ar file
Write to
.Ar file
with file descriptor
.Ar n ,
by default standard output.
If
.Ar file
does not exist,
create it;
if it does exist,
truncate it to be empty before beginning to write to it.
.It Oo Ar n Oc Ns >| Ns Ar file
As above, but forces clobbering
(see the
.Fl C
option).
.It Oo Ar n Oc Ns >> Ns Ar file
Append to
.Ar file
with file descriptor
.Ar n ,
by default standard output.
If
.Ar file
does not exist,
create it.
.It Oo Ar n Oc Ns <<
This form of redirection,
called a
.Em here document ,
is used to copy a block of lines
to a temporary file until a line matching
.Ar delimiter
is read.
When the command is executed, standard input is redirected from the
temporary file to file descriptor
.Ar n ,
or standard input by default.
The basic format is:
.Bd -unfilled -offset indent
.Oo Ar n Oc Ns << Ns Ar delimiter
text
text
\&...
.Ar delimiter
.Ed
.Pp
Provided
.Ar delimiter
doesn't contain any quoted characters,
parameter, command, and arithmetic expansions are performed on
the text block,
and backslashes escape the special meaning of
.Sq $ ,
.Sq \` ,
and
.Sq \e .
If multiple here documents are used on the same command line,
they are saved and processed in order.
.It Oo Ar n Oc Ns <<-
Same as
.Ic << ,
except leading tabs are stripped from lines in
.Ar block .
.It Oo Ar n Oc Ns <& Ns Ar file
Make file descriptor
.Ar n ,
by default standard input,
a copy of the file descriptor denoted by
.Ar file .
If
.Ar file
is
.Sq - ,
close file descriptor
.Ar n
or standard input.
.It Oo Ar n Oc Ns >& Ns Ar file
Make file descriptor
.Ar n ,
by default standard output,
a copy of the file descriptor denoted by
.Ar file .
If
.Ar file
is
.Sq - ,
close file descriptor
.Ar n
or standard output.
.It Oo Ar n Oc Ns <> Ns Ar file
Open
.Ar file
for reading and writing on file descriptor
.Ar n ,
by default standard input.
If
.Ar file
does not exist,
create it.
.El
.Sh COMMANDS
The shell first expands
any words that are not variable assignments or redirections,
with the first field being the command name
and any successive fields arguments to that command.
It sets up redirections, if any,
and then expands variable assignments, if any.
It then attempts to run the command.
.Pp
Firstly, it determines whether the command name contains any slashes.
If it does not, and the shell implements the command as a special built-in,
it then invokes the built-in.
If not, but it is a non POSIX standard command,
implemented as a shell function,
it then invokes that.
If not, but it is one of the commands
.Ic alias , bg , cd , command ,
.Ic false , fc , fg , getopts ,
.Ic jobs , kill , newgrp , pwd ,
.Ic read , true , umask , unalias ,
or
.Ic wait ,
it then invokes that.
.Pp
Failing that, the value of
.Ev PATH
is used to search for the command.
If it finds a match,
and it is a POSIX standard command,
implemented as a built-in or function,
it then invokes it.
Otherwise
it attempts to execute the command in an environment separate from the shell.
If it is unable to execute the command,
it tries to run it as a shell script.
.Pp
Finally, if the command name does contain a slash,
and it finds a match in
.Ev PATH ,
it attempts to execute the command in an environment separate from the shell.
If it is unable to execute the command,
it tries to run it as a shell script.
.Pp
A series of one or more commands separated by
.Sq ;\&
constitute a
.Em sequential list ,
where commands are executed in the order given.
The exit status of a sequential list is that of the last command executed.
The format for a sequential list is:
.Pp
.D1 Ar command No \&; Op Ar command ...
.Pp
A series of one or more commands separated by
.Sq &
constitute an
.Em asynchronous list ,
where the shell executes the command in a subshell
and runs the next command without waiting for the previous one to finish.
The exit status of an asynchronous list is always zero.
The format for an asynchronous list is:
.Pp
.D1 Ar command No & Op Ar command ...
.Pp
A series of commands separated by
.Sq |
constitute a
.Em pipeline ,
where the output of one command
is used as input for the next command.
The exit status of a pipeline is that of the last command;
if a pipeline begins
.Sq !\&
the exit status is inverted.
The format for a pipeline is:
.Pp
.D1 Oo !\& Oc Ar command | command Op | Ar ...
.Pp
A series of commands separated by
.Sq &&
constitute an
.Em AND list ,
where a command is only executed if the exit status of the previous command was
zero.
The exit status of an AND list is that of the last command.
The format for an AND list is:
.Pp
.D1 Ar command No && Ar command Op && Ar ...
.Pp
A series of commands separated by
.Sq ||
constitute an
.Em OR list ,
where a command is only executed if the exit status of the previous command was
non-zero.
The exit status of an OR list is that of the last command.
The format for an OR list is:
.Pp
.D1 Ar command No || Ar command Op || Ar ...
.Pp
A series of commands separated by
.Sq &&
and
.Sq ||
constitute an
.Em AND-OR list ,
where
.Sq &&
and
.Sq ||
have equal precedence and are evaluated in the order they are given.
The AND-OR list can be terminated with
.Sq ;\&
or
.Sq &
to have them execute sequentially or asynchronously, respectively.
.Pp
Command lists,
as described above,
can be enclosed within
.Sq ()
to have them executed in a subshell,
or within
.Sq {}
to have them executed in the current environment:
.Pp
.D1 Pq Ar command ...
.D1 Brq \& Ar command ... ; No \&
.Pp
Any redirections specified after the closing bracket apply to all commands
within the brackets.
An operator such as
.Sq ;\&
or a newline are needed to terminate a command list within curly braces.
.Pp
The shell has grammatical constructs
which allow it to work its way (loop) through lists
or evaluate things conditionally.
.Pp
A
.Em for loop
executes a series of commands for each item in a list.
Its format is:
.Bd -unfilled -offset indent
.No for Ar name Op in Op Ar word ...
do
.No "   " Ar command
.No "   " Ar ...
done
.Ed
.Pp
Firstly
.Ar word ...
is expanded to generate a list of items.
The variable
.Ar name
is set to each item, in turn,
and the commands are executed for each item.
The construct
.Qq in word ...
can be omitted,
which is equivalent to: in \&"$@\&".
The exit status is that of the last command executed.
If there are no items,
.Ar command
is not executed and the exit status is zero.
.Pp
A
.Em while loop
continuously executes a set of commands
as long as the command or command list being tested in
.Ar condition
has a zero exit status.
Its format is:
.Bd -unfilled -offset indent
.No while Ar condition
do
.No "   " Ar command
.No "   " Ar ...
done
.Ed
.Pp
Multiple commands may be given by grouping them in lists,
as described above,
or by separating them with newlines.
The exit status is zero if the commands after
.Qq do
were never executed
or otherwise the exit status of the last command executed.
.Pp
An
.Em until loop
continuously executes a set of commands
as long as the command or command list being tested in
.Ar condition
has a non-zero exit status.
Its format is:
.Bd -unfilled -offset indent
.No until Ar condition
do
.No "   " Ar command
.No "   " Ar ...
done
.Ed
.Pp
Multiple commands may be given by grouping them in lists,
as described above,
or by separating them with newlines.
The exit status is zero if the commands after
.Qq do
were never executed
or otherwise the exit status is that of the last command executed.
.Pp
A
.Em case conditional
is used to run commands whenever a pattern is matched.
Its format is:
.Bd -unfilled -offset indent
.No case Ar word No in
.No "   " Po Ar pattern Oo | Ar pattern ... Oc Pc Ar command Ns ;;
.No "   " Ar ...
esac
.Ed
.Pp
In this case
.Ar pattern
is matched against the string resulting from the expansion of
.Ar word .
Multiple commands may be given by grouping them in lists,
as described above,
or by separating them with newlines.
The initial
.Sq (\&
is optional,
as is the terminating
.Sq ;;
for the final command.
The exit status is zero if no patterns are matched
or otherwise the exit status of the last command executed.
.Pp
An
.Em if conditional
is used to execute commands depending on the exit status of the command or
command list being tested.
Its format is:
.Bd -unfilled -offset indent
.No if Ar conditional
then
.No "   " Ar command
.No "   " Ar ...
.No elif Ar conditional
then
.No "   " Ar command
.No "   " Ar ...
.No else
.No "   " Ar command
.No "   " Ar ...
fi
.Ed
.Pp
Firstly the command(s) following
.Qq if
is executed;
if its exit status is zero,
the commands in the
.Qq then
block are executed and the conditional completes.
Otherwise the commands in the
.Qq elif
block are executed;
if the exit status is zero,
the commands in the
.Qq then
block are executed and the conditional completes.
Otherwise the next
.Qq elif
block, if any, is tried.
If nothing from an
.Qq if
or
.Qq elif
block returns zero,
the commands in the
.Qq else
block are run and the conditional completes.
The
.Qq elif
and
.Qq else
blocks are optional.
.Pp
Multiple commands may be given by grouping them in lists,
as described above,
or by separating them with newlines.
The exit status is zero if nothing is executed from an
.Qq if
or
.Qq elif
block
or otherwise the exit status of the last command executed.
.Pp
Functions allow the user to define a group of commands,
executed whenever the function is invoked.
Its format is:
.Bd -unfilled -offset indent
.Ar function Ns () Ar command-list
.Ed
.Pp
The above simply defines a function;
nothing is executed until the function is invoked.
Commands may specify redirections
and positional parameters are changed,
for the duration of the function,
to those passed to it.
The special parameter
.Sq #
is temporarily changed too,
though
.Sq 0
is not.
After the function finishes,
the positional parameters and
.Sq #
are restored to their original values.
The exit status of a function definition is 0 if successful
or >0 otherwise.
The exit status of a function is that of the last command
executed by the function.
.Sh SPECIAL PARAMETERS
Some parameters have special meaning to the shell
and are listed below.
.Bl -tag -width Ds
.It 0
The name of the shell or shell script.
.It 1 ... n
The
.Em positional parameters .
These parameters are set when a shell, shell script,
or shell function is invoked.
Each argument passed to a shell or shell script
is assigned a positional parameter,
starting at 1,
and assigned sequentially.
When a shell function is invoked,
any arguments passed to it are temporarily reassigned to the
positional parameters;
when the function completes,
the values are restored.
Positional parameters 10 and above should be enclosed in {}.
Positional parameters can be reassigned using the
.Ic set
command.
.It @
All positional parameters.
Within double quotes,
each parameter is output as a separate field.
The resulting list completely matches what was passed to the shell.
So "1 2" "3" is output as two parameters, "1 2" and "3".
.It *
All positional parameters.
Within double quotes,
all parameters are output as one field,
separated by the first character of
.Ev IFS
(by default a space).
The resulting list of words is amalgamated,
losing the sense of how they were passed to the shell.
So "1 2" "3" is output as one parameter, "1 2 3".
.It #
The number of positional parameters.
.It ?
The exit status of the most recent command.
.It -
The current shell options.
.It $
The process ID of the current shell.
Subshells have the same PID as the current shell.
.It !
The process ID of the most recent background command.
.El
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm :
.Bl -tag -width "POSIXLY_CORRECT"
.It Ev CDPATH
Colon separated list of directories used by the
.Ic cd
command.
If unset or empty,
the current working directory is used.
.It Ev ENV
Pathname to a file containing commands to be executed
when an interactive shell is started.
.It Ev FCEDIT
Editor for the
.Ic fc
builtin.
The default is
.Xr ed 1 .
.It Ev HISTFILE
Pathname to a file to be used to record command history.
The default is to not write command history to a file.
.It Ev HISTSIZE
The maximum number of commands stored in history.
The default is 500.
.It Ev HOME
Pathname to a user's home directory.
.It Ev IFS
A list of characters to be used for field splitting.
.It Ev LINENO
The current line number in a script or function,
starting at 1.
This variable should not be set by users.
.It Ev MAIL
Pathname to a user's mailbox file.
If set,
.Nm
reports the arrival of new mail
(ascertained by checking a file's modification time)
every
.Ev MAILCHECK
seconds.
.Ev MAIL
is overridden by
.Ev MAILPATH .
.It Ev MAILCHECK
How often,
in seconds,
to check for new mail in either
.Ev MAIL
or
.Ev MAILPATH .
The default is 600 (10 minutes).
If set to 0,
check before issuing each prompt.
.It Ev MAILPATH
Pathname to a colon separated list of mailboxes.
If set,
.Nm
reports the arrival of new mail
(ascertained by checking a file's modification time)
every
.Ev MAILCHECK
seconds.
The default notification message
.Pq Qq you have mail in $_
can be changed per mailbox by appending
.No % Ns Ar message
to a pathname.
.Ev MAILPATH
overrides
.Ev MAIL .
.It Ev OLDPWD
Pathname to the previous working directory.
.It Ev OPTARG
An option argument for the
.Ic getopts
command.
.It Ev OPTIND
An index to the next option for the
.Ic getopts
command.
.It Ev PATH
Pathname to a colon separated list of directories
used to search for the location of executable files.
A pathname of
.Sq .\&
represents the current working directory.
The default value of
.Ev PATH
on
.Ox
is:
.Bd -literal -offset 2n
/usr/bin:/bin:/usr/sbin:/sbin:/usr/X11R6/bin:/usr/local/bin:/usr/local/sbin
.Ed
.It Ev POSIXLY_CORRECT
Enable POSIX mode
(see
.Sx STANDARDS ) .
.It Ev PPID
The shell's parent process ID.
Subshells have the same
.Ev PPID
as the current shell.
.It Ev PS1
User prompt displayed every time an interactive shell
is ready to read a command.
A
.Sq !\&
in the prompt is expanded to the number of the next command in history
to be typed.
.It Ev PS2
Newline prompt displayed in an interactive shell
when a newline has been entered
before the command line completes.
The default value is
.Sq >\ \& .
.It Ev PS4
Trace prompt displayed in an interactive shell
before each command is traced
(see the
.Fl x
option).
The default is
.Sq +\ \& .
.It PWD
The absolute pathname to the current working directory.
.El
.Sh ASYNCHRONOUS EVENTS
The following signals affect the execution of
.Nm :
.Bl -tag -width "SIGQUITXXX"
.It Dv SIGINT
If a shell is interactive
and in command line editing mode,
editing is terminated on the current line
and the command being edited is not entered into command history.
Otherwise the signal is caught
but no action is taken.
.It Dv SIGQUIT
Ignored if a shell is interactive.
.It Dv SIGTERM
Ignored if a shell is interactive.
.It Dv SIGTSTP
Ignored if a shell is interactive
and the
.Ic monitor
option
.Pq Fl m
is set.
.It Dv SIGTTIN
Ignored if a shell is interactive
and the
.Ic monitor
option
.Pq Fl m
is set.
.It Dv SIGTTOU
Ignored if a shell is interactive
and the
.Ic monitor
option
.Pq Fl m
is set.
.El
.Sh EXIT STATUS
The
.Nm
utility exits with one of:
.Bl -tag -width "1-125"
.It 0
The script being executed contained only blank lines or comments.
.It 1\(en125
A non-interactive shell detected an error other than
.Ar file
not found.
.It 126
A command was found but was not executable.
.It 127
A non-interactive shell returned
.Ar file
not found.
.El
.Pp
Otherwise
.Nm
returns the exit status of the last command it invoked.
.Sh SEE ALSO
.Xr csh 1 ,
.Xr ed 1 ,
.Xr ksh 1 ,
.Xr vi 1 ,
.Xr script 7
.Sh STANDARDS
The
.Nm
utility is compliant with the
.St -p1003.1-2008
specification,
except where noted below:
.Bl -dash
.It
The flag
.Op Fl h
is documented by POSIX as hashing
.Qq utilities invoked by functions as those functions are defined ;
this implementation hashes utilities after first invocation
(and functions be damned).
.It
POSIX says mail notifications via
.Ev MAIL
and
.Ev MAILPATH
should happen if a file is created,
as well as if its modification time changes.
This implementation of
.Nm
does not provide notification when these files are created.
.It
The built-in
.Ic newgrp
is unsupported.
.It
The
.Ic break
and
.Ic continue
built-ins should exit/return from the outermost loop if the argument
.Ar n
is greater than the level of loops.
.It
The default value for the
.Ev PS1
user prompt contains the machine's hostname,
followed by
.Sq $\ \&
for normal users and
.Sq #\ \&
for root;
POSIX does not include the hostname.
.El
.Pp
Enabling POSIX mode changes some behaviour to make
.Nm
adhere more strictly to the
.St -p1003.1-2008
specification.