diff options
Diffstat (limited to 'bin/sh/sh.1')
| -rw-r--r-- | bin/sh/sh.1 | 4549 |
1 files changed, 0 insertions, 4549 deletions
diff --git a/bin/sh/sh.1 b/bin/sh/sh.1 deleted file mode 100644 index 4630689..0000000 --- a/bin/sh/sh.1 +++ /dev/null @@ -1,4549 +0,0 @@ -.\" $NetBSD: sh.1,v 1.217 2019/01/21 14:09:24 kre Exp $ -.\" Copyright (c) 1991, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" This code is derived from software contributed to Berkeley by -.\" Kenneth Almquist. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)sh.1 8.6 (Berkeley) 5/4/95 -.\" -.Dd December 12, 2018 -.Dt SH 1 -.\" everything except c o and s (keep them ordered) -.ds flags abCEeFfhIiLmnpquVvXx -.Os -.Sh NAME -.Nm sh -.Nd command interpreter (shell) -.Sh SYNOPSIS -.Nm -.Bk -words -.Op Fl \*[flags] -.Op Cm +\*[flags] -.Ek -.Bk -words -.Op Fl o Ar option_name -.Op Cm +o Ar option_name -.Ek -.Bk -words -.Op Ar command_file Op Ar argument ... -.Ek -.Nm -.Fl c -.Bk -words -.Op Fl s -.Op Fl \*[flags] -.Op Cm +\*[flags] -.Ek -.Bk -words -.Op Fl o Ar option_name -.Op Cm +o Ar option_name -.Ek -.Bk -words -.Ar command_string -.Op Ar command_name Op Ar argument ... -.Ek -.Nm -.Fl s -.Bk -words -.Op Fl \*[flags] -.Op Cm +\*[flags] -.Ek -.Bk -words -.Op Fl o Ar option_name -.Op Cm +o Ar option_name -.Ek -.Bk -words -.Op Ar argument ... -.Ek -.Sh DESCRIPTION -.Nm -is the standard command interpreter for the system. -The current version of -.Nm -is in the process of being changed to conform more closely to the -POSIX 1003.2 and 1003.2a specifications for the shell. -This version has many -features which make it appear similar in some respects to the Korn shell, -but it is not a Korn shell clone (see -.Xr ksh 1 ) . -This man page is not intended -to be a tutorial or a complete specification of the shell. -.Ss Overview -The shell is a command that reads lines from either a file or the -terminal, interprets them, and generally executes other commands. -A shell is the program that is running when a user logs into the system. -(Users can select which shell is executed for them at login with the -.Xr chsh 1 -command). -The shell implements a language that has flow control -constructs, a macro facility that provides a variety of features in -addition to data storage, along with built in history and line editing -capabilities. -It incorporates many features to aid interactive use and -has the advantage that the interpretative language is common to both -interactive and non-interactive use (shell scripts). -That is, commands -can be typed directly to the running shell or can be put into a file and -the file can be executed directly by the shell. -.Ss Invocation -If no arguments are present and if the standard input, -and standard error output, of the shell -are connected to a terminal (or terminals, or if the -.Fl i -flag is set), -and the -.Fl c -option is not present, the shell is considered an interactive shell. -An interactive shell generally prompts before each command and handles -programming and command errors differently (as described below). -When first starting, -the shell inspects argument 0, and if it begins with a dash -.Sq - , -the shell is also considered -a login shell. -This is normally done automatically by the system -when the user first logs in. -A login shell first reads commands -from the files -.Pa /etc/profile -and -.Pa .profile -in the user's home directory -.Pq \&$HOME , -if they exist. -If the environment variable -.Ev ENV -is set on entry to a shell, -or is set in the -.Pa .profile -of a login shell, -and either the shell is interactive, or the -.Cm posix -option is not set, -the shell then performs parameter and arithmetic -expansion on the value of -.Ev ENV , -(these are described later) -and then reads commands from the file name that results. -If -.Ev ENV -contains a command substitution, or one of the -other expansions fails, or if there are no expansions -to expand, the value of -.Ev ENV -is used as the file name. -.Pp -Therefore, a user should place commands that are to be executed only at -login time in the -.Pa .profile -file, and commands that are executed for every shell inside the -.Ev ENV -file. -To set the -.Ev ENV -variable to some file, place the following line in your -.Pa .profile -of your home directory -.Pp -.Dl ENV=$HOME/.shinit; export ENV -.Pp -substituting for -.Dq .shinit -any filename you wish. -Since the -.Ev ENV -file can be read for every invocation of the shell, including shell scripts -and non-interactive shells, the following paradigm is useful for -restricting commands in the -.Ev ENV -file to interactive invocations. -Place commands within the -.Dq Ic case -and -.Dq Ic esac -below (these commands are described later): -.Bd -literal -offset indent -case $- in *i*) - # commands for interactive use only - ... -esac -.Ed -.Pp -If command line arguments besides the options have been specified, and -neither -.Fl c -nor -.Fl s -was given, then the shell treats the first argument -as the name of a file from which to read commands (a shell script). -This also becomes -.Li $0 -and the remaining arguments are set as the -positional parameters of the shell -.Li ( $1 , $2 , -etc). -Otherwise, if -.Fl c -was given, then the first argument, which must exist, -is taken to be a string of -.Nm -commands to execute. -Then if any additional arguments follow the command string, -those arguments become -.Li $0 , $1 , -\&... -Otherwise, if additional arguments were given -(which implies that -.Fl s -was set) -those arguments become -.Li $1 , $2 , -\&... -If -.Li $0 -has not been set by the preceding processing, it -will be set to -.Va argv\^ Ns [ 0 ] -as passed to the shell, which will -usually be the name of the shell itself. -If -.Fl s -was given, or if neither -.Fl c -nor any additional (non-option) arguments were present, -the shell reads commands from its standard input. -.\" -.\" -.Ss Argument List Processing -.\" -Currently, all of the single letter options that can meaningfully -be set using the -.Ic set -built-in, have a corresponding name -that can be used as an argument to the -.Fl o -option. -The -.Ic set Fl o -name is provided next to the single letter option in -the description below. -Some options have only a long name, they are described after -the flag options, they are used with -.Fl o -or -.Cm +o -only, either on the command line, or with the -.Ic set -built-in command. -Other options described are for the command line only. -Specifying a dash -.Dq Cm \- -turns the option on, while using a plus -.Dq Cm + -disables the option. -The following options can be set from the command line and, -unless otherwise stated, with the -.Ic set -built-in (described later). -.\" -.\" strlen("quietprofile") == strlen("local_lineno"): pick the latter -.\" to give the indent as the _ in local_lineno, and the fi ligature in -.\" quietprofile combine to make "local_lineno' slightly wider when printed -.\" (in italics) in a variable width font. -.Bl -tag -width ".Fl L Em local_lineno" -offset indent -.\" -.It Fl a Em allexport -Automatically export any variable to which a value is assigned -while this flag is set, unless the variable has been marked as -not for export. -.It Fl b Em notify -Enable asynchronous notification of background job completion. -(Not implemented.) -.It Fl C Em noclobber -Don't overwrite existing files with -.Dq > . -.It Fl c -Read commands from the -.Ar command_string -operand instead of, or in addition to, from the standard input. -Special parameter -.Dv 0 \" $0 (comments like this for searching sources only) -will be set from the -.Ar command_name -operand if given, and the positional parameters -.Dv ( 1 , 2 , -etc.) -set from the remaining argument operands, if any. -.Fl c -is only available at invocation, it cannot be -.Ic set , -and there is no form using -.Dq Cm \&+ . -.It Fl E Em emacs -Enable the built-in emacs style -command line editor (disables -.Fl V -if it has been set). -(See the -.Sx Command Line Editing -section below.) -.It Fl e Em errexit -If not interactive, exit immediately if any untested command fails. -If interactive, and an untested command fails, -cease all processing of the current command and return to -prompt for a new command. -The exit status of a command is considered to be -explicitly tested if the command is used to control an -.Ic if , -.Ic elif , -.Ic while , -or -.Ic until , -or if the command is the left hand operand of an -.Dq && -or -.Dq || -operator, -or if it is a pipeline (or simple command) preceded by the -.Dq \&! -operator. -With pipelines, only the status of the entire pipeline -(indicated by the last command it contains) -is tested when -.Fl e -is set to determine if the shell should exit. -.It Fl F Em fork -Cause the shell to always use -.Xr fork 2 -instead of attempting -.Xr vfork 2 -when it needs to create a new process. -This should normally have no visible effect, -but can slow execution. -The -.Nm -can be compiled to always use -.Xr fork 2 -in which case altering the -.Fl F -flag has no effect. -.It Fl f Em noglob -Disable pathname expansion. -.It Fl h Em trackall -Functions defined while this option is set will have paths bound to -commands to be executed by the function at the time of the definition. -When off when a function is defined, -the file system is searched for commands each time the function is invoked. -(Not implemented.) -.It Fl I Em ignoreeof -Ignore EOFs from input when interactive. -(After a large number of consecutive EOFs the shell will exit anyway.) -.It Fl i Em interactive -Force the shell to behave interactively. -.It Fl L Em local_lineno -When set, before a function is defined, -causes the variable -.Dv LINENO -when used within the function, -to refer to the line number defined such that -first line of the function is line 1. -When reset, -.Dv LINENO -in a function refers to the line number within the file -within which the definition of the function occurs. -This option defaults to -.Dq on -in this shell. -For more details see the section -.Sx LINENO -below. -.It Fl m Em monitor -Turn on job control (set automatically when interactive). -.It Fl n Em noexec -Read and parse commands, but do not execute them. -This is useful for checking the syntax of shell scripts. -If -.Fl n -becomes set in an interactive shell, it will automatically be -cleared just before the next time the command line prompt -.Pq Ev PS1 -is written. -.It Fl p Em nopriv -Do not attempt to reset effective UID if it does not match UID. -This is not set by default to help avoid incorrect usage by setuid -root programs via -.Xr system 3 -or -.Xr popen 3 . -.It Fl q Em quietprofile -If the -.Fl v -or -.Fl x -options have been set, do not apply them when reading -initialization files, these being -.Pa /etc/profile , -.Pa .profile , -and the file specified by the -.Ev ENV -environment variable. -.It Fl s Em stdin -Read commands from standard input (set automatically if -neither -.Fl c -nor file arguments are present). -If after processing a command_string with the -.Fl c -option, the shell has not exited, and the -.Fl s -option is set, it will continue reading more commands from standard input. -This option has no effect when set or reset after the shell has -already started reading from the command_file, or from standard input. -Note that the -.Fl s -flag being set does not cause the shell to be interactive. -.It Fl u Em nounset -Write a message to standard error when attempting to obtain a -value from a variable that is not set, -and if the shell is not interactive, exit immediately. -For interactive shells, instead return immediately to the command prompt -and read the next command. -Note that expansions (described later, see -.Sx Word Expansions -below) using the -.Sq \&+ , -.Sq \&\- , -.Sq \&= , -or -.Sq \&? -operators test if the variable is set, before attempting to -obtain its value, and hence are unaffected by -.Fl u . -.It Fl V Em vi -Enable the built-in -.Xr vi 1 -command line editor (disables -.Fl E -if it has been set). -(See the -.Sx Command Line Editing -section below.) -.It Fl v Em verbose -The shell writes its input to standard error as it is read. -Useful for debugging. -.It Fl X Em xlock -Cause output from the -.Ic xtrace -.Pq Fl x -option to be sent to standard error as it exists when the -.Fl X -option is enabled (regardless of its previous state.) -For example: -.Bd -literal -compact - set -X 2>/tmp/trace-file -.Ed -will arrange for tracing output to be sent to the file named, -instead of wherever it was previously being sent, -until the X option is set again, or cleared. -.Pp -Each change (set or clear) to -.Fl X -is also performed upon -.Fl x , -but not the converse. -.It Fl x Em xtrace -Write each command to standard error (preceded by the expanded value of -.Li $PS4 ) -before it is executed. -Unless -.Fl X -is set, -.Dq "standard error" -means that which existed immediately before any redirections to -be applied to the command are performed. -Useful for debugging. -.It "\ \ " Em cdprint -Make an interactive shell always print the new directory name when -changed by the -.Ic cd -command. -In a non-interactive shell this option has no effect. -.It "\ \ " Em nolog -Prevent the entry of function definitions into the command history (see -.Ic fc -in the -.Sx Built-ins -section.) -(Not implemented.) -.It "\ \ " Em pipefail -If set when a pipeline is created, -the way the exit status of the pipeline is determined -is altered. -See -.Sx Pipelines -below for the details. -.It "\ \ " Em posix -Enables closer adherence to the POSIX shell standard. -This option will default set at shell startup if the -environment variable -.Ev POSIXLY_CORRECT -is present. -That can be overridden (set or reset) by the -.Fl o -option on the command line. -Currently this option controls whether (!posix) or not (posix) -the file given by the -.Ev ENV -variable is read at startup by a non-interactive shell. -It also controls whether file descriptors greater than 2 -opened using the -.Ic exec -built-in command are passed on to utilities executed -.Dq ( yes -in posix mode), -whether a colon (:) terminates the user name in tilde (~) expansions -other than in assignment statements -.Dq ( no -in posix mode), -the format of the output of the -.Ic kill Fl l -command, where posix mode causes the names of the signals -be separated by either a single space or newline, and where otherwise -sufficient spaces are inserted to generate nice looking columns, -and whether the shell treats -an empty brace-list compound statement as a syntax error -(expected by POSIX) or permits it. -Such statements -.Dq "{\ }" -can be useful when defining dummy functions. -Lastly, in posix mode, only one -.Dq \&! -is permitted before a pipeline. -.It "\ \ " Em promptcmds -Allows command substitutions (as well as parameter -and arithmetic expansions, which are always performed) -upon the prompt strings -.Ev PS1 , -.Ev PS2 , -and -.Ev PS4 -each time, before they are output. -This option should not be set until after the prompts -have been set (or verified) to avoid accidentally importing -unwanted command substitutions from the environment. -.It "\ \ " Em tabcomplete -Enables filename completion in the command line editor. -Typing a tab character will extend the current input word to match a -filename. -If more than one filename matches it is only extended to be the common prefix. -Typing a second tab character will list all the matching names. -One of the editing modes, either -.Fl E -or -.Fl V , -must be enabled for this to work. -.El -.Ss Lexical Structure -The shell reads input in terms of lines from a file and breaks it up into -words at whitespace (blanks and tabs), and at certain sequences of -characters that are special to the shell called -.Dq operators . -There are two types of operators: control operators and redirection -operators (their meaning is discussed later). -The following is a list of operators: -.Bl -ohang -offset indent -.It "Control operators:" -.Dl & && \&( \&) \&; ;; ;& \&| || <newline> -.It "Redirection operators:" -.Dl < > >| << >> <& >& <<- <> -.El -.Ss Quoting -Quoting is used to remove the special meaning of certain characters or -words to the shell, such as operators, whitespace, or keywords. -There are four types of quoting: -matched single quotes, -matched double quotes, -backslash, -and -dollar preceding matched single quotes (enhanced C style strings.) -.Ss Backslash -An unquoted backslash preserves the literal meaning of the following -character, with the exception of -.Aq newline . -An unquoted backslash preceding a -.Aq newline -is treated as a line continuation, the two characters are simply removed. -.Ss Single Quotes -Enclosing characters in single quotes preserves the literal meaning of all -the characters (except single quotes, making it impossible to put -single quotes in a single-quoted string). -.Ss Double Quotes -Enclosing characters within double quotes preserves the literal -meaning of all characters except dollar sign -.Pq Li \&$ , -backquote -.Pq Li \&` , -and backslash -.Pq Li \e . -The backslash inside double quotes is historically weird, and serves to -quote only the following characters (and these not in all contexts): -.Dl $ ` \*q \e <newline> , -where a backslash newline is a line continuation as above. -Otherwise it remains literal. -.\" -.\" -.Ss Dollar Single Quotes ( Li \&$'...' ) -.\" -.Bd -filled -offset indent -.Bf Em -Note: this form of quoting is still somewhat experimental, -and yet to be included in the POSIX standard. -This implementation is based upon the current proposals for -standardization, and is subject to change should the eventual -adopted text differ. -.Ef -.Ed -.Pp -Enclosing characters in a matched pair of single quotes, with the -first immediately preceded by an unquoted dollar sign -.Pq Li \&$ -provides a quoting mechanism similar to single quotes, except -that within the sequence of characters, any backslash -.Pq Li \e , -is an escape character, which causes the following character to -be treated specially. -Only a subset of the characters that can occur in the string -are defined after a backslash, others are reserved for future -definition, and currently generate a syntax error if used. -The escape sequences are modeled after the similar sequences -in strings in the C programming language, with some extensions. -.Pp -The following characters are treated literally when following -the escape character (backslash): -.Dl \e \&' \(dq -The sequence -.Dq Li \e\e -allows the escape character (backslash) to appear in the string literally. -.Dq Li \e' -allows a single quote character into the string, such an -escaped single quote does not terminate the quoted string. -.Dq Li \e\(dq -is for compatibility with C strings, the double quote has -no special meaning in a shell C-style string, -and does not need to be escaped, but may be. -.Pp -A newline following the escape character is treated as a line continuation, -like the same sequence in a double quoted string, -or when not quoted \(en -the two characters, the backslash escape and the newline, -are removed from the input string. -.Pp -The following characters, when escaped, are converted in a -manner similar to the way they would be in a string in the C language: -.Dl a b e f n r t v -An escaped -.Sq a -generates an alert (or -.Sq BEL ) -character, that is, control-G, or 0x07. -In a similar way, -.Sq b -is backspace (0x08), -.Sq e -(an extension to C) is escape (0x1B), -.Sq f -is form feed (0x0C), -.Sq n -is newline (or line feed, 0x0A), -.Sq r -is return (0x0D), -.Sq t -is horizontal tab (0x09), -and -.Sq v -is vertical tab (0x13). -.Pp -In addition to those there are 5 forms that need additional -data, which is obtained from the subsequent characters. -An escape -.Pq Li \e -followed by one, two or three, octal digits -.Po So 0 Sc Ns \&.. Ns So 7 Sc Ns Pc -is processed to form an 8 bit character value. -If only one or two digits are present, the following -character must be something other than an octal digit. -It is safest to always use all 3 digits, with leading -zeros if needed. -If all three digits are present, the first must be one of -.So 0 Sc Ns \&.. Ns So 3 Sc . -.Pp -An escape followed by -.Sq x -(lower case only) can be followed by one or two -hexadecimal digits -.Po So 0 Sc Ns \&.. Ns So 9 Sc , So A Sc Ns \&.. Ns So F Sc , or So a Sc Ns \&.. Ns So f Sc . Pc -As with octal, if only one hex digit is present, the following -character must be something other than a hex digit, -so always giving 2 hex digits is best. -However, unlike octal, it is unspecified in the standard -how many hex digits can be consumed. -This -.Nm -takes at most two, but other shells will continue consuming -characters as long as they remain valid hex digits. -Consequently, users should ensure that the character -following the hex escape sequence is something other than -a hex digit. -One way to achieve this is to end the -.Li $'...' -string immediately -after the final hex digit, and then, immediately start -another, so -.Dl \&$'\ex33'$'4...' -always gives the character with value 0x33 -.Pq Sq 3 , -followed by the character -.Sq 4 , -whereas -.Dl \&$'\ex334' -in some other shells would be the hex value 0x334 (10, or more, bits). -.Pp -There are two escape sequences beginning with -.Sq Li \eu -or -.Sq Li \eU . -The former is followed by from 1 to 4 hex digits, the latter by -from 1 to 8 hex digits. -Leading zeros can be used to pad the sequences to the maximum -permitted length, to avoid any possible ambiguity problem with -the following character, and because there are some shells that -insist on exactly 4 (or 8) hex digits. -These sequences are evaluated to form the value of a Unicode code -point, which is then encoded into UTF-8 form, and entered into the -string. -(The code point should be converted to the appropriate -code point value for the corresponding character in the character -set given by the current locale, or perhaps the locale in use -when the shell was started, but is not... currently.) -Not all values that are possible to write are valid, values that -specify (known) invalid Unicode code points will be rejected, or -simply produce -.Sq \&? . -.Pp -Lastly, as another addition to what is available in C, the escape -character (backslash), followed by -.Sq c -(lower case only) followed by one additional character, which must -be an alphabetic character (a letter), or one of the following: -.Dl \&@ \&[ \&\e \&] \&^ \&_ \&? -Other than -.Sq Li \ec? -the value obtained is the least significant 5 bits of the -ASCII value of the character following the -.Sq Li \ec -escape sequence. -That is what is commonly known as the -.Dq control -character obtained from the given character. -The escape sequence -.Sq Li \ec? -yields the ASCII DEL character (0x7F). -Note that to obtain the ASCII FS character (0x1C) this way, -.Pq "that is control-\e" -the trailing -.Sq Li \e -must be escaped itself, and so for this one case, the full -escape sequence is -.Dq Li \ec\e\e . -The sequence -.Dq Li \ec\e Ns Ar X\^ -where -.Sq Ar X\^ -is some character other than -.Sq Li \e -is reserved for future use, its meaning is unspecified. -In this -.Nm -an error is generated. -.Pp -If any of the preceding escape sequences generate the value -.Sq \e0 -(a NUL character) that character, and all that follow in the same -.Li $'...' -string, are omitted from the resulting word. -.Pp -After the -.Li $'...' -string has had any included escape sequences -converted, it is treated as if it had been a single quoted string. -.\" -.\" -.Ss Reserved Words -.\" -Reserved words are words that have special meaning to the -shell and are recognized at the beginning of a line and -after a control operator. -The following are reserved words: -.Bl -column while while while while -offset indent -.It Ic \&! Ta Ic \&{ Ta Ic \&} Ta Ic case -.It Ic do Ta Ic done Ta Ic elif Ta Ic else -.It Ic esac Ta Ic fi Ta Ic for Ta Ic if -.It Ic in Ta Ic then Ta Ic until Ta Ic while -.El -.Pp -Their meanings are discussed later. -.\" -.\" -.Ss Aliases -.\" -An alias is a name and corresponding value set using the -.Ic alias -built-in command. -Whenever a reserved word (see above) may occur, -and after checking for reserved words, the shell -checks the word to see if it matches an alias. -If it does, it replaces it in the input stream with its value. -For example, if there is an alias called -.Dq lf -with the value -.Dq "ls -F" , -then the input: -.Pp -.Dl lf foobar Aq return -.Pp -would become -.Pp -.Dl ls -F foobar Aq return -.Pp -Aliases provide a convenient way for naive users to create shorthands for -commands without having to learn how to create functions with arguments. -They can also be used to create lexically obscure code. -This use is strongly discouraged. -.\" -.Ss Commands -.\" -The shell interprets the words it reads according to a language, the -specification of which is outside the scope of this man page (refer to the -BNF in the POSIX 1003.2 document). -Essentially though, a line is read and if the first -word of the line (or after a control operator) is not a reserved word, -then the shell has recognized a simple command. -Otherwise, a complex -command or some other special construct may have been recognized. -.\" -.\" -.Ss Simple Commands -.\" -If a simple command has been recognized, the shell performs -the following actions: -.Bl -enum -offset indent -.It -Leading words of the form -.Dq Ar name Ns Li = Ns Ar value -are stripped off, the value is expanded, as described below, -and the results are assigned to the environment of the simple command. -Redirection operators and their arguments (as described below) are -stripped off and saved for processing in step 3 below. -.It -The remaining words are expanded as described in the -.Sx Word Expansions -section below. -The first remaining word is considered the command name and the -command is located. -Any remaining words are considered the arguments of the command. -If no command name resulted, then the -.Dq Ar name Ns Li = Ns Ar value -variable assignments recognized in item 1 affect the current shell. -.It -Redirections are performed, from first to last, in the order given, -as described in the next section. -.El -.\" -.\" -.Ss Redirections -.\" -Redirections are used to change where a command reads its input or sends -its output. -In general, redirections open, close, or duplicate an -existing reference to a file. -The overall format used for redirection is: -.Pp -.Dl Oo Ar n Oc Ns Va redir-op Ar file -.Pp -where -.Va redir-op -is one of the redirection operators mentioned previously. -The following is a list of the possible redirections. -The -.Op Ar n -is an optional number, as in -.Sq Li 3 -(not -.Li [3] ) , -that refers to a file descriptor. -If present it must occur immediately before the redirection -operator, with no intervening white space, and becomes a -part of that operator. -.Bl -tag -width aaabsfiles -offset indent -.It Oo Ar n Oc Ns Ic > Ar file -Redirect standard output (or -.Ar n ) -to -.Ar file . -.It Oo Ar n Oc Ns Ic >| Ar file -The same, but override the -.Fl C -option. -.It Oo Ar n Oc Ns Ic >> Ar file -Append standard output (or -.Ar n ) -to -.Ar file . -.It Oo Ar n Oc Ns Ic < Ar file -Redirect standard input (or -.Ar n ) -from -.Ar file . -.It Oo Ar n1 Oc Ns Ic <& Ns Ar n2 -Duplicate standard input (or -.Ar n1 ) -from file descriptor -.Ar n2 . -.Ar n2 -is expanded if not a digit string, the result must be a number. -.It Oo Ar n Oc Ns Ic <&- -Close standard input (or -.Ar n ) . -.It Oo Ar n1 Oc Ns Ic >& Ns Ar n2 -Duplicate standard output (or -.Ar n1 ) -to -.Ar n2 . -.It Oo Ar n Oc Ns Ic >&- -Close standard output (or -.Ar n ) . -.It Oo Ar n Oc Ns Ic <> Ar file -Open -.Ar file -for reading and writing on standard input (or -.Ar n ) . -.El -.Pp -The following redirection is often called a -.Dq here-document . -.Bd -unfilled -offset indent -.Oo Ar n Oc Ns Ic << Ar delimiter -.Li \&... here-doc-text ... -.Ar delimiter -.Ed -.Pp -The -.Dq here-doc-text -starts immediately after the next unquoted newline character following -the here-document redirection operator. -If there is more than one here-document redirection on the same -line, then the text for the first (from left to right) is read -first, and subsequent here-doc-text for later here-document redirections -follows immediately after, until all such redirections have been -processed. -.Pp -All the text on successive lines up to the delimiter, -which must appear on a line by itself, with nothing other -than an immediately following newline, is -saved away and made available to the command on standard input, or file -descriptor n if it is specified. -If the delimiter as specified on the initial line is -quoted, then the here-doc-text is treated literally; otherwise, the text is -treated much like a double quoted string, except that -.Sq Li \(dq -characters have no special meaning, and are not escaped by -.Sq Li \&\e , -and is subjected to parameter expansion, command substitution, and arithmetic -expansion as described in the -.Sx Word Expansions -section below. -If the operator is -.Ic <<- -instead of -.Ic << , -then leading tabs in all lines in the here-doc-text, including before the -end delimiter, are stripped. -If the delimiter is not quoted, lines in here-doc-text that end with -an unquoted -.Li \e -are joined to the following line, the -.Li \e -and following -newline are simply removed while reading the here-document, -which thus guarantees -that neither of those lines can be the end delimiter. -.Pp -It is a syntax error for the end of the input file (or string) to be -reached before the delimiter is encountered. -.\" -.\" -.Ss Search and Execution -.\" -There are three types of commands: shell functions, built-in commands, and -normal programs \(em and the command is searched for (by name) in that order. -A command that contains a slash -.Sq \&/ -in its name is always a normal program. -They each are executed in a different way. -.Pp -When a shell function is executed, all of the shell positional parameters -(note: excluding -.Li 0 , \" $0 -which is a special, not positional, parameter, and remains unchanged) -are set to the arguments of the shell function. -The variables which are explicitly placed in the environment of -the command (by placing assignments to them before the function name) are -made local to the function and are set to the values given, -and exported for the benefit of programs executed with the function. -Then the command given in the function definition is executed. -The positional parameters, and local variables, are restored to -their original values when the command completes. -This all occurs within the current shell, and the function -can alter variables, or other settings, of the shell, but -not the positional parameters nor their related special parameters. -.Pp -Shell built-ins are executed internally to the shell, without spawning a -new process. -.Pp -Otherwise, if the command name doesn't match a function or built-in, the -command is searched for as a normal program in the file system (as -described in the next section). -When a normal program is executed, the shell runs the program, -passing the arguments and the environment to the program. -If the program is not a normal executable file, and if it does -not begin with the -.Dq magic number -whose ASCII representation is -.Dq Li "#!" , -so -.Xr execve 2 -returns -.Er ENOEXEC -then) the shell will interpret the program in a sub-shell. -The child shell will reinitialize itself in this case, -so that the effect will be as if a -new shell had been invoked to handle the ad-hoc shell script, except that -the location of hashed commands located in the parent shell will be -remembered by the child. -.Pp -Note that previous versions of this document and the source code itself -misleadingly and sporadically refer to a shell script without a magic -number as a -.Dq shell procedure . -.\" -.\" -.Ss Path Search -.\" -When locating a command, the shell first looks to see if it has a shell -function by that name. -Then it looks for a built-in command by that name. -If a built-in command is not found, one of two things happen: -.Bl -enum -.It -Command names containing a slash are simply executed without performing -any searches. -.It -Otherwise, the shell searches each entry in -.Ev PATH -in turn for the command. -The value of the -.Ev PATH -variable should be a series of entries separated by colons. -Each entry consists of a directory name. -The current directory may be indicated -implicitly by an empty directory name, or explicitly by a single period. -If a directory searched contains an executable file with the same -name as the command given, -the search terminates, and that program is executed. -.El -.Ss Command Exit Status -Each command has an exit status that can influence the behavior -of other shell commands. -The paradigm is that a command exits -with zero in normal cases, or to indicate success, -and non-zero for failure, -error, or a false indication. -The man page for each command -should indicate the various exit codes and what they mean. -Additionally, the built-in commands return exit codes, as does -an executed shell function. -.Pp -If a command consists entirely of variable assignments then the -exit status of the command is that of the last command substitution -if any, otherwise 0. -.Pp -If redirections are present, and any fail to be correctly performed, -any command present is not executed, and an exit status of 2 -is returned. -.Ss Complex Commands -Complex commands are combinations of simple commands with control -operators or reserved words, together creating a larger complex command. -Overall, a shell program is a: -.Bl -tag -width XpipelineX -.It list -Which is a sequence of one or more AND-OR lists. -.It "AND-OR list" -is a sequence of one or more pipelines. -.It pipeline -is a sequence of one or more commands. -.It command -is one of a simple command, a compound command, or a function definition. -.It "simple command" -has been explained above, and is the basic building block. -.It "compound command" -provides mechanisms to group lists to achieve different effects. -.It "function definition" -allows new simple commands to be created as groupings of existing commands. -.El -.Pp -Unless otherwise stated, the exit status of a list -is that of the last simple command executed by the list. -.\" -.\" -.Ss Pipelines -.\" -A pipeline is a sequence of one or more commands separated -by the control operator -.Sq Ic \(ba , -and optionally preceded by the -.Dq Ic \&! -reserved word. -Note that -.Sq Ic \(ba -is an operator, and so is recognized anywhere it appears unquoted, -it does not require surrounding white space or other syntax elements. -On the other hand -.Dq Ic \&! -being a reserved word, must be separated from adjacent words by -white space (or other operators, perhaps redirects) and is only -recognized as the reserved word when it appears in a command word -position (such as at the beginning of a pipeline.) -.Pp -The standard output of all but -the last command in the sequence is connected to the standard input -of the next command. -The standard output of the last -command is inherited from the shell, as usual, -as is the standard input of the first command. -.Pp -The format for a pipeline is: -.Pp -.Dl [!] command1 Op Li \&| command2 No ... -.Pp -The standard output of command1 is connected to the standard input of -command2. -The standard input, standard output, or both of each command is -considered to be assigned by the pipeline before any redirection specified -by redirection operators that are part of the command are performed. -.Pp -If the pipeline is not in the background (discussed later), the shell -waits for all commands to complete. -.Pp -The commands in a pipeline can either be simple commands, -or one of the compound commands described below. -The simplest case of a pipeline is a single simple command. -.Pp -If the -.Ic pipefail -option was set when a pipeline was started, -the pipeline status is the status of -the last (lexically last, i.e.: rightmost) command in the -pipeline to exit with non-zero exit status, or zero, if, -and only if, all commands in the pipeline exited with a status of zero. -If the -.Ic pipefail -option was not set, which is the default state, -the pipeline status is the exit -status of the last (rightmost) command in the pipeline, -and the exit status of any other commands in the pipeline is ignored. -.Pp -If the reserved word -.Dq Ic \&! -precedes the pipeline, the exit status -becomes the logical NOT of the pipeline status as determined above. -That is, if the pipeline status is zero, the exit status is 1; -if the pipeline status is other than zero, the exit status is zero. -If there is no -.Dq Ic \&! -reserved word, the pipeline status becomes the exit status. -.Pp -Because pipeline assignment of standard input or standard output or both -takes place before redirection, it can be modified by redirection. -For example: -.Pp -.Dl $ command1 2>&1 \&| command2 -.Pp -sends both the standard output and standard error of command1 -to the standard input of command2. -.Pp -Note that unlike some other shells, each process in the pipeline is a -child of the invoking shell (unless it is a shell built-in, in which case -it executes in the current shell \(em but any effect it has on the -environment is wiped). -.Pp -A pipeline is a simple case of an AND-OR-list (described below.) -A -.Li \&; -or -.Aq newline -terminator causes the preceding pipeline, or more generally, -the preceding AND-OR-list to be executed sequentially; -that is, the shell executes the commands, and waits for them -to finish before proceeding to following commands. -An -.Li \&& -terminator causes asynchronous (background) execution -of the preceding AND-OR-list (see the next paragraph below). -The exit status of an asynchronous AND-OR-list is zero. -The actual status of the commands, -after they have completed, -can be obtained using the -.Ic wait -built-in command described later. -.\" -.\" -.Ss Background Commands \(em Ic \&& -.\" -If a command, pipeline, or AND-OR-list -is terminated by the control operator ampersand -.Pq Li \&& , -the -shell executes the command asynchronously \(em that is, the shell does not -wait for the command to finish before executing the next command. -.Pp -The format for running a command in background is: -.Pp -.Dl command1 & Op Li command2 & No ... -.Pp -If the shell is not interactive, the standard input of an asynchronous -command is set to -.Pa /dev/null . -The process identifier of the most recent command started in the -background can be obtained from the value of the special parameter -.Dq Dv \&! \" $! -(see -.Sx Special Parameters ) -provided it is accessed before the next asynchronous command is started. -.\" -.\" -.Ss Lists \(em Generally Speaking -.\" -A list is a sequence of one or more commands separated by newlines, -semicolons, or ampersands, and optionally terminated by one of these three -characters. -A shell program, which includes the commands given to an -interactive shell, is a list. -Each command in such a list is executed when it is fully parsed. -Another use of a list is as a complete-command, -which is parsed in its entirety, and then later the commands in -the list are executed only if there were no parsing errors. -.Pp -The commands in a list are executed in the order they are written. -If command is followed by an ampersand, the shell starts the -command and immediately proceeds to the next command; otherwise it waits -for the command to terminate before proceeding to the next one. -A newline is equivalent to a -.Sq Li \&; -when no other operator is present, and the command being input -could syntactically correctly be terminated at the point where -the newline is encountered, otherwise it is just whitespace. -.\" -.\" -.Ss AND-OR Lists (Short-Circuit List Operators) -.\" -.Dq Li \&&& -and -.Dq Li \&|| -are AND-OR list operators. -After executing the commands that precede the -.Dq Li \&&& -the subsequent command is executed -if and only if the exit status of the preceding command(s) is zero. -.Dq Li \&|| -is similar, but executes the subsequent command if and only if the exit status -of the preceding command is nonzero. -If a command is not executed, the exit status remains unchanged -and the following AND-OR list operator (if any) uses that status. -.Dq Li \&&& -and -.Dq Li \&|| -both have the same priority. -Note that these operators are left-associative, so -.Dl true || echo bar && echo baz -writes -.Dq baz -and nothing else. -This is not the way it works in C. -.\" -.\" -.Ss Flow-Control Constructs \(em Ic if , while , until , for , case -.\" -These commands are instances of compound commands. -The syntax of the -.Ic if -command is -.Bd -literal -offset indent -.Ic if Ar list -.Ic then Ar list -.Ic [ elif Ar list -.Ic then Ar list ] No ... -.Ic [ else Ar list ] -.Ic fi -.Ed -.Pp -The first list is executed, and if the exit status of that list is zero, -the list following the -.Ic then -is executed. -Otherwise the list after an -.Ic elif -(if any) is executed and the process repeats. -When no more -.Ic elif -reserved words, and accompanying lists, appear, -the list after the -.Ic else -reserved word, if any, is executed. -.Pp -The syntax of the -.Ic while -command is -.Bd -literal -offset indent -.Ic while Ar list -.Ic do Ar list -.Ic done -.Ed -.Pp -The two lists are executed repeatedly while the exit status of the -first list is zero. -The -.Ic until -command is similar, but has the word -.Ic until -in place of -.Ic while , -which causes it to repeat until the exit status of the first list is zero. -.Pp -The syntax of the -.Ic for -command is -.Bd -literal -offset indent -.Ic for Ar variable Op Ic in Ar word No ... -.Ic do Ar list -.Ic done -.Ed -.Pp -The words are expanded, or -.Li \*q$@\*q -if -.Ic in -(and the following words) is not present, -and then the list is executed repeatedly with the -variable set to each word in turn. -If -.Ic in -appears after the variable, but no words are -present, the list is not executed, and the exit status is zero. -.Ic do -and -.Ic done -may be replaced with -.Sq Ic \&{ -and -.Sq Ic \&} , -but doing so is non-standard and not recommended. -.Pp -The syntax of the -.Ic break -and -.Ic continue -commands is -.Bd -literal -offset indent -.Ic break Op Ar num -.Ic continue Op Ar num -.Ed -.Pp -.Ic break -terminates the -.Ar num -innermost -.Ic for , while , -or -.Ic until -loops. -.Ic continue -breaks execution of the -.Ar num\^ Ns -1 -innermost -.Ic for , while , -or -.Ic until -loops, and then continues with the next iteration of the enclosing loop. -These are implemented as special built-in commands. -The parameter -.Ar num , -if given, must be an unsigned positive integer (greater than zero). -If not given, 1 is used. -.Pp -The syntax of the -.Ic case -command is -.Bd -literal -offset indent -.Ic case Ar word Ic in -.Oo Ic \&( Oc Ar pattern Ns Ic \&) Oo Ar list Oc Ic \&;& -.Oo Ic \&( Oc Ar pattern Ns Ic \&) Oo Ar list Oc Ic \&;; -.No \&... -.Ic esac -.Ed -.Pp -The pattern can actually be one or more patterns (see -.Sx Shell Patterns -described later), separated by -.Dq \(or -characters. -.Pp -.Ar word -is expanded and matched against each -.Ar pattern -in turn, -from first to last, -with each pattern being expanded just before the match is attempted. -When a match is found, pattern comparisons cease, and the associated -.Ar list , -if given, -is evaluated. -If the list is terminated with -.Dq Ic \&;& -execution then falls through to the following list, if any, -without evaluating its pattern, or attempting a match. -When a list terminated with -.Dq Ic \&;; -has been executed, or when -.Ic esac -is reached, execution of the -.Ic case -statement is complete. -The exit status is that of the last command executed -from the last list evaluated, if any, or zero otherwise. -.\" -.\" -.Ss Grouping Commands Together -.\" -Commands may be grouped by writing either -.Dl Ic \&( Ns Ar list Ns Ic \&) -or -.Dl Ic \&{ Ar list Ns Ic \&; \&} -These also form compound commands. -.Pp -Note that while parentheses are operators, and do not require -any extra syntax, braces are reserved words, so the opening brace -must be followed by white space (or some other operator), and the -closing brace must occur in a position where a new command word might -otherwise appear. -.Pp -The first of these executes the commands in a sub-shell. -Built-in commands grouped into a -.Li \&( Ns Ar list Ns \&) -will not affect the current shell. -The second form does not fork another shell so is slightly more efficient, -and allows for commands which do affect the current shell. -Grouping commands together this way allows you to redirect -their output as though they were one program: -.Bd -literal -offset indent -{ echo -n \*qhello \*q ; echo \*qworld\*q ; } > greeting -.Ed -.Pp -Note that -.Dq Ic } -must follow a control operator (here, -.Dq Ic \&; ) -so that it is recognized as a reserved word and not as another command argument. -.\" -.\" -.Ss Functions -.\" -The syntax of a function definition is -.Pp -.Dl Ar name Ns Ic \&() Ar command Op Ar redirect No ... -.Pp -A function definition is an executable statement; when executed it -installs a function named name and returns an exit status of zero. -The command is normally a list enclosed between -.Dq { -and -.Dq } . -The standard syntax also allows the command to be any of the other -compound commands, including a sub-shell, all of which are supported. -As an extension, this shell also allows a simple command -(or even another function definition) to be -used, though users should be aware this is non-standard syntax. -This means that -.Dl l() ls \*q$@\*q -works to make -.Dq l -an alternative name for the -.Ic ls -command. -.Pp -If the optional redirect, (see -.Sx Redirections ) , -which may be of any of the normal forms, -is given, it is applied each time the -function is called. -This means that a simple -.Dq Hello World -function might be written (in the extended syntax) as: -.Bd -literal -offset indent -hello() cat <<EOF -Hello World! -EOF -.Ed -.Pp -To be correctly standards conforming this should be re-written as: -.Bd -literal -offset indent -hello() { cat; } <<EOF -Hello World! -EOF -.Ed -.Pp -Note the distinction between those forms, and -.Bd -literal -offset indent -hello() { cat <<EOF -Hello World! -EOF -\&} -.Ed -.Pp -which reads and processes the here-document -each time the shell executes the function, and which applies -that input only to the cat command, not to any other commands -that might appear in the function. -.Pp -Variables may be declared to be local to a function by using the -.Ic local -command. -This should usually appear as the first statement of a function, -though -.Ic local -is an executable command which can be used anywhere in a function. -See -.Sx Built-ins -below for its definition. -.Pp -The function completes after having executed -.Ar command -with exit status set to the status returned by -.Ar command . -If -.Ar command -is a compound-command -it can use the -.Ic return -command (see -.Sx Built-ins -below) -to finish before completing all of -.Ar command . -.Ss Variables and Parameters -The shell maintains a set of parameters. -A parameter denoted by a name is called a variable. -When starting up, the shell turns all the environment -variables into shell variables, and exports them. -New variables can be set using the form -.Pp -.Dl Ar name Ns Li = Ns Ar value -.Pp -Variables set by the user must have a name consisting solely of -alphabetics, numerics, and underscores \(em the first of which must not be -numeric. -A parameter can also be denoted by a number or a special -character as explained below. -.Ss Positional Parameters -A positional parameter is a parameter denoted by a number (n > 0). -The shell sets these initially to the values of its command line arguments -that follow the name of the shell script. -The -.Ic set -built-in can also be used to set or reset them, and -.Ic shift -can be used to manipulate the list. -.Pp -To refer to the 10th (and later) positional parameters, -the form -.Li \&${ Ns Ar n Ns Li \&} -must be used. -Without the braces, a digit following -.Dq $ -can only refer to one of the first 9 positional parameters, -or the special parameter -.Dv 0 . \" $0 -The word -.Dq Li $10 -is treated identically to -.Dq Li ${1}0 . -.\" -.\" -.Ss Special Parameters -.\" -A special parameter is a parameter denoted by one of the following special -characters. -The value of the parameter is listed next to its character. -.Bl -tag -width thinhyphena -.It Dv * -Expands to the positional parameters, starting from one. -When the -expansion occurs within a double-quoted string it expands to a single -field with the value of each parameter separated by the first character of -the -.Ev IFS -variable, or by a -.Aq space -if -.Ev IFS -is unset. -.It Dv @ \" $@ -Expands to the positional parameters, starting from one. -When the expansion occurs within double quotes, each positional -parameter expands as a separate argument. -If there are no positional parameters, the -expansion of @ generates zero arguments, even when -.Dv $@ -is double-quoted. -What this basically means, for example, is -if -.Li $1 -is -.Dq abc -and -.Li $2 -is -.Dq def\ ghi , -then -.Li \*q$@\*q -expands to -the two arguments: -.Pp -.Sm off -.Dl \*q abc \*q \ \*q def\ ghi \*q -.Sm on -.It Dv # -Expands to the number of positional parameters. -.It Dv \&? -Expands to the exit status of the most recent pipeline. -.It Dv \- No (hyphen, or minus) -Expands to the current option flags (the single-letter -option names concatenated into a string) as specified on -invocation, by the set built-in command, or implicitly -by the shell. -.It Dv $ -Expands to the process ID of the invoked shell. -A sub-shell retains the same value of -.Dv $ -as its parent. -.It Dv \&! -Expands to the process ID of the most recent background -command executed from the current shell. -For a pipeline, the process ID is that of the last command in the pipeline. -If no background commands have yet been started by the shell, then -.Dq Dv \&! -will be unset. -Once set, the value of -.Dq Dv \&! -will be retained until another background command is started. -.It Dv 0 No (zero) \" $0 -Expands to the name of the shell or shell script. -.El -.\" -.\" -.Ss Word Expansions -.\" -This section describes the various expansions that are performed on words. -Not all expansions are performed on every word, as explained later. -.Pp -Tilde expansions, parameter expansions, command substitutions, arithmetic -expansions, and quote removals that occur within a single word expand to a -single field. -It is only field splitting or pathname expansion that can -create multiple fields from a single word. -The single exception to this -rule is the expansion of the special parameter -.Dv @ \" $@ -within double quotes, as was described above. -.Pp -The order of word expansion is: -.Bl -enum -.It -Tilde Expansion, Parameter Expansion, Command Substitution, -Arithmetic Expansion (these all occur at the same time). -.It -Field Splitting is performed on fields -generated by step (1) unless the -.Ev IFS -variable is null. -.It -Pathname Expansion (unless set -.Fl f -is in effect). -.It -Quote Removal. -.El -.Pp -The $ character is used to introduce parameter expansion, command -substitution, or arithmetic evaluation. -.Ss Tilde Expansion (substituting a user's home directory) -A word beginning with an unquoted tilde character (~) is -subjected to tilde expansion. -Provided all of the subsequent characters in the word are unquoted -up to an unquoted slash (/) -or when in an assignment or not in posix mode, an unquoted colon (:), -or if neither of those appear, the end of the word, -they are treated as a user name -and are replaced with the pathname of the named user's home directory. -If the user name is missing (as in -.Pa ~/foobar ) , -the tilde is replaced with the value of the -.Dv HOME -variable (the current user's home directory). -.Pp -In variable assignments, -an unquoted tilde immediately after the assignment operator (=), and -each unquoted tilde immediately after an unquoted colon in the value -to be assigned is also subject to tilde expansion as just stated. -.\" -.\" -.Ss Parameter Expansion -.\" -The format for parameter expansion is as follows: -.Pp -.Dl ${ Ns Ar expression Ns Li } -.Pp -where -.Ar expression -consists of all characters until the matching -.Sq Li } . -Any -.Sq Li } -escaped by a backslash or within a quoted string, and characters in -embedded arithmetic expansions, command substitutions, and variable -expansions, are not examined in determining the matching -.Sq Li } . -.Pp -The simplest form for parameter expansion is: -.Pp -.Dl ${ Ns Ar parameter Ns Li } -.Pp -The value, if any, of -.Ar parameter -is substituted. -.Pp -The parameter name or symbol can be enclosed in braces, -which are optional in this simple case, -except for positional parameters with more than one digit or -when parameter is followed by a character that could be interpreted as -part of the name. -If a parameter expansion occurs inside double quotes: -.Bl -enum -.It -pathname expansion is not performed on the results of the expansion; -.It -field splitting is not performed on the results of the -expansion, with the exception of the special rules for -.Dv @ . \" $@ -.El -.Pp -In addition, a parameter expansion where braces are used, -can be modified by using one of the following formats. -If the -.Sq Ic \&: -is omitted in the following modifiers, then the test in the expansion -applies only to unset parameters, not null ones. -.Bl -tag -width aaparameterwordaaaaa -.It Li ${ Ns Ar parameter Ns Ic :- Ns Ar word Ns Li } -.Sy Use Default Values. -If -.Ar parameter -is unset or null, the expansion of -.Ar word -is substituted; otherwise, the value of -.Ar parameter -is substituted. -.It Li ${ Ns Ar parameter Ns Ic := Ns Ar word Ns Li } -.Sy Assign Default Values. -If -.Ar parameter -is unset or null, the expansion of -.Ar word -is assigned to -.Ar parameter . -In all cases, the final value of -.Ar parameter -is substituted. -Only variables, not positional parameters or special -parameters, can be assigned in this way. -.It Li ${ Ns Ar parameter Ns Ic :? Ns Oo Ar word\^ Oc Ns Li } -.Sy Indicate Error if Null or Unset. -If -.Ar parameter -is unset or null, the expansion of -.Ar word -(or a message indicating it is unset if -.Ar word -is omitted) -is written to standard error and a non-interactive shell exits with -a nonzero exit status. -An interactive shell will not exit, but any associated command(s) will -not be executed. -If the -.Ar parameter -is set, its value is substituted. -.It Li ${ Ns Ar parameter Ns Ic :+ Ns Ar word Ns Li } -.Sy Use Alternative Value. -If -.Ar parameter -is unset or null, null is substituted; -otherwise, the expansion of -.Ar word -is substituted. -The value of -.Ar parameter -.Em is not used -in this expansion. -.It Li ${ Ns Ic # Ns Ar parameter Ns Li } -.Sy String Length. -The length in characters of the value of -.Ar parameter . -.El -.Pp -The following four varieties of parameter expansion provide for substring -processing. -In each case, pattern matching notation (see -.Sx Shell Patterns ) , -rather than regular expression notation, is used to evaluate the patterns. -If parameter is -.Dv * -or -.Dv @ , \" $@ -the result of the expansion is unspecified. -Enclosing the full parameter expansion string in double quotes does not -cause the following four varieties of pattern characters to be quoted, -whereas quoting characters within the braces has this effect. -.Bl -tag -width aaparameterwordaaaaa -.It Li ${ Ns Ar parameter Ns Ic % Ns Ar word Ns Li } -.Sy Remove Smallest Suffix Pattern. -The -.Ar word -is expanded to produce a pattern. -The parameter expansion then results in -.Ar parameter , -with the -smallest portion of the suffix matched by the pattern deleted. -If the -.Ar word -is to start with a -.Sq Li \&% -character, it must be quoted. -.It Li ${ Ns Ar parameter Ns Ic %% Ns Ar word Ns Li } -.Sy Remove Largest Suffix Pattern. -The -.Ar word -is expanded to produce a pattern. -The parameter expansion then results in -.Ar parameter , -with the largest -portion of the suffix matched by the pattern deleted. -The -.Dq Ic %% -pattern operator only produces different results from the -.Dq Ic \&% -operator when the pattern contains at least one unquoted -.Sq Li \&* . -.It Li ${ Ns Ar parameter Ns Ic \&# Ns Ar word Ns Li } -.Sy Remove Smallest Prefix Pattern. -The -.Ar word -is expanded to produce a pattern. -The parameter expansion then results in -.Ar parameter , -with the -smallest portion of the prefix matched by the pattern deleted. -If the -.Ar word -is to start with a -.Sq Li \&# -character, it must be quoted. -.It Li ${ Ns Ar parameter Ns Ic \&## Ns Ar word Ns Li } -.Sy Remove Largest Prefix Pattern. -The -.Ar word -is expanded to produce a pattern. -The parameter expansion then results in -.Ar parameter , -with the largest -portion of the prefix matched by the pattern deleted. -This has the same relationship with the -.Dq Ic \&# -pattern operator as -.Dq Ic %% -has with -.Dq Ic \&% . -.El -.\" -.\" -.Ss Command Substitution -.\" -Command substitution allows the output of a command to be substituted in -place of the command (and surrounding syntax). -Command substitution occurs when a word contains -a command list enclosed as follows: -.Pp -.Dl Ic $( Ns Ar list Ns Ic \&) -.Pp -or the older -.Pq Dq backquoted -version, which is best avoided: -.Pp -.Dl Ic \&` Ns Ar list Ns Ns Ic \&` -.Pp -See the section -.Sx Complex Commands -above for the definition of -.Ic list . -.Pp -The shell expands the command substitution by executing the -.Ar list -in a sub-shell environment and replacing the command substitution with the -standard output of the -.Ar list -after removing any sequence of one or more -.Ao newline Ac Ns s -from the end of the substitution. -(Embedded -.Ao newline Ac Ns s -before -the end of the output are not removed; however, during field splitting, -they may be used to separate fields -.Pq "as spaces usually are" -depending on the value of -.Ev IFS -and any quoting that is in effect.) -.Pp -Note that if a command substitution includes commands -to be run in the background, -the sub-shell running those commands -will only wait for them to complete if an appropriate -.Ic wait -command is included in the command list. -However, the shell in which the result of the command substitution -will be used will wait for both the sub-shell to exit and for the -file descriptor that was initially standard output for the command -substitution sub-shell to be closed. -In some circumstances this might not happen until all processes -started by the command substitution have finished. -.\" While the exit of the sub-shell closes its standard output, -.\" any background process left running may still -.\" have that file descriptor open. -.\" This includes yet another sub-shell which might have been -.\" (almost invisibly) created to wait for some other command to complete, -.\" and even where the background command has had its -.\" standard output redirected or closed, -.\" the waiting sub-shell may still have it open. -.\" Thus there is no guarantee that the result of a command substitution -.\" will be available in the shell which is to use it before all of -.\" the commands started by the command substitution have completed, -.\" though careful coding can often avoid delays beyond the termination -.\" of the command substitution sub-shell. -.\" .Pp -.\" For example, assuming a script were to contain the following -.\" code (which could be done better other ways, attempting -.\" this kind of trickery is not recommended): -.\" .Bd -literal -offset indent -.\" if [ "$( printf "Ready? " >&2; read ans; printf "${ans}"; -.\" { sleep 120 >/dev/null && kill $$ >/dev/null 2>&1; }& )" = go ] -.\" then -.\" printf Working... -.\" # more code -.\" fi -.\" .Ed -.\" .Pp -.\" the -.\" .Dq Working... -.\" output will not be printed, and code that follows will never be executed. -.\" Nor will anything later in the script -.\" .Po -.\" unless -.\" .Dv SIGTERM -.\" is trapped or ignored -.\" .Pc . -.\" .Pp -.\" The intent is to prompt the user, wait for the user to -.\" answer, then if the answer was -.\" .Dq go -.\" do the appropriate work, but set a 2 minute time limit -.\" on completing that work. -.\" If the work is not done by then, kill the shell doing it. -.\" .Pp -.\" It will usually not work as written, as while the 2 minute -.\" .Sq sleep -.\" has its standard output redirected, as does the -.\" .Sq kill -.\" that follows (which also redirects standard error, -.\" so the user would not see an error if the work were -.\" completed and there was no parent process left to kill); -.\" the sub-shell waiting for the -.\" .Sq sleep -.\" to finish successfully, so it can start the -.\" .Sq kill , -.\" does not. -.\" It waits, with standard output still open, -.\" for the 2 minutes until the sleep is done, -.\" even though the kill is not going to need that file descriptor, -.\" and there is nothing else which could. -.\" The command substitution does not complete until after -.\" the kill has executed and the background sub-shell -.\" finishes \(en at which time the shell running it is -.\" presumably dead. -.\" .Pp -.\" Rewriting the background sub-shell part of that as -.\" .Dl "{ sleep 120 && kill $$ 2>&1; } >/dev/null &" -.\" would allow this -.\" .Nm -.\" to perform as expected, but that is not guaranteed, -.\" not all shells would behave as planned. -.\" It is advised to avoid starting background processes -.\" from within a command substitution. -.\" -.\" -.Ss Arithmetic Expansion -.\" -Arithmetic expansion provides a mechanism for evaluating an arithmetic -expression and substituting its value. -The format for arithmetic expansion is as follows: -.Pp -.Dl Ic $(( Ns Ar expression Ns Ic \&)) -.Pp -The expression in an arithmetic expansion is treated as if it were in -double quotes, except that a double quote character inside the expression -is just a normal character (it quotes nothing.) -The shell expands all tokens in the expression for parameter expansion, -command substitution, and quote removal (the only quoting character is -the backslash -.Sq \&\e , -and only when followed by another -.Sq \&\e , -a dollar sign -.Sq \&$ , -a backquote -.Sq \&` -or a newline.) -.Pp -Next, the shell evaluates the expanded result as an arithmetic expression -and substitutes the calculated value of that expression. -.Pp -Arithmetic expressions use a syntax similar to that -of the C language, and are evaluated using the -.Ql intmax_t -data type (this is an extension to POSIX, which requires only -.Ql long -arithmetic.) -Shell variables may be referenced by name inside an arithmetic -expression, without needing a -.Dq \&$ -sign. -Variables that are not set, or which have an empty (null string) value, -used this way evaluate as zero (that is, -.Dq x -in arithmetic, as an R-Value, is evaluated as -.Dq ${x:-0} ) -unless the -.Nm -.Fl u -flag is set, in which case a reference to an unset variable is an error. -Note that unset variables used in the ${var} form expand to a null -string, which might result in syntax errors. -Referencing the value of a variable which is not numeric is an error. -.Pp -All of the C expression operators applicable to integers are supported, -and operate as they would in a C expression. -Use white space, or parentheses, to disambiguate confusing syntax, -otherwise, as in C, the longest sequence of consecutive characters -which make a valid token (operator, variable name, or number) is taken -to be that token, even if the token designated cannot be used -and a different interpretation could produce a successful parse. -This means, as an example, that -.Dq a+++++b -is parsed as the gibberish sequence -.Dq "a ++ ++ + b" , -rather than as the valid alternative -.Dq "a ++ + ++ b" . -Similarly, separate the -.Sq \&, -operator from numbers with white space to avoid the possibility -of confusion with the decimal indicator in some locales (though -fractional, or floating-point, numbers are not supported in this -implementation.) -.Pp -It should not be necessary to state that the C operators which -operate on, or produce, pointer types, are not supported. -Those include unary -.Dq \&* -and -.Dq \&& -and the struct and array referencing binary operators: -.Dq \&. , -.Dq \&-> -and -.Dq \&[ . -.\" -.\" -.Ss White Space Splitting (Field Splitting) -.\" -After parameter expansion, command substitution, and -arithmetic expansion the shell scans the results of -expansions and substitutions that did not occur in double quotes, -and -.Dq Li $@ -even if it did, -for field splitting and multiple fields can result. -.Pp -The shell treats each character of the -.Ev IFS -as a delimiter and uses the delimiters to split the results of parameter -expansion and command substitution into fields. -.Pp -Non-whitespace characters in -.Ev IFS -are treated strictly as parameter separators. -So adjacent non-whitespace -.Ev IFS -characters will produce empty parameters. -On the other hand, any sequence of whitespace -characters that occur in -.Ev IFS -(known as -.Ev IFS -whitespace) -can occur, leading and trailing -.Ev IFS -whitespace, and any -.Ev IFS -whitespace surrounding a non whitespace -.Ev IFS -delimiter, is removed. -Any sequence of -.Ev IFS -whitespace characters without a non-whitespace -.Ev IFS -delimiter acts as a single field separator. -.Pp -If -.Ev IFS -is unset it is assumed to contain space, tab, and newline, -all of which are -.Ev IFS -whitespace characters. -If -.Ev IFS -is set to a null string, there are no delimiters, -and no field splitting occurs. -.Ss Pathname Expansion (File Name Generation) -Unless the -.Fl f -flag is set, file name generation is performed after word splitting is -complete. -Each word is viewed as a series of patterns, separated by slashes. -The process of expansion replaces the word with the names of all -existing files whose names can be formed by replacing each pattern with a -string that matches the specified pattern. -There are two restrictions on -this: first, a pattern cannot match a string containing a slash, and -second, a pattern cannot match a string starting with a period unless the -first character of the pattern is a period. -The next section describes the -patterns used for both Pathname Expansion and the -.Ic case -command. -.Ss Shell Patterns -A pattern consists of normal characters, which match themselves, -and meta-characters. -The meta-characters are -.Dq \&! , -.Dq * , -.Dq \&? , -and -.Dq \&[ . -These characters lose their special meanings if they are quoted. -When command or variable substitution is performed -and the dollar sign or backquotes are not double-quoted, -the value of the variable or the output of -the command is scanned for these characters and they are turned into -meta-characters. -.Pp -An asterisk -.Pq Dq * -matches any string of characters. -A question mark -.Pq Dq \&? -matches any single character. -A left bracket -.Pq Dq \&[ -introduces a character class. -The end of the character class is indicated by a right bracket -.Pq Dq \&] ; -if this -.Dq \&] -is missing then the -.Dq \&[ -matches a -.Dq \&[ -rather than introducing a character class. -A character class matches any of the characters between the square brackets. -A named class of characters (see -.Xr wctype 3 ) -may be specified by surrounding the name with -.Pq Dq [: -and -.Pq Dq :] . -For example, -.Pq Dq [[:alpha:]] -is a shell pattern that matches a single letter. -A range of characters may be specified using a minus sign -.Pq Dq \(mi . -The character class may be complemented -by making an exclamation mark -.Pq Dq \&! -the first character of the character class. -.Pp -To include a -.Dq \&] -in a character class, make it the first character listed (after the -.Dq \&! , -if any). -To include a -.Dq \(mi , -make it the first (after !) or last character listed. -If both -.Dq \&] -and -.Dq \(mi -are to be included, the -.Dq \&] -must be first (after !) -and the -.Dq \(mi -last, in the character class. -.\" -.\" -.Ss Built-ins -.\" -This section lists the built-in commands which are built-in because they -need to perform some operation that can't be performed by a separate -process. -Or just because they traditionally are. -In addition to these, there are several other commands that may -be built in for efficiency (e.g. -.Xr printf 1 , -.Xr echo 1 , -.Xr test 1 , -etc). -.Bl -tag -width 5n -.It Ic \&: Op Ar arg ... -A null command that returns a 0 (true) exit value. -Any arguments or redirects are evaluated, then ignored. -.\" -.It Ic \&. Ar file -The dot command reads and executes the commands from the specified -.Ar file -in the current shell environment. -The file does not need to be executable and is looked up from the directories -listed in the -.Ev PATH -variable if its name does not contain a directory separator -.Pq Sq / . -The -.Ic return -command (see below) -can be used for a premature return from the sourced file. -.Pp -The POSIX standard has been unclear on how loop control keywords (break -and continue) behave across a dot command boundary. -This implementation allows them to control loops surrounding the dot command, -but obviously such behavior should not be relied on. -It is now permitted by the standard, but not required. -.\" -.It Ic alias Op Ar name Ns Op Li = Ns Ar string ... -If -.Ar name Ns Li = Ns Ar string -is specified, the shell defines the alias -.Ar name -with value -.Ar string . -If just -.Ar name -is specified, the value of the alias -.Ar name -is printed. -With no arguments, the -.Ic alias -built-in prints the -names and values of all defined aliases (see -.Ic unalias ) . -.\" -.It Ic bg Op Ar job ... -Continue the specified jobs (or the current job if no -jobs are given) in the background. -.\" -.It Ic command Oo Fl pVv Oc Ar command Op Ar arg ... -Execute the specified command but ignore shell functions when searching -for it. -(This is useful when you -have a shell function with the same name as a command.) -.Bl -tag -width 5n -.It Fl p -search for command using a -.Ev PATH -that guarantees to find all the standard utilities. -.It Fl V -Do not execute the command but -search for the command and print the resolution of the -command search. -This is the same as the -.Ic type -built-in. -.It Fl v -Do not execute the command but -search for the command and print the absolute pathname -of utilities, the name for built-ins or the expansion of aliases. -.El -.\" -.It Ic cd Oo Fl P Oc Op Ar directory Op Ar replace -Switch to the specified directory (default -.Ev $HOME ) . -If -.Ar replace -is specified, then the new directory name is generated by replacing -the first occurrence of the string -.Ar directory -in the current directory name with -.Ar replace . -Otherwise if -.Ar directory -is -.Sq Li - , -then the current working directory is changed to the previous current -working directory as set in -.Ev OLDPWD . -Otherwise if an entry for -.Ev CDPATH -appears in the environment of the -.Ic cd -command or the shell variable -.Ev CDPATH -is set and the directory name does not begin with a slash, -and its first (or only) component isn't dot or dot dot, -then the directories listed in -.Ev CDPATH -will be searched for the specified directory. -The format of -.Ev CDPATH -is the same as that of -.Ev PATH . -.Pp -The -.Fl P -option instructs the shell to update -.Ev PWD -with the specified physical directory path and change to that directory. -This is the default. -.Pp -When the directory changes, the variable -.Ev OLDPWD -is set to the working directory before the change. -.Pp -Some shells also support a -.Fl L -option, which instructs the shell to update -.Ev PWD -with the logical path and to change the current directory -accordingly. -This is not supported. -.Pp -In an interactive shell, the -.Ic cd -command will print out the name of the -directory that it actually switched to if this is different from the name -that the user gave, -or always if the -.Cm cdprint -option is set. -The destination may be different either because the -.Ev CDPATH -mechanism was used -.\" or because a symbolic link was crossed. -or if the -.Ar replace -argument was used. -.\" -.It Ic eval Ar string ... -Concatenate all the arguments with spaces. -Then re-parse and execute the command. -.\" -.It Ic exec Op Ar command Op Ar arg ... -Unless -.Ar command -is omitted, the shell process is replaced with the -specified program (which must be a real program, not a shell built-in or -function). -Any redirections on the -.Ic exec -command are marked as permanent, so that they are not undone when the -.Ic exec -command finishes. -When the -.Cm posix -option is not set, -file descriptors created via such redirections are marked close-on-exec -(see -.Xr open 2 -.Dv O_CLOEXEC -or -.Xr fcntl 2 -.Dv F_SETFD / -.Dv FD_CLOEXEC ) , -unless the descriptors refer to the standard input, -output, or error (file descriptors 0, 1, 2). -Traditionally Bourne-like shells -(except -.Xr ksh 1 ) , -made those file descriptors available to exec'ed processes. -To be assured the close-on-exec setting is off, -redirect the descriptor to (or from) itself, -either when invoking a command for which the descriptor is wanted open, -or by using -.Ic exec -(perhaps the same -.Ic exec -as opened it, after the open) -to leave the descriptor open in the shell -and pass it to all commands invoked subsequently. -Alternatively, see the -.Ic fdflags -command below, which can set, or clear, this, and other, -file descriptor flags. -.\" -.It Ic exit Op Ar exitstatus -Terminate the shell process. -If -.Ar exitstatus -is given it is used as the exit status of the shell; otherwise the -exit status of the preceding command (the current value of $?) is used. -.\" -.It Ic export Oo Fl nx Oc Ar name Ns Oo =value Oc ... -.It Ic export Oo Fl x Oc Oo Fl p Oo Ar name ... Oc Oc -.It Ic export Fl q Oo Fl x Oc Ar name ... -With no options, -but one or more names, -the specified names are exported so that they will appear in the -environment of subsequent commands. -With -.Fl n -the specified names are un-exported. -Variables can also be un-exported using the -.Ic unset -built in command. -With -.Fl x -(exclude) the specified names are marked not to be exported, -and any that had been exported, will be un-exported. -Later attempts to export the variable will be refused. -Note this does not prevent explicitly exporting a variable -to a single command, script or function by preceding that -command invocation by a variable assignment to that variable, -provided the variable is not also read-only. -That is -.Bd -literal -offset indent -export -x FOO # FOO will now not be exported by default -export FOO # this command will fail (non-fatally) -FOO=some_value my_command -.Ed -.Pp -still passes the value -.Pq Li FOO=some_value -to -.Li my_command -through the environment. -.Pp -The shell allows the value of a variable to be set at the -same time it is exported (or unexported, etc) by writing -.Pp -.Dl export [-nx] name=value -.Pp -With no arguments the export command lists the names of all -set exported variables, -or if -.Fl x -was given, all set variables marked not for export. -With the -.Fl p -option specified, the output will be formatted suitably for -non-interactive use, and unset variables are included. -When -.Fl p -is given, variable names, but not values, may also be -given, in which case output is limited to the variables named. -.Pp -With -.Fl q -and a list of variable names, the -.Ic export -command will exit with status 0 if all the named -variables have been marked for export, or 1 if -any are not so marked. -If -.Fl x -is also given, -the test is instead for variables marked not to be exported. -.Pp -Other than with -.Fl q , -the -.Ic export -built-in exits with status 0, -unless an attempt is made to export a variable which has -been marked as unavailable for export, -in which cases it exits with status 1. -In all cases if -an invalid option, or option combination, is given, -or an invalid variable name is present, -.Ic export -will write a message to the standard error output, -and exit with a non-zero status. -A non-interactive shell will terminate. -.Pp -Note that there is no restriction upon exporting, -or un-exporting, read-only variables. -The no-export flag can be reset by unsetting the variable -and creating it again \(en provided the variable is not also read-only. -.\" -.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last -.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last -.It Ic fc Fl s Oo Ar old=new Oc Op Ar first -The -.Ic fc -built-in lists, or edits and re-executes, commands previously entered -to an interactive shell. -.Bl -tag -width 5n -.It Fl e Ar editor -Use the editor named by -.Ar editor -to edit the commands. -The -.Ar editor -string is a command name, subject to search via the -.Ev PATH -variable. -The value in the -.Ev FCEDIT -variable is used as a default when -.Fl e -is not specified. -If -.Ev FCEDIT -is null or unset, the value of the -.Ev EDITOR -variable is used. -If -.Ev EDITOR -is null or unset, -.Xr ed 1 -is used as the editor. -.It Fl l No (ell) -List the commands rather than invoking an editor on them. -The commands are written in the sequence indicated by -the first and last operands, as affected by -.Fl r , -with each command preceded by the command number. -.It Fl n -Suppress command numbers when listing with -.Fl l . -.It Fl r -Reverse the order of the commands listed (with -.Fl l ) -or edited (with neither -.Fl l -nor -.Fl s ) . -.It Fl s -Re-execute the command without invoking an editor. -.It Ar first -.It Ar last -Select the commands to list or edit. -The number of previous commands that -can be accessed are determined by the value of the -.Ev HISTSIZE -variable. -The value of -.Ar first -or -.Ar last -or both are one of the following: -.Bl -tag -width 5n -.It Oo Cm + Oc Ns Ar number -A positive number representing a command number; command numbers can be -displayed with the -.Fl l -option. -.It Cm \- Ns Ar number -A negative decimal number representing the command that was executed -number of commands previously. -For example, \-1 is the immediately previous command. -.El -.It Ar string -A string indicating the most recently entered command that begins with -that string. -If the -.Ar old Ns Li = Ns Ar new -operand is not also specified with -.Fl s , -the string form of the first operand cannot contain an embedded equal sign. -.El -.Pp -The following environment variables affect the execution of -.Ic fc : -.Bl -tag -width HISTSIZE -.It Ev FCEDIT -Name of the editor to use. -.It Ev HISTSIZE -The number of previous commands that are accessible. -.El -.\" -.It Ic fg Op Ar job -Move the specified job or the current job to the foreground. -A foreground job can interact with the user via standard input, -and receive signals from the terminal. -.\" -.It Ic fdflags Oo Fl v Oc Op Ar fd ... -.It Ic fdflags Oo Fl v Oc Fl s Ar flags fd Op ... -Get or set file descriptor flags. -The -.Fl v -argument enables verbose printing, printing flags that are also off, and -the flags of the file descriptor being set after setting. -The -.Fl s -flag interprets the -.Ar flags -argument as a comma separated list of file descriptor flags, each preceded -with a -.Dq \(pl -or a -.Dq \(mi -indicating to set or clear the respective flag. -Valid flags are: -.Cm append , -.Cm async , -.Cm sync , -.Cm nonblock , -.Cm fsync , -.Cm dsync , -.Cm rsync , -.Cm direct , -.Cm nosigpipe , -and -.Cm cloexec . -Unique abbreviations of these names, of at least 2 characters, -may be used on input. -See -.Xr fcntl 2 -and -.Xr open 2 -for more information. -.\" -.It Ic getopts Ar optstring var -The POSIX -.Ic getopts -command, not to be confused with the -Bell Labs\[en]derived -.Xr getopt 1 . -.Pp -The first argument should be a series of letters, each of which may be -optionally followed by a colon to indicate that the option requires an -argument. -The variable specified is set to the parsed option. -.Pp -The -.Ic getopts -command deprecates the older -.Xr getopt 1 -utility due to its handling of arguments containing whitespace. -.Pp -The -.Ic getopts -built-in may be used to obtain options and their arguments -from a list of parameters. -When invoked, -.Ic getopts -places the value of the next option from the option string in the list in -the shell variable specified by -.Ar var -and its index in the shell variable -.Ev OPTIND . -When the shell is invoked, -.Ev OPTIND -is initialized to 1. -For each option that requires an argument, the -.Ic getopts -built-in will place it in the shell variable -.Ev OPTARG . -If an option is not allowed for in the -.Ar optstring , -then -.Ev OPTARG -will be unset. -.Pp -.Ar optstring -is a string of recognized option letters (see -.Xr getopt 3 ) . -If a letter is followed by a colon, the option is expected to have an -argument which may or may not be separated from it by whitespace. -If an option character is not found where expected, -.Ic getopts -will set the variable -.Ar var -to a -.Sq Li \&? ; -.Ic getopts -will then unset -.Ev OPTARG -and write output to standard error. -By specifying a colon as the first character of -.Ar optstring -all errors will be ignored. -.Pp -A nonzero value is returned when the last option is reached. -If there are no remaining arguments, -.Ic getopts -will set -.Ar var -to the special option, -.Dq Li \-\- , -otherwise, it will set -.Ar var -to -.Sq Li \&? . -.Pp -The following code fragment shows how one might process the arguments -for a command that can take the options -.Fl a -and -.Fl b , -and the option -.Fl c , -which requires an argument. -.Bd -literal -offset indent -while getopts abc: f -do - case $f in - a | b) flag=$f;; - c) carg=$OPTARG;; - \e?) echo $USAGE; exit 1;; - esac -done -shift $((OPTIND - 1)) -.Ed -.Pp -This code will accept any of the following as equivalent: -.Bd -literal -offset indent -cmd \-acarg file file -cmd \-a \-c arg file file -cmd \-carg -a file file -cmd \-a \-carg \-\- file file -.Ed -.\" -.It Ic hash Oo Fl rv Oc Op Ar command ... -The shell maintains a hash table which remembers the -locations of commands. -With no arguments whatsoever, -the -.Ic hash -command prints out the contents of this table. -Entries which have not been looked at since the last -.Ic cd -command are marked with an asterisk; it is possible for these entries -to be invalid. -.Pp -With arguments, the -.Ic hash -command removes the specified commands from the hash table (unless -they are functions) and then locates them. -With the -.Fl v -option, hash prints the locations of the commands as it finds them. -The -.Fl r -option causes the hash command to delete all the entries in the hash table -except for functions. -.\" -.It Ic inputrc Ar file -Read the -.Ar file -to set key bindings as defined by -.Xr editrc 5 . -.\" -.It Ic jobid Oo Fl g Ns \&| Ns Fl j Ns \&| Ns Fl p Oc Op Ar job -With no flags, print the process identifiers of the processes in the job. -If the -.Ar job -argument is omitted, the current job is used. -Any of the ways to select a job may be used for -.Ar job , -including the -.Sq Li \&% -forms, or the process id of the job leader -.Po -.Dq Li \&$! -if the job was created in the background. -.Pc -.Pp -If one of the flags is given, then instead of the list of -process identifiers, the -.Ic jobid -command prints: -.Bl -tag -width ".Fl g" -.It Fl g -the process group, if one was created for this job, -or nothing otherwise (the job is in the same process -group as the shell.) -.It Fl j -the job identifier (using -.Dq Li \&% Ns Ar n -notation, where -.Ar n -is a number) is printed. -.It Fl p -only the process id of the process group leader is printed. -.El -.Pp -These flags are mutually exclusive. -.Pp -.Ic jobid -exits with status 2 if there is an argument error, -status 1, if with -.Fl g -the job had no separate process group, -or with -.Fl p -there is no process group leader (should not happen), -and otherwise exits with status 0. -.\" -.It Ic jobs Oo Fl l Ns \&| Ns Fl p Oc Op Ar job ... -Without -.Ar job -arguments, -this command lists out all the background processes -which are children of the current shell process. -With -.Ar job -arguments, the listed jobs are shown instead. -Without flags, the output contains the job -identifier (see -.Sx Job Control -below), an indicator character if the job is the current or previous job, -the current status of the job (running, suspended, or terminated successfully, -unsuccessfully, or by a signal) -and a (usually abbreviated) command string. -.Pp -With the -.Fl l -flag the output is in a longer form, with the process identifiers -of each process (run from the top level, as in a pipeline), and the -status of each process, rather than the job status. -.Pp -With the -.Fl p -flag, the output contains only the process identifier of the lead -process. -.Pp -In an interactive shell, each job shown as completed in the output -from the jobs command is implicitly waited for, and is removed from -the jobs table, never to be seen again. -In an interactive shell, when a background job terminates, the -.Ic jobs -command (with that job as an argument) is implicitly run just -before outputting the next PS1 command prompt, after the job -terminated. -This indicates that the job finished, shows its status, -and cleans up the job table entry for that job. -Non-interactive shells need to execute -.Ic wait -commands to clean up terminated background jobs. -.\" -.It Ic local Oo Fl INx Oc Oo Ar variable | \- Oc ... -Define local variables for a function. -Local variables have their attributes, and values, -as they were before the -.Ic local -declaration, restored when the function terminates. -.Pp -With the -.Fl N -flag, variables made local, are unset initially inside -the function. -Unless the -.Fl x -flag is also given, such variables are also unexported. -The -.Fl I -flag, which is the default in this shell, causes -the initial value and exported attribute -of local variables -to be inherited from the variable -with the same name in the surrounding -scope, if there is one. -If there is not, the variable is initially unset, -and not exported. -The -.Fl N -and -.Fl I -flags are mutually exclusive, if both are given, the last specified applies. -The read-only and unexportable attributes are always -inherited, if a variable with the same name already exists. -.Pp -The -.Fl x -flag (lower case) causes the local variable to be exported, -while the function runs, unless it has the unexportable attribute. -This can also be accomplished by using the -.Ic export -command, giving the same -.Ar variable -names, after the -.Ic local -command. -.Pp -Making an existing read-only variable local is possible, -but pointless. -If an attempt is made to assign an initial value to such -a variable, the -.Ic local -command fails, as does any later attempted assignment. -If the -.Ic readonly -command is applied to a variable that has been declared local, -the variable cannot be (further) modified within the function, -or any other functions it calls, however when the function returns, -the previous status (and value) of the variable is returned. -.Pp -Values may be given to local variables on the -.Ic local -command line in a similar fashion as used for -.Ic export -and -.Ic readonly . -These values are assigned immediately after the initialization -described above. -Note that any variable references on the command line will have -been expanded before -.Ic local -is executed, so expressions like -.Pp -.Dl "local -N X=${X}" -.Pp -are well defined, first $X is expanded, and then the command run is -.Pp -.Dl "local -N X=old-value-of-X" -.Pp -After arranging to preserve the old value and attributes, of -.Dv X -.Dq ( old-value-of X ) -.Ic local -unsets -.Dv X , -unexports it, and then assigns the -.Dq old-value-of-X -to -.Ev X . -.Pp -The shell uses dynamic scoping, so that if you make the variable -.Dv x -local to -function -.Dv f , -which then calls function -.Dv g , -references to the variable -.Dv x -made inside -.Dv g -will refer to the variable -.Dv x -declared inside -.Dv f , -not to the global variable named -.Dv x . -.Pp -Another way to view this, is as if the shell just has one flat, global, -namespace, in which all variables exist. -The -.Ic local -command conceptually copies the variable(s) named to unnamed temporary -variables, and when the function ends, copies them back again. -All references to the variables reference the same global variables, -but while the function is active, after the -.Ic local -command has run, the values and attributes of the variables might -be altered, and later, when the function completes, be restored. -.Pp -Note that the positional parameters -.Dv 1 , \" $1 -.Dv 2 , \" $2 -\&... (see -.Sx Positional Parameters ) , -and the special parameters -.Dv \&# , \" $# -.Dv \&* \" $* -and -.Dv \&@ \" $@ -(see -.Sx Special Parameters ) , -are always made local in all functions, and are reset inside the -function to represent the options and arguments passed to the function. -Note that -.Li $0 -however retains the value it had outside the function, -as do all the other special parameters. -.Pp -The only special parameter that can optionally be made local is -.Dq Li \- . -Making -.Dq Li \- -local causes any shell options that are changed via the set command inside the -function to be restored to their original values when the function -returns. -If -.Fl X -option is altered after -.Dq Li \- -has been made local, then when the function returns, the previous -destination for -.Cm xtrace -output (as of the time of the -.Ic local -command) will also be restored. -If any of the shell's magic variables -(those which return a value which may vary without -the variable being explicitly altered, -e.g.: -.Dv SECONDS -or -.Dv HOSTNAME ) -are made local in a function, -they will lose their special properties when set -within the function, including by the -.Ic local -command itself -(if not to be set in the function, there is little point -in making a variable local) -but those properties will be restored when the function returns. -.Pp -It is an error to use -.Ic local -outside the scope of a function definition. -When used inside a function, it exits with status 0, -unless an undefined option is used, or an attempt is made to -assign a value to a read-only variable. -.Pp -Note that either -.Fl I -or -.Fl N -should always be used, or variables made local should always -be given a value, or explicitly unset, as the default behavior -(inheriting the earlier value, or starting unset after -.Ic local ) -differs amongst shell implementations. -Using -.Dq Li local \&\- -is an extension not implemented by most shells. -.Pp -See the section -.Sx LINENO -below for details of the effects of making the variable -.Dv LINENO -local. -.\" -.It Ic pwd Op Fl \&LP -Print the current directory. -If -.Fl L -is specified the cached value (initially set from -.Ev PWD ) -is checked to see if it refers to the current directory; if it does -the value is printed. -Otherwise the current directory name is found using -.Xr getcwd 3 . -The environment variable -.Ev PWD -is set to the printed value. -.Pp -The default is -.Ic pwd -.Fl L , -but note that the built-in -.Ic cd -command doesn't support the -.Fl L -option and will cache (almost) the absolute path. -If -.Ic cd -is changed (as unlikely as that is), -.Ic pwd -may be changed to default to -.Ic pwd -.Fl P . -.Pp -If the current directory is renamed and replaced by a symlink to the -same directory, or the initial -.Ev PWD -value followed a symbolic link, then the cached value may not -be the absolute path. -.Pp -The built-in command may differ from the program of the same name because -the program will use -.Ev PWD -and the built-in uses a separately cached value. -.\" -.It Ic read Oo Fl p Ar prompt Oc Oo Fl r Oc Ar variable Op Ar ... -The -.Ar prompt -is printed if the -.Fl p -option is specified and the standard input is a terminal. -Then a line is read from the standard input. -The trailing newline is deleted from the -line and the line is split as described in the field splitting section of the -.Sx Word Expansions -section above, and the pieces are assigned to the variables in order. -If there are more pieces than variables, the remaining pieces -(along with the characters in -.Ev IFS -that separated them) are assigned to the last variable. -If there are more variables than pieces, -the remaining variables are assigned the null string. -The -.Ic read -built-in will indicate success unless EOF is encountered on input, in -which case failure is returned. -.Pp -By default, unless the -.Fl r -option is specified, the backslash -.Dq \e -acts as an escape character, causing the following character to be treated -literally. -If a backslash is followed by a newline, the backslash and the -newline will be deleted. -.\" -.It Ic readonly Ar name Ns Oo =value Oc ... -.It Ic readonly Oo Fl p Oo Ar name ... Oc Oc -.It Ic readonly Fl q Ar name ... -With no options, -the specified names are marked as read only, so that they cannot be -subsequently modified or unset. -The shell allows the value of a variable -to be set at the same time it is marked read only by writing -.Pp -.Dl readonly name=value -.Pp -With no arguments the -.Ic readonly -command lists the names of all set read only variables. -With the -.Fl p -option specified, -the output will be formatted suitably for non-interactive use, -and unset variables are included. -When the -.Fl p -option is given, -a list of variable names (without values) may also be specified, -in which case output is limited to the named variables. -.Pp -With the -.Fl q -option, the -.Ic readonly -command tests the read-only status of the variables listed -and exits with status 0 if all named variables are read-only, -or with status 1 if any are not read-only. -.Pp -Other than as specified for -.Fl q -the -.Ic readonly -command normally exits with status 0. -In all cases, if an unknown option, or an invalid option combination, -or an invalid variable name, is given; -or a variable which was already read-only is attempted to be set; -the exit status will not be zero, a diagnostic -message will be written to the standard error output, -and a non-interactive shell will terminate. -.\" -.It Ic return Op Ar n -Stop executing the current function or a dot command with return value of -.Ar n -or the value of the last executed command, if not specified. -For portability, -.Ar n -should be in the range from 0 to 255. -.Pp -The POSIX standard says that the results of -.Ic return -outside a function or a dot command are unspecified. -This implementation treats such a return as a no-op with a return value of 0 -(success, true). -Use the -.Ic exit -command instead, if you want to return from a script or exit -your shell. -.\" -.It Ic set Oo { Fl options | Cm +options | Cm \-- } Oc Ar arg ... -The -.Ic set -command performs four different functions. -.Pp -With no arguments, it lists the values of all shell variables. -.Pp -With a single option of either -.Dq Fl o -or -.Dq Cm +o -.Ic set -outputs the current values of the options. -In the -.Fl o -form, all options are listed, with their current values. -In the -.Cm +o -form, the shell outputs a string that can later be used -as a command to reset all options to their current values. -.Pp -If options are given, it sets the specified option -flags, or clears them as described in the -.Sx Argument List Processing -section. -In addition to the options listed there, -when the -.Dq "option name" -given to -.Ic set Fl o -is -.Cm default -all of the options are reset to the values they had immediately -after -.Nm -initialization, before any startup scripts, or other input, had been processed. -While this may be of use to users or scripts, its primary purpose -is for use in the output of -.Dq Ic set Cm +o , -to avoid that command needing to list every available option. -There is no -.Cm +o default . -.Pp -The fourth use of the -.Ic set -command is to set the values of the shell's -positional parameters to the specified arguments. -To change the positional -parameters without changing any options, use -.Dq -\|- -as the first argument to -.Ic set . -If no following arguments are present, the -.Ic set -command -will clear all the positional parameters (equivalent to executing -.Dq Li shift $# . ) -Otherwise the following arguments become -.Li \&$1 , -.Li \&$2 , -\&..., -and -.Li \&$# -is set to the number of arguments present. -.\" -.It Ic setvar Ar variable Ar value -Assigns -.Ar value -to -.Ar variable . -(In general it is better to write -.Li variable=value -rather than using -.Ic setvar . -.Ic setvar -is intended to be used in -functions that assign values to variables whose names are passed as -parameters.) -.\" -.It Ic shift Op Ar n -Shift the positional parameters -.Ar n -times. -If -.Ar n -is omitted, 1 is assumed. -Each -.Ic shift -sets the value of -.Li $1 -to the previous value of -.Li $2 , -the value of -.Li $2 -to the previous value of -.Li $3 , -and so on, decreasing -the value of -.Li $# -by one. -The shift count must be less than or equal to the number of -positional parameters ( -.Dq Li $# ) -before the shift. -.\" -.It Ic times -Prints two lines to standard output. -Each line contains two accumulated time values, expressed -in minutes and seconds (including fractions of a second.) -The first value gives the user time consumed, the second the system time. -.Pp -The first output line gives the CPU and system times consumed by the -shell itself. -The second line gives the accumulated times for children of this -shell (and their descendants) which have exited, and then been -successfully waited for by the relevant parent. -See -.Xr times 3 -for more information. -.Pp -.Ic times -has no parameters, and exits with an exit status of 0 unless -an attempt is made to give it an option. -.\" -.It Ic trap Ar action signal ... -.It Ic trap \- -.It Ic trap Op Fl l -.It Ic trap Oo Fl p Oc Ar signal ... -.It Ic trap Ar N signal ... -.Pp -Cause the shell to parse and execute action when any of the specified -signals are received. -The signals are specified by signal number or as the name of the signal. -If -.Ar signal -is -.Li 0 \" $0 -or its equivalent, -.Li EXIT , -the action is executed when the shell exits. -The -.Ar action -may be a null (empty) string, -which causes the specified signals to be ignored. -With -.Ar action -set to -.Sq Li - -the specified signals are set to their default actions. -If the first -.Ar signal -is specified in its numeric form, then -.Ar action -can be omitted to achieve the same effect. -This archaic, -but still standard, -form should not be relied upon, use the explicit -.Sq Li - -action. -If no signals are specified with an action of -.Sq Li - , -all signals are reset. -.Pp -When the shell forks off a sub-shell, it resets trapped (but not ignored) -signals to the default action. -On non-interactive shells, the -.Ic trap -command has no effect on signals that were -ignored on entry to the shell. -On interactive shells, the -.Ic trap -command will catch or reset signals ignored on entry. -.Pp -Issuing -.Ic trap -with option -.Fl l -will print a list of valid signal names. -.Ic trap -without any arguments causes it to write a list of signals and their -associated non-default actions to the standard output in a format -that is suitable as an input to the shell that achieves the same -trapping results. -With the -.Fl p -flag, trap prints the same information for the signals specified, -or if none are given, for all signals, including those where the -action is the default. -These variants of the trap command may be executed in a sub-shell -.Pq "such as in a command substitution" , -provided they appear as the sole, or first, command in that sub-shell, -in which case the state of traps from the parent of that -sub-shell is reported. -.Pp -Examples: -.Pp -.Dl trap -.Pp -List trapped signals and their corresponding actions. -.Pp -.Dl trap -l -.Pp -Print a list of valid signals. -.Pp -.Dl trap '' INT QUIT tstp 30 -.Pp -Ignore signals INT QUIT TSTP USR1. -.Pp -.Dl trap date INT -.Pp -Run the -.Dq date -command (print the date) upon receiving signal INT. -.Pp -.Dl trap HUP INT -.Pp -Run the -.Dq HUP -command, or function, upon receiving signal INT. -.Pp -.Dl trap 1 2 -.Pp -Reset the actions for signals 1 (HUP) and 2 (INT) to their defaults. -.Bd -literal -offset indent -traps=$(trap -p) - # more commands ... -trap 'action' SIG - # more commands ... -eval "$traps" -.Ed -.Pp -Save the trap status, execute commands, changing some traps, -and then reset all traps to their values at the start of the sequence. -The -.Fl p -option is required in the first command here, -or any signals that were previously -untrapped (in their default states) -and which were altered during the intermediate code, -would not be reset by the final -.Ic eval . -.\" -.It Ic type Op Ar name ... -Interpret each -.Ar name -as a command and print the resolution of the command search. -Possible resolutions are: -shell keyword, alias, shell built-in, -command, tracked alias and not found. -For aliases the alias expansion is -printed; for commands and tracked aliases the complete pathname of the -command is printed. -.\" -.It Ic ulimit Oo Fl H Ns \*(Ba Ns Fl S Oc Op Fl a \*(Ba Fl btfdscmlrpnv Op Ar value -Inquire about or set the hard or soft limits on processes or set new -limits. -The choice between hard limit (which no process is allowed to -violate, and which may not be raised once it has been lowered) and soft -limit (which causes processes to be signaled but not necessarily killed, -and which may be raised) is made with these flags: -.Bl -tag -width Fl -.It Fl H -set or inquire about hard limits -.It Fl S -set or inquire about soft limits. -.El -.Pp -If neither -.Fl H -nor -.Fl S -is specified, the soft limit is displayed or both limits are set. -If both are specified, the last one wins. -.Pp -The limit to be interrogated or set, then, is chosen by specifying -any one of these flags: -.Bl -tag -width Fl -.It Fl a -show all the current limits -.It Fl b -the socket buffer size of a process (bytes) -.It Fl c -the largest core dump size that can be produced -(512-byte blocks) -.It Fl d -the data segment size of a process (kilobytes) -.It Fl f -the largest file that can be created -(512-byte blocks) -.It Fl l -how much memory a process can lock with -.Xr mlock 2 -(kilobytes) -.It Fl m -the total physical memory that can be -in use by a process (kilobytes) -.It Fl n -the number of files a process can have open at once -.It Fl p -the number of processes this user can -have at one time -.It Fl r -the number of threads this user can -have at one time -.It Fl s -the stack size of a process (kilobytes) -.It Fl t -CPU time (seconds) -.It Fl v -how large a process address space can be -.El -.Pp -If none of these is specified, it is the limit on file size that is shown -or set. -If value is specified, the limit is set to that number; otherwise -the current limit is displayed. -.Pp -Limits of an arbitrary process can be displayed or set using the -.Xr sysctl 8 -utility. -.It Ic umask Oo Fl S Oc Op Ar mask -Set the value of umask (see -.Xr umask 2 ) -to the specified octal value. -If the argument is omitted, the umask value is printed. -With -.Fl S -a symbolic form is used instead of an octal number. -.It Ic unalias Oo Fl a Oc Op Ar name -If -.Ar name -is specified, the shell removes that alias. -If -.Fl a -is specified, all aliases are removed. -.It Ic unset Oo Fl efvx Oc Ar name ... -If -.Fl v -is specified, the specified variables are unset and unexported. -Readonly variables cannot be unset. -If -.Fl f -is specified, the specified functions are undefined. -If -.Fl e -is given, the specified variables are unexported, but otherwise unchanged, -alternatively, if -.Fl x -is given, the exported status of the variable will be retained, -even after it is unset. -.Pp -If no flags are provided -.Fl v -is assumed. -If -.Fl f -is given with one of the other flags, -then the named variables will be unset, or unexported, and functions -of the same names will be undefined. -The -.Fl e -and -.Fl x -flags both imply -.Fl v . -If -.Fl e -is given, the -.Fl x -flag is ignored. -.Pp -The exit status is 0, unless an attempt was made to unset -a readonly variable, in which case the exit status is 1. -It is not an error to unset (or undefine) a variable (or function) -that is not currently set (or defined.) -.\" -.It Ic wait Oo Fl n Oc Oo Fl p Ar var Oc Op Ar job ... -Wait for the specified jobs to complete -and return the exit status of the last job in the parameter list, -or 127 if that job is not a current child of the shell. -.Pp -If no -.Ar job -arguments are given, wait for all jobs to -complete and then return an exit status of zero -(including when there were no jobs, and so nothing exited.) -.Pp -With the -.Fl n -option, wait instead for any one of the given -.Ar job Ns s, -or if none are given, any job, to complete, and -return the exit status of that job. -If none of the given -.Ar job -arguments is a current child of the shell, -or if no -.Ar job -arguments are given and the shell has no unwaited for children, -then the exit status will be 127. -.Pp -The -.Fl p Ar var -option allows the process (or job) identifier of the -job for which the exit status is returned to be obtained. -The variable named (which must not be readonly) will be -unset initially, then if a job has exited and its status is -being returned, set to the identifier from the -arg list (if given) of that job, -or the lead process identifier of the job to exit when used with -.Fl n -and no job arguments. -Note that -.Fl p -with neither -.Fl n -nor -.Ar job -arguments is useless, as in that case no job status is -returned, the variable named is simply unset. -.Pp -If the wait is interrupted by a signal, -its exit status will be greater than 128, -and -.Ar var , -if given, will remain unset. -.Pp -Once waited upon, by specific process number or job-id, -or by a -.Ic wait -with no arguments, -knowledge of the child is removed from the system, -and it cannot be waited upon again. -.Pp -Note than when a list of jobs are given, more that -one argument might refer to the same job. -In that case, if the final argument represents a job -that is also given earlier in the list, it is not -defined whether the status returned will be the -exit status of the job, or 127 indicating that -the child no longer existed when the wait command -reached the later argument in the list. -In this -.Nm -the exit status will be that from the job. -.Nm -waits for each job exactly once, regardless of -how many times (or how many different ways) it -is listed in the arguments to -.Ic wait . -That is -.Bd -literal -offset indent -compact -wait 100 100 100 -.Ed -is identical to -.Bd -literal -offset indent -compact -wait 100 -.Ed -.El -.\" -.\" -.Ss Job Control -.\" -Each process (or set of processes) started by -.Nm -is created as a -.Dq job -and added to the jobs table. -When enabled by the -.Fl m -option -.Pq aka Fl o Cm monitor -when the job is created, -.Nm -places each job (if run from the top level shell) -into a process group of its own, which allows control -of the process(es), and its/their descendants, as a unit. -When the -.Fl m -option is off, or when started from a sub-shell environment, -jobs share the same process group as the parent shell. -The -.Fl m -option is enabled by default in interactive shells with -a terminal as standard input and standard error. -.Pp -Jobs with separate process groups may be stopped, and then later -resumed in the foreground (with access to the terminal) -or in the background (where attempting to read from the -terminal will result in the job stopping.) -A list of current jobs can be obtained using the -.Ic jobs -built-in command. -Jobs are identified using either the process identifier -of the lead process of the job (the value available in -the special parameter -.Dq Dv \&! -if the job is started in the background), or using percent -notation. -Each job is given a -.Dq job number -which is a small integer, starting from 1, and can be -referenced as -.Dq Li \&% Ns Ar n -where -.Ar n -is that number. -Note that this applies to jobs both with and without their own process groups. -Job numbers are shown in the output from the -.Ic jobs -command enclosed in brackets -.Po -.Sq Li \&[ -and -.Sq Li \&] -.Pc . -Whenever the job table becomes empty, the numbers begin at one again. -In addition, there is the concept of a current, and a previous job, -identified by -.Dq Li \&%+ -.Po -or -.Dq Li \&%% -or even just -.Dq Li \&% -.Pc , -and a previous job, identified by -.Dq Li \&%\- . -Whenever a background job is started, -or a job is resumed in the background, -it becomes the current job. -The job that was the current job -(prepare for a big surprise here, drum roll..., wait for it...\&) -becomes the previous job. -When the current job terminates, the previous job is -promoted to be the current job. -In addition the form -.Dq Li \&% Ns Ar string\^ -finds the job for which the command starts with -.Ar string -and the form -.Dq Li \&%? Ns Ar string\^ -finds the job which contains the -.Ar string -in its command somewhere. -Both forms require the result to be unambiguous. -For this purpose the -.Dq command -is that shown in the output from the -.Ic jobs -command, not the original command line. -.Pp -The -.Ic bg , -.Ic fg , -.Ic jobid , -.Ic jobs , -.Ic kill , -and -.Ic wait -commands all accept job identifiers as arguments, in addition to -process identifiers (larger integers). -See the -.Sx Built-ins -section above, and -.Xr kill 1 , -for more details of those commands. -In addition, a job identifier -(using one of the -.Dq \&% forms ) -issued as a command, without arguments, is interpreted as -if it had been given as the argument to the -.Ic fg -command. -.Pp -To cause a foreground process to stop, enter the terminal's -.Ic stop -character (usually control-Z). -To cause a background process to stop, send it a -.Dv STOP -signal, using the kill command. -A useful function to define is -.Bd -literal -offset indent -stop() { kill -s STOP "${@:-%%}"; } -.Ed -.Pp -The -.Ic fg -command resumes a stopped job, placing it in the foreground, -and -.Ic bg -resumes a stopped job in the background. -The -.Ic jobid -command provides information about process identifiers, job identifiers, -and the process group identifier, for a job. -.Pp -Whenever a sub-shell is created, the jobs table becomes invalid -(the sub-shell has no children.) -However, to enable uses like -.Bd -literal -offset indent -PID=$(jobid -p %1) -.Ed -.Pp -the table is only actually cleared in a sub-shell when needed to -create the first job there (built-in commands run in the foreground -do not create jobs.) -Note that in this environment, there is no useful current job -.Dq ( Li \&%% -actually refers to the sub-shell itself, but is not accessible) -but the job which is the current job in the parent can be accessed as -.Dq Li \&%\- . -.\" -.\" -.Ss Command Line Editing -.\" -When -.Nm -is being used interactively from a terminal, the current command -and the command history (see -.Ic fc -in the -.Sx Built-ins -section) -can be edited using emacs-mode or vi-mode command-line editing. -The command -.Ql set -o emacs -(or -.Fl E -option) -enables emacs-mode editing. -The command -.Ql set -o vi -(or -.Fl V -option) -enables vi-mode editing and places the current shell process into -vi insert mode. -(See the -.Sx Argument List Processing -section above.) -.Pp -The vi-mode uses commands similar to a subset of those described in the -.Xr vi 1 -man page. -With vi-mode -enabled, -.Nm sh -can be switched between insert mode and command mode. -It's similar to -.Ic vi : -pressing the -.Aq ESC -key will throw you into vi command mode. -Pressing the -.Aq return -key while in command mode will pass the line to the shell. -.Pp -The emacs-mode uses commands similar to a subset available in the -.Ic emacs -editor. -With emacs-mode enabled, special keys can be used to modify the text -in the buffer using the control key. -.Pp -.Nm -uses the -.Xr editline 3 -library. -See -.Xr editline 7 -for a list of the possible command bindings, -and the default settings in emacs and vi modes. -Also see -.Xr editrc 5 -for the commands that can be given to configure -.Xr editline 7 -in the file named by the -.Ev EDITRC -parameter, -or a file used with the -.Ic inputrc -built-in command, -or using -.Xr editline 7 Ap s -configuration command line. -.Pp -When command line editing is enabled, the -.Xr editline 7 -functions control printing of the -.Ev PS1 -and -.Ev PS2 -prompts when required. -As, in this mode, the command line editor needs to -keep track of what characters are in what position on -the command line, care needs to be taken when setting -the prompts. -Normal printing characters are handled automatically, -however mode setting sequences, which do not actually display -on the terminal, need to be identified to -.Xr editline 7 . -This is done, when needed, by choosing a character that -is not needed anywhere in the prompt, including in the mode -setting sequences, any single character is acceptable, -and assigning it to the shell parameter -.Dv PSlit . -Then that character should be used, in pairs, in the -prompt string. -Between each pair of -.Dv PSlit -characters are mode setting sequences, which affect the printing -attributes of the following (normal) characters of the prompt, -but do not themselves appear visibly, nor change the terminal's -cursor position. -.Pp -Each such sequence, that is -.Dv PSlit -character, mode setting character sequence, and another -.Dv PSlit -character, must currently be followed by at least one following -normal prompt character, or it will be ignored. -That is, a -.Dv PSlit -character cannot be the final character of -.Ev PS1 -or -.Ev PS2 , -nor may two -.Dv PSlit -delimited sequences appear adjacent to each other. -Each sequence can contain as many mode altering sequences as are -required however. -Only the first character from -.Dv PSlit -will be used. -When set -.Dv PSlit -should usually be set to a string containing just one -character, then it can simply be embedded in -.Ev PS1 -(or -.Ev PS2 ) -as in -.Pp -.D1 Li PS1=\*q${PSlit} Ns Ar mset\^ Ns Li ${PSlit}XYZ${PSlit} Ns Ar mclr\^ Ns Li ${PSlit}ABC\*q -.Pp -The prompt visible will be -.Dq XYZABC -with the -.Dq XYZ -part shown according as defined by the mode setting characters -.Ar mset , -and then cleared again by -.Ar mclr . -See -.Xr tput 1 -for one method to generate appropriate mode sequences. -Note that both parts, XYZ and ABC, must each contain at least one -character. -.Pp -If -.Dv PSlit -is unset, which is its initial state, or set to a null string, -no literal character will be defined, -and all characters of the prompt strings will be assumed -to be visible characters (which includes spaces etc.) -To allow smooth use of prompts, without needing redefinition, when -.Xr editline 7 -is disabled, the character chosen should be one which will be -ignored by the terminal if received, as when -.Xr editline 7 -is not in use, the prompt strings are simply written to the terminal. -For example, setting: -.\" XXX: PS1 line is too long for -offset indent -.Bd -literal -offset left - PSlit="$(printf\ '\e1')" - PS1="${PSlit}$(tput\ bold\ blink)${PSlit}\e$${PSlit}$(tput\ sgr0)${PSlit}\ " -.Ed -.Pp -will arrange for the primary prompt to be a bold blinking dollar sign, -if supported by the current terminal, followed by an (ordinary) space, -and, as the SOH (control-A) character -.Pq Sq \e1 -will not normally affect -a terminal, this same prompt will usually work with -.Xr editline 7 -enabled or disabled. -.Sh ENVIRONMENT -.Bl -tag -width MAILCHECK -.It Ev CDPATH -The search path used with the -.Ic cd -built-in. -.It Ev EDITRC -Gives the name of the file containing commands for -.Xr editline 7 . -See -.Xr editrc 5 -for possible content and format. -The file is processed, when in interactive mode with -command line editing enabled, whenever -.Ev EDITRC -is set (even with no actual value change,) -and if command line editing changes from disabled to enabled, -or the editor style used is changed. -(See the -.Fl E -and -.Fl V -options of the -.Ic set -built-in command, described in -.Sx Built-ins -above, which are documented further above in -.Sx Argument List Processing . ) -If unset -.Dq $HOME/.editrc -is used. -.It Ev ENV -Names the file sourced at startup by the shell. -Unused by this shell after initialization, -but is usually passed through the environment to -descendant shells. -.It Ev EUSER -Set to the login name of the effective user id running the shell, -as returned by -.Bd -compact -literal -offset indent -getpwuid(geteuid())->pw_name -.Ed -.Po -See -.Xr getpwuid 3 -and -.Xr geteuid 2 -for more details. -.Pc -This is obtained each time -.Ev EUSER -is expanded, so changes to the shell's execution identity -cause updates without further action. -If unset, it returns nothing. -If set it loses its special properties, and is simply a variable. -.It Ev HISTSIZE -The number of lines in the history buffer for the shell. -.It Ev HOME -Set automatically by -.Xr login 1 -from the user's login directory in the password file -.Pq Xr passwd 5 . -This environment variable also functions as the default argument for the -.Ic cd -built-in. -.It Ev HOSTNAME -Set to the current hostname of the system, as returned by -.Xr gethostname 3 . -This is obtained each time -.Ev HOSTNAME -is expanded, so changes to the system's name are reflected -without further action. -If unset, it returns nothing. -If set it loses its special properties, and is simply a variable. -.It Ev IFS -Input Field Separators. -This is normally set to -.Aq space , -.Aq tab , -and -.Aq newline . -See the -.Sx White Space Splitting -section for more details. -.It Ev LANG -The string used to specify localization information that allows users -to work with different culture-specific and language conventions. -See -.Xr nls 7 . -.It Dv LINENO -The current line number in the script or function. -See the section -.Sx LINENO -below for more details. -.It Ev MAIL -The name of a mail file, that will be checked for the arrival of new mail. -Overridden by -.Ev MAILPATH . -The check occurs just before -.Ev PS1 -is written, immediately after reporting jobs which have changed status, -in interactive shells only. -New mail is considered to have arrived if the monitored file -has increased in size since the last check. -.\" .It Ev MAILCHECK -.\" The frequency in seconds that the shell checks for the arrival of mail -.\" in the files specified by the -.\" .Ev MAILPATH -.\" or the -.\" .Ev MAIL -.\" file. -.\" If set to 0, the check will occur at each prompt. -.It Ev MAILPATH -A colon -.Dq \&: -separated list of file names, for the shell to check for incoming mail. -This environment setting overrides the -.Ev MAIL -setting. -There is a maximum of 10 mailboxes that can be monitored at once. -.It Ev PATH -The default search path for executables. -See the -.Sx Path Search -section above. -.It Ev POSIXLY_CORRECT -If set in the environment upon initialization of the shell, -then the shell option -.Ic posix -will be set. -.Po -See the description of the -.Ic set -command in the -.Sx Built-ins -section. -.Pc -After initialization it is unused by the shell, -but is usually passed through the environment to -descendant processes, including other instances of the shell, -which may interpret it in a similar way. -.It Ev PPID -The process identified of the parent process of the -current shell. -This value is set at shell startup, ignoring -any value in the environment, and then made readonly. -.It Ev PS1 -The primary prompt string, which defaults to -.Dq Li "$ " , -unless you are the superuser, in which case it defaults to -.Dq Li "# " . -This string is subject to parameter, arithmetic, and if -enabled by setting the -.Ic promptcmds -option, command substitution before being output. -During execution of commands used by command substitution, -execution tracing, the -.Ic xtrace -.Ic ( set Fl x ) -option is temporarily disabled. -If -.Ic promptcmds -is not set and the prompt string uses command substitution, -the prompt used will be an appropriate error string. -For other expansion errors, a message will be output, -and the unexpanded string will then be used as the prompt. -.It Ev PS2 -The secondary prompt string, which defaults to -.Dq Li "> " . -After expansion (as for -.Ev PS1 ) -it is written whenever more input is required to complete the -current command. -.It Ev PS4 -Output, after expansion like -.Ev PS1 , -before each line when execution trace -.Ic ( set Fl x ) -is enabled. -.Ev PS4 -defaults to -.Dq Li "+ " . -.It Ev PSc -Initialized by the shell, ignoring any value from the environment, -to a single character string, either -.Sq \&# -or -.Sq \&$ , -depending upon whether the current user is the superuser or not. -This is intended for use when building a custom -.Ev PS1 . -.It Ev PSlit -Defines the character which may be embedded in pairs, in -.Ev PS1 -or -.Ev PS2 -to indicate to -.Xr editline 7 -that the characters between each pair of occurrences of the -.Dv PSlit -character will not appear in the visible prompt, and will not -cause the terminal's cursor to change position, but rather set terminal -attributes for the following prompt character(s) at least one of -which must be present. -See -.Sx Command Line Editing -above for more information. -.It Ev RANDOM -Returns a different pseudo-random integer, -in the range [0,32767] each time it is accessed. -.Ev RANDOM -can be assigned an integer value to seed the PRNG. -If the value assigned is a constant, then the -sequence of values produces on subsequent references of -.Ev RANDOM -will repeat after the next time the same constant is assigned. -Note, this is not guaranteed to remain constant from one version -of the shell to another \(en the PRNG algorithm, or seeding -method is subject to change. -If -.Ev RANDOM -is assigned an empty value (null string) then the next time -.Ev RANDOM -is accessed, it will be seeded from a more genuinely random source. -The sequence of pseudo-random numbers generated will not be able to -be generated again (except by luck, whether good or bad, depends!) -This is also how the initial seed is generated, if none has been -assigned before -.Ev RANDOM -is first accessed after shell initialization. -Should the error message -.Dq "RANDOM initialisation failed" -appear on standard error, it indicates that the source -of good random numbers was not available, and -.Ev RANDOM -has instead been seeded with a more predictable value. -The following sequence of random numbers will -not be as unpredictable as they otherwise would be. -.It Ev SECONDS -Returns the number of seconds since the current shell was started. -If unset, it remains unset, and returns nothing, unless set again. -If set, it loses its special properties, and becomes a normal variable. -.It Ev START_TIME -Initialized by the shell to the number of seconds since the Epoch -(see -.Xr localtime 3 ) -when the shell was started. -The value of -.Dl $(( Ns Ev START_TIME + Ev SECONDS Ns )) -represents the current time, if -.Ev START_TIME -has not been modified, and -.Ev SECONDS -has not been set or unset. -.It Ev TERM -The default terminal setting for the shell. -This is inherited by -children of the shell, and is used in the history editing modes. -.\" This is explicitly last, not in sort order - please leave! -.It Ev ToD -When referenced, uses the value of -.Ev ToD_FORMAT -(or -.Dq \&%T -if -.Ev ToD_FORMAT -is unset) as the format argument to -.Xr strftime 3 -to encode the current time of day, in the time zone -defined by -.Ev TZ -if set, or current local time if not, and returns the result. -If unset -.Ev ToD -returns nothing. -If set, it loses its special properties, and becomes a normal variable. -.It Ev ToD_FORMAT -Can be set to the -.Xr strftime 3 -format string to be used when expanding -.Ev ToD . -Initially unset. -.It Ev TZ -If set, gives the time zone -(see -.Xr localtime 3 , -.Xr environ 7 ) -to use when formatting -.Ev ToD -and if exported, other utilities that deal with times. -If unset, the system's local wall clock time zone is used. -.It Ev NETBSD_SHELL -Unlike the variables previously mentioned, -this variable is somewhat strange, -in that it cannot be set, -inherited from the environment, -modified, or exported from the shell. -If set, by the shell, it indicates that the shell is the -.Ic sh -defined by this manual page, and gives its version information. -It can also give information in additional space separated words, -after the version string. -If the shell was built as part of a reproducible build, -the relevant date that was used for that build will be included. -Finally, any non-standard compilation options, -which may affect features available, -that were used when building the shell will be listed. -.Ev NETBSD_SHELL -behaves like any other variable that has the read-only -and un-exportable attributes set. -.El -.Ss Dv LINENO -.Dv LINENO -is in many respects a normal shell variable, containing an -integer value. and can be expanded using any of the forms -mentioned above which can be used for any other variable. -.Pp -.Dv LINENO -can be exported, made readonly, or unset, as with any other -variable, with similar effects. -Note that while being readonly prevents later attempts to -set, or unset, -.Dv LINENO , -it does not prevent its value changing. -References to -.Dv LINENO -.Pq "when not unset" -always obtain the current line number. -However, -.Dv LINENO -should normally not ever be set or unset. -In this shell setting -.Dv LINENO -reverses the effect of an earlier -.Ic unset , -but does not otherwise affect the value obtained. -If unset, -.Dv LINENO -should not normally be set again, doing so is not portable. -If -.Dv LINENO -is set or unset, different shells act differently. -The value of -.Dv LINENO -is never imported from the environment when the shell is -started, though if present there, as with any other variable, -.Dv LINENO -will be exported by this shell. -.Pp -.Dv LINENO -is set automatically by the shell to be the number of the source -line on which it occurs. -When exported, -.Dv LINENO -is exported with its value set to the line number it would have -had had it been referenced on the command line of the command to -which it is exported. -Line numbers are counted from 1, which is the first line the shell -reads from any particular file. -For this shell, standard input, including in an interactive shell, -the user's terminal, is just another file and lines are counted -there as well. -However note that not all shells count interactive -lines this way, it is not wise to rely upon -.Dv LINENO -having a useful value, except in a script, or a function. -.Pp -The role of -.Dv LINENO -in functions is less clear. -In some shells, -.Dv LINENO -continues to refer to the line number in the script which defines -the function, -in others lines count from one within the function, always (and -resume counting normally once the function definition is complete) -and others count in functions from one if the function is defined -interactively, but otherwise just reference the line number in the -script in which the function is defined. -This shell gives the user the option to choose. -If the -.Fl L -flag (the -.Ic local_lineno -option, see -.Sx Argument List Processing ) -is set, when the function is defined, then the function -defaults to counting lines with one being the first line of the -function. -When the -.Fl L -flag is not set, the shell counts lines in a function definition -in the same continuous sequence as the lines that surround the -function definition. -Further, if -.Dv LINENO -is made local -(see -.Sx Built-ins -above) -inside the function, the function can decide which -behavior it prefers. -If -.Dv LINENO -is made local and inherited, and not given a value, as in -.Dl local Fl I Dv LINENO -then from that point in the function, -.Dv LINENO -will give the line number as if lines are counted in sequence -with the lines that surround the function definition (and -any other function definitions in which this is nested.) -If -.Dv LINENO -is made local, and in that same command, given a value, as -.Dl local Oo Fl I Ns | Ns Fl N Oc Dv LINENO Ns = Ns Ar value -then -.Dv LINENO -will give the line number as if lines are counted from one -from the beginning of the function. -The value nominally assigned in this case is irrelevant, and ignored. -For completeness, if lineno is made local and unset, as in -.Dl local Fl N Dv LINENO -then -.Dv LINENO -is simply unset inside the function, and gives no value at all. -.Pp -Now for some technical details. -The line on which -.Dv LINENO -occurs in a parameter expansion, is the line that contains the -.Sq \&$ -that begins the expansion of -.Dv LINENO . -In the case of nested expansions, that -.Sq \&$ -is the one that actually has -.Dv LINENO -as its parameter. -In an arithmetic expansion, where no -.Sq \&$ -is used to evaluate -.Dv LINENO -but -.Dv LINENO -is simply referenced as a variable, then the value is the -line number of the line that contains the -.Sq L -of -.Dv LINENO . -For functions line one of the function definition (when relevant) -is the line that contains the first character of the -function name in the definition. -When exported, the line number of the command is the line number -where the first character of the word which becomes the command name occurs. -.Pp -When the shell opens a new file, for any reason, -it counts lines from one in that file, -and then resumes its original counting once it resumes reading the -previous input stream. -When handling a string passed to -.Ic eval -the line number starts at the line on which the string starts, -and then if the string contains internal newline characters, -those characters increase the line number. -This means that references to -.Dv LINENO -in such a case can produce values larger than would be -produced by a reference on the line after the -.Ic eval . -.Sh FILES -.Bl -item -.It -.Pa $HOME/.profile -.It -.Pa /etc/profile -.El -.Sh EXIT STATUS -Errors that are detected by the shell, such as a syntax error, will cause the -shell to exit with a non-zero exit status. -If the shell is not an -interactive shell, the execution of the shell file will be aborted. -Otherwise -the shell will return the exit status of the last command executed, or -if the exit built-in is used with a numeric argument, it will return the -argument. -.Sh SEE ALSO -.Xr csh 1 , -.Xr echo 1 , -.Xr getopt 1 , -.Xr ksh 1 , -.Xr login 1 , -.Xr printf 1 , -.Xr test 1 , -.Xr editline 3 , -.Xr getopt 3 , -.\" .Xr profile 4 , -.Xr editrc 5 , -.Xr passwd 5 , -.Xr editline 7 , -.Xr environ 7 , -.Xr nls 7 , -.Xr sysctl 8 -.Sh HISTORY -A -.Nm -command appeared in -.At v1 . -It was replaced in -.At v7 -with a version that introduced the basis of the current syntax. -That was, however, unmaintainable so we wrote this one. -.Sh BUGS -Setuid shell scripts should be avoided at all costs, as they are a -significant security risk. -.Pp -The characters generated by filename completion should probably be quoted -to ensure that the filename is still valid after the input line has been -processed. -.Pp -Job control of compound statements (loops, etc) is a complete mess. -.Pp -Many, many, more. -(But less than there were...) |