From 10185af4bc5de5a5ac280e5c44a9eff96a10d800 Mon Sep 17 00:00:00 2001 From: Peter Avalos Date: Sun, 14 Jan 2007 16:30:20 +0000 Subject: [PATCH] Mechanically kill hard sentence breaks. Fix references to non-existing or obsoleted man pages. Use ``.Pq Ql'' to quote single characters, instead of ``.Pq Li''. This makes the resulting output more aesthetically pleasing in text-only terminals. mdoc cleanups. Add missed '.'. Document that '#' starts a comment. o Discuss the ways to escape an alias. o Fix the alias syntax lines. o Refer to the Aliases subsection. Document that `in word ...' is optional in the for command. Document the "return" built-in better: it will exit . (sources) and the top-level shell instance, too. When listing the special $ variables, ($!, $#, etc) list them as $! instead of just !, this allows one to more easily locate/understand the section of the manpage in question. Document the -L and -P options to the cd and pwd commands as being mutually exclusive. Document command -v and -V. Split the export synopsis into two lines as -p cannot be mixed with variable names. Document the fact that 'true' and 'false' are among sh(1) built-in commands. - Move the description of the ``-c string'' option closer to the option itself. - Add an ENVIRONMENT section (1) - Add more .Xr cross references to the SEE ALSO section. Add `local' and `return' to the list of built-ins. Document that read -t timeout returns 1 if the timeout elapses. Make it easier to find that we have test(1) built-in in sh(1). - Document trap's -l option and the behaviour of a missing action or a single dash. - Discourage the omission of the action. Document umask's -S option. Tell more of the sh(1) history. Acknowledge Kenneth Almquist's contribution in AUTHORS. Document missing multibyte character handling in utilities specified by POSIX. Obtained-from: FreeBSD --- bin/sh/sh.1 | 629 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 466 insertions(+), 163 deletions(-) diff --git a/bin/sh/sh.1 b/bin/sh/sh.1 index 6449bfdf08..04082fa86e 100644 --- a/bin/sh/sh.1 +++ b/bin/sh/sh.1 @@ -1,3 +1,4 @@ +.\"- .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -33,10 +34,10 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)sh.1 8.6 (Berkeley) 5/4/95 -.\" $FreeBSD: src/bin/sh/sh.1,v 1.39.2.25 2003/02/13 19:28:08 fanf Exp $ -.\" $DragonFly: src/bin/sh/sh.1,v 1.7 2007/01/13 20:33:47 pavalos Exp $ +.\" $FreeBSD: src/bin/sh/sh.1,v 1.124 2006/10/07 16:51:16 stefanf Exp $ +.\" $DragonFly: src/bin/sh/sh.1,v 1.8 2007/01/14 16:30:20 pavalos Exp $ .\" -.Dd December 4, 2005 +.Dd October 7, 2006 .Dt SH 1 .Os .Sh NAME @@ -57,11 +58,11 @@ The current version of is in the process of being changed to conform with the .St -p1003.2 -specification for the shell. This version has many features which make +specification 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 like -.Xr pdksh 1 . +shell clone like pdksh. Only features designated by POSIX, plus a few Berkeley extensions, are being incorporated into this shell. @@ -79,10 +80,12 @@ 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 +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 +use (shell scripts). +That is, commands can be typed directly to the running shell or can be put into a file, which can be executed directly by the shell. .Ss Invocation @@ -94,20 +97,23 @@ is connected to a terminal (or if the .Fl i option is set), -the shell is considered an interactive shell. An interactive shell +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 -.Pq Li - , +.Pq Ql - , 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 +when the user first logs in. +A login shell first reads commands from the files .Pa /etc/profile and then .Pa .profile -if they exist. If the environment variable +if they exist. +If the environment variable .Ev ENV is set on entry to a shell, or is set in the .Pa .profile @@ -134,14 +140,16 @@ The first non-option argument specified on the command line will be treated as the name of a file from which to read commands (a shell script), and the remaining arguments are set as the positional parameters -of the shell ($1, $2, etc). Otherwise, the shell reads commands +of the shell ($1, $2, etc). +Otherwise, the shell reads commands from its standard input. .Pp Unlike older versions of .Nm the .Ev ENV -script is only sourced on invocation of interactive shells. This +script is only sourced on invocation of interactive shells. +This closes a well-known, and sometimes easily exploitable security hole related to poorly thought out .Ev ENV @@ -169,15 +177,15 @@ built-in command (described later in the section called .Sx Built-in Commands ) . Introducing an option with a dash -.Pq Li - +.Pq Ql - enables the option, while using a plus -.Pq Li + +.Pq Ql + disables the option. A .Dq Li -- or plain -.Dq Li - +.Dq Ql - will stop option processing and will force the remaining words on the command line to be treated as arguments. The @@ -206,7 +214,11 @@ option if it has been set). Exit immediately if any untested command fails in non-interactive mode. The exit status of a command is considered to be explicitly tested if the command is part of the list used to control -an if, elif, while, or until; if the command is the left +an +.Ic if , elif , while , +or +.Ic until ; +if the command is the left hand operand of an .Dq Li && or @@ -229,7 +241,8 @@ Force the shell to behave interactively. Turn on job control (set automatically when interactive). .It Fl n Li noexec If not interactive, read commands but do not -execute them. This is useful for checking the +execute them. +This is useful for checking the syntax of shell scripts. .It Fl P Li physical Change the default for the @@ -243,9 +256,11 @@ to .Fl P (physical directory layout). .It Fl p Li privileged -Turn on privileged mode. This mode is enabled on startup +Turn on privileged mode. +This mode is enabled on startup if either the effective user or group id is not equal to the -real user or group id. Turning this mode off sets the +real user or group id. +Turning this mode off sets the effective user and group ids to the real user and group ids. When this mode is enabled for interactive shells, the file .Pa /etc/suid_profile @@ -258,9 +273,10 @@ is sourced, and the contents of the variable are ignored. .It Fl s Li stdin Read commands from standard input (set automatically -if no file arguments are present). This option has +if no file arguments are present). +This option has no effect when set after the shell has already started -running (i.e. when set with the +running (i.e., when set with the .Ic set command). .It Fl T Li trapsasync @@ -268,9 +284,10 @@ When waiting for a child, execute traps immediately. If this option is not set, traps are executed after the child exits, as specified in -.St -p1003.2 +.St -p1003.2 . This nonstandard option is useful for putting guarding shells around -children that block signals. The surrounding shell may kill the child +children that block signals. +The surrounding shell may kill the child or it may just return control to the tty and leave the child alone, like this: .Bd -literal -offset indent @@ -289,7 +306,8 @@ command line editor (disables if it has been set). .It Fl v Li verbose The shell writes its input to standard error -as it is read. Useful for debugging. +as it is read. +Useful for debugging. .It Fl x Li xtrace Write each command (preceded by the value of the @@ -301,8 +319,9 @@ Useful for debugging. .Pp The .Fl c -option may be used to pass its string argument to the shell -to be interpreted as input. +option causes the commands to be read from the +.Ar string +operand instead of from the standard input. Keep in mind that this option only accepts a single string as its argument, hence multi-word strings must be quoted. .Pp @@ -349,10 +368,19 @@ The following is a list of valid operators: .It Li <& Ta Li >& Ta Li <<- Ta Li >| .El .El +.Pp +The character +.Ql # +introduces a comment if used at the beginning of a word. +The word starting with +.Ql # +and the rest of the line are ignored. .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 three types of quoting: matched single quotes, +or words to the shell, such as operators, whitespace, keywords, +or alias names. +.Pp +There are three types of quoting: matched single quotes, matched double quotes, and backslash. .Bl -tag -width indent .It Single Quotes @@ -362,11 +390,11 @@ it impossible to put single-quotes in a single-quoted string). .It Double Quotes Enclosing characters within double quotes preserves the literal meaning of all characters except dollarsign -.Pq Li $ , +.Pq Ql $ , backquote -.Pq Li ` , +.Pq Ql ` , and backslash -.Pq Li \e . +.Pq Ql \e . The backslash inside double quotes is historically weird. It remains literal unless it precedes the following characters, which it serves to quote: @@ -376,13 +404,14 @@ which it serves to quote: .It Backslash A backslash preserves the literal meaning of the following character, with the exception of the newline character -.Pq Li \en . +.Pq Ql \en . A backslash preceding a newline is treated as a line continuation. .El .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: +after a control operator. +The following are reserved words: .Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center .It Li \&! Ta { Ta } Ta Ic case Ta Ic do .It Ic done Ta Ic elif Ta Ic else Ta Ic esac Ta Ic fi @@ -391,7 +420,8 @@ after a control operator. The following are reserved words: .Ss Aliases An alias is a name and corresponding value set using the .Ic alias -built-in command. Whenever a reserved word may occur (see above), +built-in command. +Whenever a reserved word may occur (see above), 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. @@ -411,17 +441,31 @@ ls -F foobar .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 discouraged. +to create functions with arguments. +They can also be +used to create lexically obscure code. +This use is discouraged. +.Pp +An alias name may be escaped in a command line, so that it is not +replaced by its alias value, by using quoting characters within or +adjacent to the alias name. +This is most often done by prefixing +an alias name with a backslash to execute a function, built-in, or +normal program with the same name. +See the +.Sx Quoting +subsection. .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 .St -p1003.2 -document). Essentially though, a line is read and if +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 +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 @@ -431,7 +475,8 @@ the following actions: Leading words of the form .Dq Li name=value are stripped off and assigned to the environment of -the simple command. Redirection operators and +the simple command. +Redirection operators and their arguments (as described below) are stripped off and saved for processing. .It @@ -439,7 +484,8 @@ The remaining words are expanded as described in the section called .Sx Word Expansions , and the first remaining word is considered the command -name and the command is located. The remaining +name and the command is located. +The remaining words are considered the arguments of the command. If no command name resulted, then the .Dq Li name=value @@ -451,8 +497,10 @@ 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 +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 [n] redir-op file @@ -460,7 +508,8 @@ used for redirection is: The .Ql redir-op is one of the redirection operators mentioned -previously. The following gives some examples of how these +previously. +The following gives some examples of how these operators can be used. Note that stdin and stdout are commonly used abbreviations for standard input and standard output respectively. @@ -498,7 +547,8 @@ delimiter .Pp All the text on successive lines up to the delimiter is saved away and made available to the command on standard -input, or file descriptor n if it is specified. If the delimiter +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 subjected to parameter expansion, command substitution, and arithmetic @@ -537,7 +587,7 @@ 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 -(i.e. if it does not begin with the +(i.e., if it does not begin with the .Qq magic number whose .Tn ASCII @@ -561,8 +611,10 @@ as a .Qq 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, +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 @@ -571,10 +623,12 @@ performing any searches. .It The shell searches each entry in .Ev PATH -in turn for the command. The value of the +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 +entries separated by colons. +Each entry consists of a directory name. The current directory may be indicated implicitly by an empty directory name, @@ -582,20 +636,24 @@ or explicitly by a single period. .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 +of other shell commands. +The paradigm is that a command exits with zero for normal or success, and non-zero for failure, -error, or a false indication. The man page for each command +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 is terminated by a signal, its exit status is 128 plus -the signal number. Signal numbers are defined in the header file +the signal number. +Signal numbers are defined in the header file .In sys/signal.h . .Ss Complex Commands Complex commands are combinations of simple commands with control operators or reserved words, together creating a larger complex -command. More generally, a command is one of the following: +command. +More generally, a command is one of the following: .Bl -item -offset indent .It simple command @@ -613,9 +671,11 @@ Unless otherwise stated, the exit status of a command is that of the last simple command executed by the command. .Ss Pipelines A pipeline is a sequence of one or more commands separated -by the control operator |. The standard output of all but +by the control operator |. +The standard output of all but the last command is connected to the standard input -of the next command. The standard output of the last +of the next command. +The standard output of the last command is inherited from the shell, as usual. .Pp The format for a pipeline is: @@ -623,7 +683,8 @@ The format for a pipeline is: .Dl [!] command1 [ | command2 ...] .Pp The standard output of command1 is connected to the standard -input of command2. The standard input, standard output, or +input of command2. +The standard input, standard output, or both of a command is considered to be assigned by the pipeline before any redirection specified by redirection operators that are part of the command. @@ -631,17 +692,22 @@ operators that are part of the command. If the pipeline is not in the background (discussed later), the shell waits for all commands to complete. .Pp -If the reserved word ! does not precede the pipeline, the +If the reserved word +.Ic !\& +does not precede the pipeline, the exit status is the exit status of the last command specified -in the pipeline. Otherwise, the exit status is the logical -NOT of the exit status of the last command. That is, if +in the pipeline. +Otherwise, the exit status is the logical +NOT of the exit status of the last command. +That is, if the last command returns zero, the exit status is 1; if the last command returns greater than zero, the exit status is zero. .Pp Because pipeline assignment of standard input or standard output or both takes place before redirection, it can be -modified by redirection. For example: +modified by redirection. +For example: .Pp .Dl $ command1 2>&1 | command2 .Pp @@ -671,7 +737,7 @@ They are executed in the current shell, although they do not affect its environment when used in pipelines. .Ss Background Commands (&) If a command is terminated by the control operator ampersand -.Pq Li & , +.Pq Ql & , the shell executes the command asynchronously; the shell does not wait for the command to finish before executing the next command. @@ -743,10 +809,15 @@ repeat until the exit status of the first list is zero. The syntax of the .Ic for command is: -.Dl Ic for Ar variable Ic in Ar word ... +.Dl Ic for Ar variable Op Ic in Ar word ... .Dl Ic do Ar list .Dl Ic done .Pp +If +.Ic in +and the following words are omitted, +.Ic in Li $@ +is used instead. The words are expanded, and then the list is executed repeatedly with the variable set to each word in turn. The @@ -823,7 +894,8 @@ name ( ) command .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 +exit status of zero. +The command is normally a list enclosed between .Dq Li { and @@ -838,7 +910,7 @@ and the syntax is: .Bd -ragged -offset indent .Ic local .Op Ar variable ... -.Op Ar - +.Op Fl .Ed .Pp The @@ -848,7 +920,9 @@ command is implemented as a built-in command. When a variable is made local, it inherits the initial value and exported and readonly flags from the variable with the same name in the surrounding scope, if there is -one. Otherwise, the variable is initially unset. The shell +one. +Otherwise, the variable is initially unset. +The shell uses dynamic scoping, so that if the variable .Em x is made local to function @@ -866,7 +940,7 @@ declared inside not to the global variable named .Em x . .Pp -The only special parameter than can be made local is +The only special parameter that can be made local is .Dq Li - . Making .Dq Li - @@ -883,15 +957,19 @@ command is .Op Ar exitstatus .Ed .Pp -It terminates the currently executing function. +It terminates the current executional scope, returning from the previous +nested function, sourced script, or shell instance, in that order. The .Ic return command is implemented as a built-in 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 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. New variables can be set using the form +variables. +New variables can be set using the form .Bd -literal -offset indent name=value .Ed @@ -904,16 +982,23 @@ or a special character as explained below. .Ss Positional Parameters A positional parameter is a parameter denoted by a number greater than zero. The shell sets these initially to the values of its command line -arguments that follow the name of the shell script. The +arguments that follow the name of the shell script. +The .Ic set built-in command can also be used to set or reset them. .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. +A special parameter is a parameter denoted by a special one-character +name. +The special parameters recognized by the +.Nm +shell of +.Fx +are shown in the following list, exactly as they would appear in input +typed by the user or in the source of a shell script. .Bl -hang -.It Li * -Expands to the positional parameters, starting from one. When +.It Li $* +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 @@ -924,8 +1009,9 @@ or by a if .Ev IFS is unset. -.It Li @ -Expands to the positional parameters, starting from one. When +.It Li $@ +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 @@ -933,7 +1019,8 @@ expansion of .Li @ generates zero arguments, even when .Li @ -is double-quoted. What this basically means, for example, is +is double-quoted. +What this basically means, for example, is if $1 is .Dq abc and $2 is @@ -945,34 +1032,38 @@ the two arguments: .Bd -literal -offset indent "abc" "def ghi" .Ed -.It Li # +.It Li $# Expands to the number of positional parameters. -.It Li \&? +.It Li $\&? Expands to the exit status of the most recent pipeline. -.It Li - +.It Li $- (hyphen) 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 Li $ -Expands to the process ID of the invoked shell. A subshell +.It Li $$ +Expands to the process ID of the invoked shell. +A subshell retains the same value of $ as its parent. -.It Li \&! +.It Li $\&! Expands to the process ID of the most recent background -command executed from the current shell. For a +command executed from the current shell. +For a pipeline, the process ID is that of the last command in the pipeline. -.It Li 0 +.It Li $0 (zero) Expands to the name of the shell or shell script. .El .Ss Word Expansions This clause describes the various expansions that are -performed on words. Not all expansions are performed on +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 +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 @@ -1005,13 +1096,14 @@ 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 -.Pq Li ~ +.Pq Ql ~ is subjected to tilde expansion. All the characters up to a slash -.Pq Li / +.Pq Ql / or the end of the word are treated as a username -and are replaced with the user's home directory. If the +and are replaced with the user's home directory. +If the username is missing (as in ~/foobar), the tilde is replaced with the value of the HOME variable (the current user's home directory). @@ -1056,30 +1148,37 @@ In addition, a parameter expansion can be modified by using one of the following formats. .Bl -tag -width indent .It Li ${parameter:-word} -Use Default Values. If parameter is unset or +Use Default Values. +If parameter is unset or null, the expansion of word is substituted; otherwise, the value of parameter is substituted. .It Li ${parameter:=word} -Assign Default Values. If parameter is unset +Assign Default Values. +If parameter is unset or null, the expansion of word is -assigned to parameter. In all cases, the +assigned to parameter. +In all cases, the final value of parameter is -substituted. Only variables, not positional +substituted. +Only variables, not positional parameters or special parameters, can be assigned in this way. .It Li ${parameter:?[word]} -Indicate Error if Null or Unset. If +Indicate Error if Null or Unset. +If parameter is unset or null, the expansion of word (or a message indicating it is unset if word is omitted) is written to standard error and the shell exits with a nonzero exit status. Otherwise, the value of -parameter is substituted. An +parameter is substituted. +An interactive shell need not exit. .It Li ${parameter:+word} -Use Alternate Value. If parameter is unset +Use Alternate Value. +If parameter is unset or null, null is substituted; otherwise, the expansion of word is substituted. @@ -1090,7 +1189,8 @@ format results in a test for a parameter that is unset or null; omission of the colon results in a test for a parameter that is only unset. .Bl -tag -width indent .It Li ${#parameter} -String Length. The length in characters of +String Length. +The length in characters of the value of parameter. .El .Pp @@ -1111,33 +1211,42 @@ cause the following four varieties of pattern characters to be quoted, whereas quoting characters within the braces has this effect. .Bl -tag -width indent .It Li ${parameter%word} -Remove Smallest Suffix Pattern. The word -is expanded to produce a pattern. The +Remove Smallest Suffix Pattern. +The word +is expanded to produce a pattern. +The parameter expansion then results in parameter, with the smallest portion of the suffix matched by the pattern deleted. .It Li ${parameter%%word} -Remove Largest Suffix Pattern. The word -is expanded to produce a pattern. The +Remove Largest Suffix Pattern. +The word +is expanded to produce a pattern. +The parameter expansion then results in parameter, with the largest portion of the suffix matched by the pattern deleted. .It Li ${parameter#word} -Remove Smallest Prefix Pattern. The word -is expanded to produce a pattern. The +Remove Smallest Prefix Pattern. +The word +is expanded to produce a pattern. +The parameter expansion then results in parameter, with the smallest portion of the prefix matched by the pattern deleted. .It Li ${parameter##word} -Remove Largest Prefix Pattern. The word -is expanded to produce a pattern. The +Remove Largest Prefix Pattern. +The word +is expanded to produce a pattern. +The parameter expansion then results in parameter, with the largest portion of the prefix matched by the pattern deleted. .El .Ss Command Substitution Command substitution allows the output of a command to be substituted in -place of the command name itself. Command substitution occurs when +place of the command name itself. +Command substitution occurs when the command is enclosed as follows: .Bd -literal -offset indent $(command) @@ -1166,7 +1275,8 @@ $((expression)) .Ed .Pp The expression is treated as if it were in double-quotes, except -that a double-quote inside the expression is not treated specially. The +that a double-quote inside the expression is not treated specially. +The shell expands all tokens in the expression for parameter expansion, command substitution, and quote removal. .Pp @@ -1188,8 +1298,10 @@ Unless the .Fl f option 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 +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. @@ -1217,13 +1329,13 @@ variable or the output of the command is scanned for these characters and they are turned into meta-characters. .Pp An asterisk -.Pq Li * +.Pq Ql * matches any string of characters. A question mark -.Pq Li \&? +.Pq Ql \&? matches any single character. A left bracket -.Pq Li [ +.Pq Ql [ introduces a character class. The end of the character class is indicated by a .Dq Li \&] ; @@ -1237,9 +1349,9 @@ rather than introducing a character class. A character class matches any of the characters between the square brackets. A range of characters may be specified using a minus sign. The character class may be complemented by making an exclamation point -.Pq Li !\& +.Pq Ql !\& or the caret -.Pq Li ^\& +.Pq Ql ^\& the first character of the character class. .Pp To include a @@ -1256,28 +1368,35 @@ make it the first or last character listed. .Ss Built-in Commands This section lists the commands which are built-in because they need to perform some operation -that cannot be performed by a separate process. In addition to -these, built-in versions of the -.Xr printf 1 -and -.Xr test 1 -commands are provided for efficiency. +that cannot be performed by a separate process. +In addition to +these, built-in versions of essential utilities +are provided for efficiency. .Bl -tag -width indent .It Ic \&: A null command that returns a 0 (true) exit value. .It Ic \&. Ar file The commands in the specified file are read and executed by the shell. +The +.Ic return +command may be used to return to the +.Ic \&. +command's caller. If .Ar file contains any .Dq / -characters, it is used as is. Otherwise, the shell searches the +characters, it is used as is. +Otherwise, the shell searches the .Ev PATH -for the file. If it is not found in the +for the file. +If it is not found in the .Ev PATH , it is sought in the current working directory. -.It Ic alias Op Ar name ... -.It Ic alias Op Ar name Ns = Ns Ar string ... +.It Ic \&[ +A built-in equivalent of +.Xr test 1 . +.It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc ... Oc If .Ar name Ns = Ns Ar string is specified, the shell defines the alias @@ -1296,6 +1415,9 @@ built-in command prints the names and values of all defined aliases .Ic unalias ) . Alias values are written with appropriate quoting so that they are suitable for re-input to the shell. +Also see the +.Sx Aliases +subsection. .It Ic bg Op Ar job ... Continue the specified jobs (or the current job if no jobs are given) @@ -1309,7 +1431,7 @@ with the same name as a built-in command. List or alter key bindings for the line editor. This command is documented in .Xr editrc 5 . -.It Ic cd Oo Fl LP Oc Op Ar directory +.It Ic cd Oo Fl L | P Oc Op Ar directory Switch to the specified .Ar directory , or to the directory specified in the @@ -1363,7 +1485,8 @@ A synonym for the .Ic cd built-in command. .It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ... -Execute the specified +.It Ic command Oo Fl v | V Oc Op Ar utility +The first form of invocation executes the specified .Ar utility as a simple command (see the .Sx Simple Commands @@ -1375,10 +1498,39 @@ option is specified, the command search is performed using a default value of .Ev PATH that is guaranteed to find all of the standard utilities. -.It Ic echo Oo Fl e | n Oc Op Ar string -Print -.Ar string -to the standard output with a newline appended. +.Pp +If the +.Fl v +option is specified, +.Ar utility +is not executed but a description of its interpretation by the shell is +printed. +For ordinary commands the output is the path name; for shell built-in +commands, shell functions and keywords only the name is written. +Aliases are printed as +.Dq Ic alias Ar name Ns = Ns Ar value . +.Pp +The +.Fl V +option is identical to +.Fl v +except for the output. +It prints +.Dq Ar utility Ic is Ar description +where +.Ar description +is either +the path name to +.Ar utility , +a shell builtin, +a shell function, +a shell keyword +or +an alias for +. Ar value . +.It Ic echo Oo Fl e | n Oc Op Ar string ... +Print a space-separated list of the arguments to the standard output +and append a newline character. .Bl -tag -width indent .It Fl n Suppress the output of the trailing newline. @@ -1415,7 +1567,8 @@ Literal backslash If .Ar string is not enclosed in quotes then the backslash itself must be escaped -with a backslash to protect it from the shell. For example +with a backslash to protect it from the shell. +For example .Bd -literal -offset indent $ echo -e "a\evb" a @@ -1457,7 +1610,8 @@ If is given it is used as the exit status of the shell; otherwise the exit status of the preceding command is used. -.It Ic export Oo Fl p Oc Op Ar name ... +.It Ic export Ar name ... +.It Ic export Op Fl p The specified names are exported so that they will appear in the environment of subsequent commands. The only way to un-export a variable is to @@ -1476,6 +1630,8 @@ If the option is specified, the exported variables are printed as .Dq Ic export Ar name Ns = Ns Ar value lines, suitable for re-input to the shell. +.It Ic false +A null command that returns a non-zero (false) exit value. .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 Ns = Ns Ar new Oc Op Ar first @@ -1509,7 +1665,8 @@ is null or unset, 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 +an editor on them. +The commands are written in the sequence indicated by the first and last operands, as affected by .Fl r , @@ -1566,9 +1723,9 @@ the string form of the first operand cannot contain an embedded equal sign. .Pp The following environment variables affect the execution of .Ic fc : -.Bl -tag -width indent +.Bl -tag -width ".Ev HISTSIZE" .It Ev FCEDIT -Name of the editor to use. +Name of the editor to use for history editing. .It Ev HISTSIZE The number of previous commands that are accessible. .El @@ -1587,7 +1744,8 @@ command deprecates the older command. The first argument should be a series of letters, each possibly followed by a colon which indicates that the option takes an argument. -The specified variable is set to the parsed option. The index of +The specified variable is set to the parsed option. +The index of the next argument is placed into the shell variable .Ev OPTIND . If an option takes an argument, it is placed into the shell variable @@ -1645,12 +1803,19 @@ If the .Fl s option is specified, only the PIDs of the job commands are printed, one per line. -.It Ic pwd Op Fl LP -Print the path of the current directory. The built-in command may +.It Ic local Oo Ar variable ... Oc Op Fl +See the +.Sx Functions +subsection. +.It Ic pwd Op Fl L | P +Print the path of the current directory. +The built-in command may differ from the program of the same name because the built-in command remembers what the current directory -is rather than recomputing it each time. This makes -it faster. However, if the current directory is +is rather than recomputing it each time. +This makes +it faster. +However, if the current directory is renamed, the built-in version of .Xr pwd 1 @@ -1670,8 +1835,10 @@ The 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 +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 section on .Sx White Space Splitting (Field Splitting) @@ -1688,9 +1855,11 @@ variables are assigned the null string. Backslashes are treated specially, unless the .Fl r option is -specified. If a backslash is followed by +specified. +If a backslash is followed by a newline, the backslash and the newline will be -deleted. If a backslash is followed by any other +deleted. +If a backslash is followed by any other character, the backslash will be deleted and the following character will be treated as though it were not in .Ev IFS , @@ -1703,7 +1872,7 @@ option is specified and the elapses before any input is supplied, the .Ic read -command will return without assigning any values. +command will return an exit status of 1 without assigning any values. The .Ar timeout value may optionally be followed by one of @@ -1739,6 +1908,10 @@ If the option is specified, the read-only variables are printed as .Dq Ic readonly Ar name Ns = Ns Ar value lines, suitable for re-input to the shell. +.It Ic return Op Ar exitstatus +See the +.Sx Functions +subsection. .It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo .Fl c Ar string Oc Op Fl - Ar arg ... The @@ -1773,9 +1946,9 @@ flag may be omitted when specifying arguments to be used as positional replacement parameters. This is not recommended, because the first argument may begin with a dash -.Pq Li - +.Pq Ql - or a plus -.Pq Li + , +.Pq Ql + , which the .Ic set command will interpret as a request to enable or disable options. @@ -1804,12 +1977,16 @@ A shift sets the value of $1 to the value of $2, the value of $2 to the value of $3, and so on, decreasing the value of $# by one. If there are zero positional parameters, shifting does not do anything. +.It Ic test +A built-in equivalent of +.Xr test 1 . .It Ic times Print the amount of time spent executing the shell and its children. The first output line shows the user and system times for the shell itself, the second one contains the user and system times for the children. .It Ic trap Oo Ar action Oc Ar signal ... +.It Ic trap Fl l Cause the shell to parse and execute .Ar action when any specified @@ -1821,14 +1998,27 @@ In addition, the pseudo-signal may be used to specify an action that is performed when the shell terminates. The .Ar action -may be null or omitted; +may be an empty string or a dash +.Pq Ql - ; the former causes the specified signal to be ignored and the latter causes the default action to be taken. +Omitting the +.Ar action +is another way to request the default action, for compatibility reasons this +usage is not recommended though. When the shell forks off a subshell, it resets trapped (but not ignored) signals to the default action. The .Ic trap command has no effect on signals that were ignored on entry to the shell. +.Pp +Option +.Fl l +causes the +.Ic trap +command to display a list of valid signal names. +.It Ic true +A null command that returns a 0 (true) exit value. .It Ic type Op Ar name ... Interpret each .Ar name @@ -1855,7 +2045,8 @@ only the superuser can increase it. The .Fl S option -specifies the soft limits instead. When displaying limits, +specifies the soft limits instead. +When displaying limits, only one of .Fl S or @@ -1901,16 +2092,19 @@ The maximal number of simultaneous processes for this user ID. .It Fl v Ar virtualmem The maximal virtual size of a process, in kilobytes. .El -.It Ic umask Op Ar mask +.It Ic umask Oo Fl S Oc Op Ar mask Set the file creation mask (see .Xr umask 2 ) -to the octal value specified by +to the octal or symbolic (see +.Xr chmod 1 ) +value specified by .Ar mask . If the argument is omitted, the current mask value is printed. -.It Ic unalias Oo Fl a Oc Op Ar name -If -.Ar name -is specified, the shell removes that alias. +If the +.Fl S +option is specified, the output is symbolic, otherwise the output is octal. +.It Ic unalias Oo Fl a Oc Op Ar name ... +The specified alias names are removed. If .Fl a is specified, all aliases are removed. @@ -1952,7 +2146,8 @@ The command .Dq Li set -V ) enables vi-mode editing and places .Nm -into vi insert mode. With vi-mode enabled, +into vi insert mode. +With vi-mode enabled, .Nm can be switched between insert mode and command mode by typing .Aq ESC . @@ -1966,15 +2161,123 @@ Similarly, the .Dq Li set -E ) command can be used to enable a subset of emacs-style command line editing features. +.Sh ENVIRONMENT +The following environment variables affect the execution of +.Nm : +.Bl -tag -width ".Ev HISTSIZE" +.It Ev CDPATH +The search path used with the +.Ic cd +built-in. +.It Ev EDITOR +The fallback editor used with the +.Ic fc +built-in. +If not set, the default editor is +.Xr ed 1 . +.It Ev FCEDIT +The default editor used with the +.Ic fc +built-in. +.It Ev HISTSIZE +The number of previous commands that are accessible. +.It Ev HOME +The starting directory of +.Nm . +.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 MAIL +The name of a mail file, that will be checked for the arrival of new +mail. +Overridden by +.Ev MAILPATH . +.It Ev MAILPATH +A colon +.Pq Ql \&: +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 for details. +.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 "# " . +.It Ev PS2 +The secondary prompt string, which defaults to +.Dq Li "> " . +.It Ev PS4 +The prefix for the trace output (if +.Fl x +is active). +The default is +.Dq Li "+ " . +.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. +.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 builtin is used with a numeric argument, it +will return the argument. .Sh SEE ALSO .Xr builtin 1 , +.Xr chsh 1 , .Xr echo 1 , +.Xr ed 1 , +.Xr emacs 1 , .Xr expr 1 , +.Xr getopt 1 , .Xr printf 1 , .Xr pwd 1 , -.Xr test 1 +.Xr test 1 , +.Xr vi 1 , +.Xr execve 2 , +.Xr getrlimit 2 , +.Xr umask 2 , +.Xr editrc 5 .Sh HISTORY A .Nm -command appeared in +command, the Thompson shell, appeared in .At v1 . +It was superseded in +.At v7 +by the Bourne shell, which inherited the name +.Nm . +.Pp +This version of +.Nm +was rewritten in 1989 under the +.Bx +license after the Bourne shell from +.At V.4 . +.Sh AUTHORS +This version of +.Nm +was originally written by +.An Kenneth Almquist . +.Sh BUGS +The +.Nm +utility does not recognize multibyte characters. -- 2.41.0