1 .\" Copyright (c) 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" from: @(#)sh.1 8.6 (Berkeley) 5/4/95
36 .\" $FreeBSD: src/bin/sh/sh.1,v 1.39.2.25 2003/02/13 19:28:08 fanf Exp $
37 .\" $DragonFly: src/bin/sh/sh.1,v 1.2 2003/06/17 04:22:50 dillon Exp $
44 .Nd command interpreter (shell)
47 .Op Fl /+abCEefIimnPpsTuVvx
48 .Op Fl /+o Ar longname
54 utility is the standard command interpreter for the system.
55 The current version of
57 is in the process of being changed to
60 specification for the shell. This version has many features which make
62 similar in some respects to the Korn shell, but it is not a Korn
66 designated by POSIX, plus a few Berkeley extensions, are being
67 incorporated into this shell.
68 This man page is not intended to be a tutorial nor a complete
69 specification of the shell.
71 The shell is a command that reads lines from
72 either a file or the terminal, interprets them, and
73 generally executes other commands.
74 It is the program that is started when a user logs into the system,
75 although a user can select a different shell with the
79 implements a language that has flow control constructs,
80 a macro facility that provides a variety of features in
81 addition to data storage, along with built-in history and line
82 editing capabilities. It incorporates many features to
83 aid interactive use and has the advantage that the interpretative
84 language is common to both interactive and non-interactive
85 use (shell scripts). That is, commands can be typed directly
86 to the running shell or can be put into a file,
87 which can be executed directly by the shell.
90 .\" XXX This next sentence is incredibly confusing.
92 If no arguments are present and if the standard input of the shell
93 is connected to a terminal
97 the shell is considered an interactive shell. An interactive shell
98 generally prompts before each command and handles programming
99 and command errors differently (as described below).
100 When first starting, the shell inspects argument 0, and
101 if it begins with a dash
103 the shell is also considered a login shell.
104 This is normally done automatically by the system
105 when the user first logs in. A login shell first reads commands
110 if they exist. If the environment variable
112 is set on entry to a shell, or is set in the
114 of a login shell, the shell then reads commands from the file named in
116 Therefore, a user should place commands that are to be executed only
119 file, and commands that are executed for every shell inside the
124 variable to some file by placing the following line in the file
126 in the home directory,
129 the filename desired:
131 .Dl ENV=$HOME/.shinit; export ENV
133 The first non-option argument specified on the command line
134 will be treated as the
135 name of a file from which to read commands (a shell script), and
136 the remaining arguments are set as the positional parameters
137 of the shell ($1, $2, etc). Otherwise, the shell reads commands
138 from its standard input.
140 Unlike older versions of
144 script is only sourced on invocation of interactive shells. This
145 closes a well-known, and sometimes easily exploitable security
146 hole related to poorly thought out
149 .Ss Argument List Processing
150 All of the single letter options to
152 have a corresponding long name,
153 with the exception of
157 These long names are provided next to the single letter options
158 in the descriptions below.
159 The long name for an option may be specified as an argument to the
163 Once the shell is running,
164 the long name for an option may be specified as an argument to the
169 (described later in the section called
170 .Sx Built-in Commands ) .
171 Introducing an option with a dash
181 will stop option processing and will force the remaining
182 words on the command line to be treated as arguments.
187 options do not have long names.
188 They take arguments and are described after the single letter options.
189 .Bl -tag -width indent
190 .It Fl a Li allexport
191 Flag variables for export when assignments are made to them.
193 Enable asynchronous notification of background job
196 .It Fl C Li noclobber
197 Do not overwrite existing files with
202 command line editor (disables the
204 option if it has been set).
206 Exit immediately if any untested command fails in non-interactive mode.
207 The exit status of a command is considered to be
208 explicitly tested if the command is used to control
209 an if, elif, while, or until; or if the command is the left
216 Disable pathname expansion.
217 .It Fl I Li ignoreeof
220 from input when in interactive mode.
221 .It Fl i Li interactive
222 Force the shell to behave interactively.
224 Turn on job control (set automatically when interactive).
226 If not interactive, read commands but do not
227 execute them. This is useful for checking the
228 syntax of shell scripts.
230 Change the default for the
236 (logical directory layout)
239 (physical directory layout).
240 .It Fl p Li privileged
241 Turn on privileged mode. This mode is enabled on startup
242 if either the effective user or group id is not equal to the
243 real user or group id. Turning this mode off sets the
244 effective user and group ids to the real user and group ids.
245 When this mode is enabled for interactive shells, the file
246 .Pa /etc/suid_profile
247 is sourced instead of
251 is sourced, and the contents of the
253 variable are ignored.
255 Read commands from standard input (set automatically
256 if no file arguments are present). This option has
257 no effect when set after the shell has already started
258 running (i.e. when set with the
261 .It Fl T Li trapsasync
262 When waiting for a child, execute traps immediately.
263 If this option is not set,
264 traps are executed after the child exits,
267 This nonstandard option is useful for putting guarding shells around
268 children that block signals. The surrounding shell may kill the child
269 or it may just return control to the tty and leave the child alone,
271 .Bd -literal -offset indent
272 sh -T -c "trap 'exit 1' 2 ; some-blocking-program"
276 Write a message to standard error when attempting
277 to expand a variable that is not set, and if the
278 shell is not interactive, exit immediately.
282 command line editor (disables
286 The shell writes its input to standard error
287 as it is read. Useful for debugging.
292 to standard error before it is executed.
293 Useful for debugging.
298 option may be used to pass its string argument to the shell
299 to be interpreted as input.
300 Keep in mind that this option only accepts a single string as its
301 argument, hence multi-word strings must be quoted.
305 option takes as its only argument the long name of an option
306 to be enabled or disabled.
307 For example, the following two invocations of
309 both enable the built-in
312 .Bd -literal -offset indent
317 If used without an argument, the
319 option displays the current option settings in a human-readable format.
322 is used without an argument, the current option settings are output
323 in a format suitable for re-input into the shell.
324 .Ss Lexical Structure
325 The shell reads input in terms of lines from a file and breaks
326 it up into words at whitespace (blanks and tabs), and at
330 which are special to the shell.
331 There are two types of operators: control operators and
332 redirection operators (their meaning is discussed later).
333 The following is a list of valid operators:
334 .Bl -tag -width indent
335 .It Control operators:
336 .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
337 .It Li & Ta Li && Ta Li ( Ta Li ) Ta Li \en
338 .It Li ;; Ta Li ; Ta Li | Ta Li ||
340 .It Redirection operators:
341 .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
342 .It Li < Ta Li > Ta Li << Ta Li >> Ta Li <>
343 .It Li <& Ta Li >& Ta Li <<- Ta Li >|
347 Quoting is used to remove the special meaning of certain characters
348 or words to the shell, such as operators, whitespace, or
349 keywords. There are three types of quoting: matched single quotes,
350 matched double quotes, and backslash.
351 .Bl -tag -width indent
353 Enclosing characters in single quotes preserves the literal
354 meaning of all the characters (except single quotes, making
355 it impossible to put single-quotes in a single-quoted string).
357 Enclosing characters within double quotes preserves the literal
358 meaning of all characters except dollarsign
364 The backslash inside double quotes is historically weird.
365 It remains literal unless it precedes the following characters,
366 which it serves to quote:
367 .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
368 .It Li $ Ta Li ` Ta Li \&" Ta Li \e\ Ta Li \en
371 A backslash preserves the literal meaning of the following
372 character, with the exception of the newline character
374 A backslash preceding a newline is treated as a line continuation.
377 Reserved words are words that have special meaning to the
378 shell and are recognized at the beginning of a line and
379 after a control operator. The following are reserved words:
380 .Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center
381 .It Li \&! Ta { Ta } Ta Ic case Ta Ic do
382 .It Ic done Ta Ic elif Ta Ic else Ta Ic esac Ta Ic fi
383 .It Ic for Ta Ic if Ta Ic then Ta Ic until Ta Ic while
386 An alias is a name and corresponding value set using the
388 built-in command. Whenever a reserved word may occur (see above),
389 and after checking for reserved words, the shell
390 checks the word to see if it matches an alias.
391 If it does, it replaces it in the input stream with its value.
392 For example, if there is an alias called
397 .Bd -literal -offset indent
402 .Bd -literal -offset indent
406 Aliases provide a convenient way for naive users to
407 create shorthands for commands without having to learn how
408 to create functions with arguments. They can also be
409 used to create lexically obscure code. This use is discouraged.
411 The shell interprets the words it reads according to a
412 language, the specification of which is outside the scope
413 of this man page (refer to the BNF in the
415 document). Essentially though, a line is read and if
416 the first word of the line (or after a control operator)
417 is not a reserved word, then the shell has recognized a
418 simple command. Otherwise, a complex command or some
419 other special construct may have been recognized.
421 If a simple command has been recognized, the shell performs
422 the following actions:
425 Leading words of the form
427 are stripped off and assigned to the environment of
428 the simple command. Redirection operators and
429 their arguments (as described below) are stripped
430 off and saved for processing.
432 The remaining words are expanded as described in
434 .Sx Word Expansions ,
435 and the first remaining word is considered the command
436 name and the command is located. The remaining
437 words are considered the arguments of the command.
438 If no command name resulted, then the
440 variable assignments recognized in 1) affect the
443 Redirections are performed as described in
447 Redirections are used to change where a command reads its input
448 or sends its output. In general, redirections open, close, or
449 duplicate an existing reference to a file. The overall format
450 used for redirection is:
452 .Dl [n] redir-op file
456 is one of the redirection operators mentioned
457 previously. The following gives some examples of how these
458 operators can be used.
459 Note that stdin and stdout are commonly used abbreviations
460 for standard input and standard output respectively.
461 .Bl -tag -width "1234567890XX" -offset indent
463 redirect stdout (or file descriptor n) to file
465 same as above, but override the
469 append stdout (or file descriptor n) to file
471 redirect stdin (or file descriptor n) from file
473 redirect stdin (or file descriptor n) to and from file
475 duplicate stdin (or file descriptor n1) from file descriptor n2
477 close stdin (or file descriptor n)
479 duplicate stdout (or file descriptor n1) to file descriptor n2
481 close stdout (or file descriptor n)
484 The following redirection is often called a
486 .Bd -literal -offset indent
493 All the text on successive lines up to the delimiter is
494 saved away and made available to the command on standard
495 input, or file descriptor n if it is specified. If the delimiter
496 as specified on the initial line is quoted, then the here-doc-text
497 is treated literally, otherwise the text is subjected to
498 parameter expansion, command substitution, and arithmetic
499 expansion (as described in the section on
500 .Sx Word Expansions ) .
506 in the here-doc-text are stripped.
507 .Ss Search and Execution
508 There are three types of commands: shell functions,
509 built-in commands, and normal programs.
510 The command is searched for (by name) in that order.
511 The three types of commands are all executed in a different way.
513 When a shell function is executed, all of the shell positional
514 parameters (except $0, which remains unchanged) are
515 set to the arguments of the shell function.
516 The variables which are explicitly placed in the environment of
517 the command (by placing assignments to them before the
518 function name) are made local to the function and are set
520 Then the command given in the function definition is executed.
521 The positional parameters are restored to their original values
522 when the command completes.
523 This all occurs within the current shell.
525 Shell built-in commands are executed internally to the shell, without
526 spawning a new process.
528 Otherwise, if the command name does not match a function
529 or built-in command, the command is searched for as a normal
530 program in the file system (as described in the next section).
531 When a normal program is executed, the shell runs the program,
532 passing the arguments and the environment to the program.
533 If the program is not a normal executable file
534 (i.e. if it does not begin with the
544 the shell will interpret the program in a subshell.
545 The child shell will reinitialize itself in this case,
546 so that the effect will be
547 as if a new shell had been invoked to handle the ad-hoc shell script,
548 except that the location of hashed commands located in
549 the parent shell will be remembered by the child.
551 Note that previous versions of this document
552 and the source code itself misleadingly and sporadically
553 refer to a shell script without a magic number
555 .Qq shell procedure .
557 When locating a command, the shell first looks to see if
558 it has a shell function by that name. Then it looks for a
559 built-in command by that name. If a built-in command is not found,
560 one of two things happen:
563 Command names containing a slash are simply executed without
564 performing any searches.
566 The shell searches each entry in
568 in turn for the command. The value of the
570 variable should be a series of
571 entries separated by colons. Each entry consists of a
573 The current directory
574 may be indicated implicitly by an empty directory name,
575 or explicitly by a single period.
577 .Ss Command Exit Status
578 Each command has an exit status that can influence the behavior
579 of other shell commands. The paradigm is that a command exits
580 with zero for normal or success, and non-zero for failure,
581 error, or a false indication. The man page for each command
582 should indicate the various exit codes and what they mean.
583 Additionally, the built-in commands return exit codes, as does
584 an executed shell function.
586 If a command is terminated by a signal, its exit status is 128 plus
587 the signal number. Signal numbers are defined in the header file
588 .Aq Pa sys/signal.h .
590 Complex commands are combinations of simple commands
591 with control operators or reserved words, together creating a larger complex
592 command. More generally, a command is one of the following:
593 .Bl -item -offset indent
599 list or compound-list
606 Unless otherwise stated, the exit status of a command is
607 that of the last simple command executed by the command.
609 A pipeline is a sequence of one or more commands separated
610 by the control operator |. The standard output of all but
611 the last command is connected to the standard input
612 of the next command. The standard output of the last
613 command is inherited from the shell, as usual.
615 The format for a pipeline is:
617 .Dl [!] command1 [ | command2 ...]
619 The standard output of command1 is connected to the standard
620 input of command2. The standard input, standard output, or
621 both of a command is considered to be assigned by the
622 pipeline before any redirection specified by redirection
623 operators that are part of the command.
625 If the pipeline is not in the background (discussed later),
626 the shell waits for all commands to complete.
628 If the reserved word ! does not precede the pipeline, the
629 exit status is the exit status of the last command specified
630 in the pipeline. Otherwise, the exit status is the logical
631 NOT of the exit status of the last command. That is, if
632 the last command returns zero, the exit status is 1; if
633 the last command returns greater than zero, the exit status
636 Because pipeline assignment of standard input or standard
637 output or both takes place before redirection, it can be
638 modified by redirection. For example:
640 .Dl $ command1 2>&1 | command2
642 sends both the standard output and standard error of
644 to the standard input of
649 or newline terminator causes the preceding
651 (described below in the section called
652 .Sx Short-Circuit List Operators )
653 to be executed sequentially;
656 causes asynchronous execution of the preceding AND-OR-list.
658 Note that unlike some other shells,
660 executes each process in the pipeline as a child of the
663 Shell built-in commands are the exception to this rule.
664 They are executed in the current shell, although they do not affect its
665 environment when used in pipelines.
666 .Ss Background Commands (&)
667 If a command is terminated by the control operator ampersand
669 the shell executes the command asynchronously;
670 the shell does not wait for the command to finish
671 before executing the next command.
673 The format for running a command in background is:
674 .Bd -literal -offset indent
675 command1 & [command2 & ...]
678 If the shell is not interactive, the standard input of an
679 asynchronous command is set to /dev/null.
680 .Ss Lists (Generally Speaking)
681 A list is a sequence of zero or more commands separated by
682 newlines, semicolons, or ampersands,
683 and optionally terminated by one of these three characters.
685 list are executed in the order they are written.
686 If command is followed by an ampersand, the shell starts the
687 command and immediately proceeds onto the next command;
688 otherwise it waits for the command to terminate before
689 proceeding to the next one.
690 .Ss Short-Circuit List Operators
694 are AND-OR list operators.
696 executes the first command, and then executes the second command
697 if the exit status of the first command is zero.
699 is similar, but executes the second command if the exit
700 status of the first command is nonzero.
704 both have the same priority.
705 .Ss Flow-Control Constructs (if, while, for, case)
710 .\" XXX Use .Dl to work around broken handling of .Ic inside .Bd and .Ed .
714 .Dl [ Ic elif Ar list
715 .Dl Ic then Ar list ] ...
716 .Dl [ Ic else Ar list ]
726 The two lists are executed repeatedly while the exit status of the
730 command is similar, but has the word
735 repeat until the exit status of the first list is zero.
740 .Dl Ic for Ar variable Ic in Ar word ...
744 The words are expanded, and then the list is executed
745 repeatedly with the variable set to each word in turn.
750 commands may be replaced with
760 .Dl Ic break Op Ar num
761 .Dl Ic continue Op Ar num
765 command terminates the
774 command continues with the next iteration of the innermost loop.
775 These are implemented as built-in commands.
780 .Dl Ic case Ar word Ic in
785 The pattern can actually be one or more patterns
792 .Ss Grouping Commands Together
793 Commands may be grouped by writing either
794 .Bd -literal -offset indent
799 .Bd -literal -offset indent
803 The first form executes the commands in a subshell.
804 Note that built-in commands thus executed do not affect the current shell.
805 The second form does not fork another shell,
806 so it is slightly more efficient.
807 Grouping commands together this way allows the user to
808 redirect their output as though they were one program:
809 .Bd -literal -offset indent
810 { echo -n "hello"; echo " world"; } > greeting
813 The syntax of a function definition is
814 .Bd -literal -offset indent
818 A function definition is an executable statement; when
819 executed it installs a function named name and returns an
820 exit status of zero. The command is normally a list
826 Variables may be declared to be local to a function by
830 This should appear as the first statement of a function,
832 .Bd -ragged -offset indent
840 command is implemented as a built-in command.
842 When a variable is made local, it inherits the initial
843 value and exported and readonly flags from the variable
844 with the same name in the surrounding scope, if there is
845 one. Otherwise, the variable is initially unset. The shell
846 uses dynamic scoping, so that if the variable
848 is made local to function
850 which then calls function
852 references to the variable
856 will refer to the variable
860 not to the global variable named
863 The only special parameter than can be made local is
867 local causes any shell options that are
868 changed via the set command inside the function to be
869 restored to their original values when the function
875 .Bd -ragged -offset indent
880 It terminates the currently executing function.
883 command is implemented as a built-in command.
884 .Ss Variables and Parameters
885 The shell maintains a set of parameters. A parameter
886 denoted by a name is called a variable. When starting up,
887 the shell turns all the environment variables into shell
888 variables. New variables can be set using the form
889 .Bd -literal -offset indent
893 Variables set by the user must have a name consisting solely
894 of alphabetics, numerics, and underscores.
895 The first letter of a variable name must not be numeric.
896 A parameter can also be denoted by a number
897 or a special character as explained below.
898 .Ss Positional Parameters
899 A positional parameter is a parameter denoted by a number greater than zero.
900 The shell sets these initially to the values of its command line
901 arguments that follow the name of the shell script. The
903 built-in command can also be used to set or reset them.
904 .Ss Special Parameters
905 A special parameter is a parameter denoted by one of the following
906 special characters. The value of the parameter is listed
907 next to its character.
910 Expands to the positional parameters, starting from one. When
911 the expansion occurs within a double-quoted string
912 it expands to a single field with the value of each parameter
913 separated by the first character of the
922 Expands to the positional parameters, starting from one. When
923 the expansion occurs within double-quotes, each positional
924 parameter expands as a separate argument.
925 If there are no positional parameters, the
928 generates zero arguments, even when
930 is double-quoted. What this basically means, for example, is
939 .Bd -literal -offset indent
943 Expands to the number of positional parameters.
945 Expands to the exit status of the most recent pipeline.
947 (hyphen) Expands to the current option flags (the single-letter
948 option names concatenated into a string) as specified on
949 invocation, by the set built-in command, or implicitly
952 Expands to the process ID of the invoked shell. A subshell
953 retains the same value of $ as its parent.
955 Expands to the process ID of the most recent background
956 command executed from the current shell. For a
957 pipeline, the process ID is that of the last command in the
960 (zero) Expands to the name of the shell or shell script.
963 This clause describes the various expansions that are
964 performed on words. Not all expansions are performed on
965 every word, as explained later.
967 Tilde expansions, parameter expansions, command substitutions,
968 arithmetic expansions, and quote removals that occur within
969 a single word expand to a single field. It is only field
970 splitting or pathname expansion that can create multiple
971 fields from a single word.
972 The single exception to this rule is
973 the expansion of the special parameter
975 within double-quotes,
976 as was described above.
978 The order of word expansion is:
981 Tilde Expansion, Parameter Expansion, Command Substitution,
982 Arithmetic Expansion (these all occur at the same time).
984 Field Splitting is performed on fields generated by step (1)
989 Pathname Expansion (unless the
991 option is in effect).
998 character is used to introduce parameter expansion, command
999 substitution, or arithmetic evaluation.
1000 .Ss Tilde Expansion (substituting a user's home directory)
1001 A word beginning with an unquoted tilde character
1004 subjected to tilde expansion.
1005 All the characters up to a slash
1007 or the end of the word are treated as a username
1008 and are replaced with the user's home directory. If the
1009 username is missing (as in ~/foobar), the tilde is replaced
1010 with the value of the HOME variable (the current user's
1012 .Ss Parameter Expansion
1013 The format for parameter expansion is as follows:
1014 .Bd -literal -offset indent
1018 where expression consists of all characters until the matching
1022 escaped by a backslash or within a quoted string, and characters in
1023 embedded arithmetic expansions, command substitutions, and variable
1024 expansions, are not examined in determining the matching
1027 The simplest form for parameter expansion is:
1028 .Bd -literal -offset indent
1032 The value, if any, of parameter is substituted.
1034 The parameter name or symbol can be enclosed in braces, which are
1035 optional except for positional parameters with more than one digit or
1036 when parameter is followed by a character that could be interpreted as
1038 If a parameter expansion occurs inside double-quotes:
1041 Pathname expansion is not performed on the results of the
1044 Field splitting is not performed on the results of the
1045 expansion, with the exception of the special parameter
1049 In addition, a parameter expansion can be modified by using one of the
1051 .Bl -tag -width indent
1052 .It Li ${parameter:-word}
1053 Use Default Values. If parameter is unset or
1054 null, the expansion of word is
1055 substituted; otherwise, the value of
1056 parameter is substituted.
1057 .It Li ${parameter:=word}
1058 Assign Default Values. If parameter is unset
1059 or null, the expansion of word is
1060 assigned to parameter. In all cases, the
1061 final value of parameter is
1062 substituted. Only variables, not positional
1063 parameters or special parameters, can be
1064 assigned in this way.
1065 .It Li ${parameter:?[word]}
1066 Indicate Error if Null or Unset. If
1067 parameter is unset or null, the expansion of
1068 word (or a message indicating it is unset if
1069 word is omitted) is written to standard
1070 error and the shell exits with a nonzero
1072 Otherwise, the value of
1073 parameter is substituted. An
1074 interactive shell need not exit.
1075 .It Li ${parameter:+word}
1076 Use Alternate Value. If parameter is unset
1077 or null, null is substituted;
1078 otherwise, the expansion of word is
1082 In the parameter expansions shown previously, use of the colon in the
1083 format results in a test for a parameter that is unset or null; omission
1084 of the colon results in a test for a parameter that is only unset.
1085 .Bl -tag -width indent
1086 .It Li ${#parameter}
1087 String Length. The length in characters of
1088 the value of parameter.
1091 The following four varieties of parameter expansion provide for substring
1093 In each case, pattern matching notation
1095 .Sx Shell Patterns ) ,
1096 rather than regular expression notation,
1097 is used to evaluate the patterns.
1098 If parameter is one of the special parameters
1102 the result of the expansion is unspecified.
1103 Enclosing the full parameter expansion string in double-quotes does not
1104 cause the following four varieties of pattern characters to be quoted,
1105 whereas quoting characters within the braces has this effect.
1106 .Bl -tag -width indent
1107 .It Li ${parameter%word}
1108 Remove Smallest Suffix Pattern. The word
1109 is expanded to produce a pattern. The
1110 parameter expansion then results in
1111 parameter, with the smallest portion of the
1112 suffix matched by the pattern deleted.
1113 .It Li ${parameter%%word}
1114 Remove Largest Suffix Pattern. The word
1115 is expanded to produce a pattern. The
1116 parameter expansion then results in
1117 parameter, with the largest portion of the
1118 suffix matched by the pattern deleted.
1119 .It Li ${parameter#word}
1120 Remove Smallest Prefix Pattern. The word
1121 is expanded to produce a pattern. The
1122 parameter expansion then results in
1123 parameter, with the smallest portion of the
1124 prefix matched by the pattern deleted.
1125 .It Li ${parameter##word}
1126 Remove Largest Prefix Pattern. The word
1127 is expanded to produce a pattern. The
1128 parameter expansion then results in
1129 parameter, with the largest portion of the
1130 prefix matched by the pattern deleted.
1132 .Ss Command Substitution
1133 Command substitution allows the output of a command to be substituted in
1134 place of the command name itself. Command substitution occurs when
1135 the command is enclosed as follows:
1136 .Bd -literal -offset indent
1140 or the backquoted version:
1141 .Bd -literal -offset indent
1145 The shell expands the command substitution by executing command in a
1146 subshell environment and replacing the command substitution
1147 with the standard output of the command,
1148 removing sequences of one or more newlines at the end of the substitution.
1149 Embedded newlines before the end of the output are not removed;
1150 however, during field splitting, they may be translated into spaces
1151 depending on the value of
1153 and the quoting that is in effect.
1154 .Ss Arithmetic Expansion
1155 Arithmetic expansion provides a mechanism for evaluating an arithmetic
1156 expression and substituting its value.
1157 The format for arithmetic expansion is as follows:
1158 .Bd -literal -offset indent
1162 The expression is treated as if it were in double-quotes, except
1163 that a double-quote inside the expression is not treated specially. The
1164 shell expands all tokens in the expression for parameter expansion,
1165 command substitution, and quote removal.
1167 Next, the shell treats this as an arithmetic expression and
1168 substitutes the value of the expression.
1169 .Ss White Space Splitting (Field Splitting)
1170 After parameter expansion, command substitution, and
1171 arithmetic expansion the shell scans the results of
1172 expansions and substitutions that did not occur in double-quotes for
1173 field splitting and multiple fields can result.
1175 The shell treats each character of the
1177 as a delimiter and uses
1178 the delimiters to split the results of parameter expansion and command
1179 substitution into fields.
1180 .Ss Pathname Expansion (File Name Generation)
1184 file name generation is performed
1185 after word splitting is complete. Each word is
1186 viewed as a series of patterns, separated by slashes. The
1187 process of expansion replaces the word with the names of
1188 all existing files whose names can be formed by replacing
1189 each pattern with a string that matches the specified pattern.
1190 There are two restrictions on this: first, a pattern cannot match
1191 a string containing a slash, and second,
1192 a pattern cannot match a string starting with a period
1193 unless the first character of the pattern is a period.
1194 The next section describes the patterns used for both
1195 Pathname Expansion and the
1199 A pattern consists of normal characters, which match themselves,
1200 and meta-characters.
1201 The meta-characters are
1207 These characters lose their special meanings if they are quoted.
1208 When command or variable substitution is performed and the dollar sign
1209 or back quotes are not double-quoted, the value of the
1210 variable or the output of the command is scanned for these
1211 characters and they are turned into meta-characters.
1215 matches any string of characters.
1218 matches any single character.
1221 introduces a character class.
1222 The end of the character class is indicated by a
1230 rather than introducing a character class.
1231 A character class matches any of the characters between the square brackets.
1232 A range of characters may be specified using a minus sign.
1233 The character class may be complemented by making an exclamation point
1235 the first character of the character class.
1239 in a character class, make it the first character listed
1245 make it the first or last character listed.
1246 .Ss Built-in Commands
1247 This section lists the commands which
1248 are built-in because they need to perform some operation
1249 that cannot be performed by a separate process. In addition to
1250 these, built-in versions of the
1254 commands are provided for efficiency.
1255 .Bl -tag -width indent
1257 A null command that returns a 0 (true) exit value.
1259 The commands in the specified file are read and executed by the shell.
1264 characters, it is used as is. Otherwise, the shell searches the
1266 for the file. If it is not found in the
1268 it is sought in the current working directory.
1269 .It Ic alias Op Ar name ...
1270 .It Ic alias Op Ar name Ns = Ns Ar string ...
1272 .Ar name Ns = Ns Ar string
1273 is specified, the shell defines the alias
1279 is specified, the value of the alias
1282 With no arguments, the
1284 built-in command prints the names and values of all defined aliases
1287 Alias values are written with appropriate quoting so that they are
1288 suitable for re-input to the shell.
1289 .It Ic bg Op Ar job ...
1290 Continue the specified jobs
1291 (or the current job if no jobs are given)
1293 .It Ic builtin Ar cmd Op Ar arg ...
1294 Execute the specified built-in command,
1296 This is useful when the user wishes to override a shell function
1297 with the same name as a built-in command.
1298 .It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc
1299 List or alter key bindings for the line editor.
1300 This command is documented in
1302 .It Ic cd Oo Fl LP Oc Op Ar directory
1303 Switch to the specified
1305 or to the directory specified in the
1307 environment variable if no
1316 then the directories listed in the
1319 searched for the specified
1323 is unset, the current directory is searched.
1326 is the same as that of
1328 In an interactive shell,
1331 command will print out the name of the directory
1332 that it actually switched to
1333 if this is different from the name that the user gave.
1334 These may be different either because the
1336 mechanism was used or because a symbolic link was crossed.
1340 option is specified,
1342 is handled physically and symbolic links are resolved before
1344 components are processed.
1347 option is specified,
1349 is handled logically.
1350 This is the default.
1355 .It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ...
1356 Execute the specified
1358 as a simple command (see the
1364 option is specified, the command search is performed using a
1367 that is guaranteed to find all of the standard utilities.
1368 .It Ic echo Oo Fl e | n Oc Op Ar string
1371 to the standard output with a newline appended.
1372 .Bl -tag -width indent
1374 Suppress the output of the trailing newline.
1376 Process C-style backslash escape sequences.
1378 understands the following character escapes:
1379 .Bl -tag -width indent
1381 Alert (ring the terminal bell)
1385 Suppress the trailing newline (this has the side-effect of truncating the
1386 line if it is not the last character)
1388 The ESC character (ASCII 0x1b)
1402 (Zero) The character whose octal value is nnn
1407 is not enclosed in quotes then the backslash itself must be escaped
1408 with a backslash to protect it from the shell. For example
1409 .Bd -literal -offset indent
1418 $ echo -e a\e\e\e\eb
1427 options may be specified.
1428 .It Ic eval Ar string ...
1429 Concatenate all the arguments with spaces.
1430 Then re-parse and execute the command.
1431 .It Ic exec Op Ar command Op arg ...
1435 the shell process is replaced with the specified program
1436 (which must be a real program, not a shell built-in command or function).
1437 Any redirections on the
1439 command are marked as permanent,
1440 so that they are not undone when the
1443 .It Ic exit Op Ar exitstatus
1444 Terminate the shell process.
1448 it is used as the exit status of the shell;
1449 otherwise the exit status of the preceding command is used.
1450 .It Ic export Oo Fl p Oc Op Ar name ...
1451 The specified names are exported so that they will
1452 appear in the environment of subsequent commands.
1453 The only way to un-export a variable is to
1456 The shell allows the value of a variable to be set
1457 at the same time as it is exported by writing
1458 .Bd -literal -offset indent
1462 With no arguments the export command lists the names
1463 of all exported variables.
1466 option is specified, the exported variables are printed as
1467 .Dq Ic export Ar name Ns = Ns Ar value
1468 lines, suitable for re-input to the shell.
1469 .It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last
1470 .It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last
1471 .It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first
1474 built-in command lists, or edits and re-executes,
1475 commands previously entered to an interactive shell.
1476 .Bl -tag -width indent
1478 Use the editor named by
1480 to edit the commands.
1481 The editor string is a command name,
1482 subject to search via the
1487 variable is used as a default when
1492 is null or unset, the value of the
1499 is used as the editor.
1501 List the commands rather than invoking
1502 an editor on them. The commands are written in the
1503 sequence indicated by the first and last operands, as
1506 with each command preceded by the command number.
1508 Suppress command numbers when listing with
1511 Reverse the order of the commands listed
1520 Re-execute the command without invoking an editor.
1523 Select the commands to list or edit.
1524 The number of previous commands that can be accessed
1525 are determined by the value of the
1532 or both are one of the following:
1533 .Bl -tag -width indent
1535 A positive number representing a command number;
1536 command numbers can be displayed with the
1540 A negative decimal number representing the
1541 command that was executed
1544 commands previously.
1545 For example, -1 is the immediately previous command.
1547 A string indicating the most recently entered command
1548 that begins with that string.
1551 operand is not also specified with
1553 the string form of the first operand cannot contain an embedded equal sign.
1557 The following environment variables affect the execution of
1559 .Bl -tag -width indent
1561 Name of the editor to use.
1563 The number of previous commands that are accessible.
1568 or the current job to the foreground.
1569 .It Ic getopts Ar optstring Ar var
1575 command deprecates the older
1578 The first argument should be a series of letters, each possibly
1579 followed by a colon which indicates that the option takes an argument.
1580 The specified variable is set to the parsed option. The index of
1581 the next argument is placed into the shell variable
1583 If an option takes an argument, it is placed into the shell variable
1585 If an invalid option is encountered,
1589 It returns a false value (1) when it encounters the end of the options.
1590 .It Ic hash Oo Fl rv Oc Op Ar command ...
1591 The shell maintains a hash table which remembers the locations of commands.
1592 With no arguments whatsoever, the
1594 command prints out the contents of this table.
1595 Entries which have not been looked at since the last
1597 command are marked with an asterisk;
1598 it is possible for these entries to be invalid.
1602 command removes each specified
1604 from the hash table (unless they are functions) and then locates it.
1609 prints the locations of the commands as it finds them.
1614 command to delete all the entries in the hash table except for functions.
1615 .It Ic jobid Op Ar job
1616 Print the process id's of the processes in the specified
1620 argument is omitted, use the current job.
1621 .It Ic jobs Oo Fl ls Oc Op Ar job ...
1622 Print information about the specified jobs, or all jobs if no
1625 The information printed includes job ID, status and command name.
1629 option is specified, the PID of each job is also printed.
1632 option is specified, only the PIDs of the jobs are printed, one per line.
1634 Print the path of the current directory. The built-in command may
1635 differ from the program of the same name because the
1636 built-in command remembers what the current directory
1637 is rather than recomputing it each time. This makes
1638 it faster. However, if the current directory is
1640 the built-in version of
1642 will continue to print the old name for the directory.
1646 option is specified, symbolic links are resolved.
1649 option is specified, the shell's notion of the current directory
1650 is printed (symbolic links are not resolved).
1651 This is the default.
1652 .It Ic read Oo Fl p Ar prompt Oc Oo Fl t Ar timeout Oc Oo Fl er Oc Ar variable ...
1658 and the standard input is a terminal. Then a line is
1659 read from the standard input. The trailing newline
1660 is deleted from the line and the line is split as
1661 described in the section on
1662 .Sx White Space Splitting (Field Splitting)
1664 the pieces are assigned to the variables in order.
1665 If there are more pieces than variables, the remaining
1666 pieces (along with the characters in
1668 that separated them)
1669 are assigned to the last variable.
1670 If there are more variables than pieces, the remaining
1671 variables are assigned the null string.
1673 Backslashes are treated specially, unless the
1676 specified. If a backslash is followed by
1677 a newline, the backslash and the newline will be
1678 deleted. If a backslash is followed by any other
1679 character, the backslash will be deleted and the following
1680 character will be treated as though it were not in
1686 option is specified and the
1688 elapses before any input is supplied,
1691 command will return without assigning any values.
1694 value may optionally be followed by one of
1699 to explicitly specify seconds, minutes or hours.
1700 If none is supplied,
1706 option exists only for backward compatibility with older scripts.
1707 .It Ic readonly Oo Fl p Oc Op Ar name ...
1710 is marked as read only,
1711 so that it cannot be subsequently modified or unset.
1712 The shell allows the value of a variable to be set
1713 at the same time as it is marked read only
1714 by using the following form:
1715 .Bd -literal -offset indent
1719 With no arguments the
1721 command lists the names of all read only variables.
1724 option is specified, the read-only variables are printed as
1725 .Dq Ic readonly Ar name Ns = Ns Ar value
1726 lines, suitable for re-input to the shell.
1727 .It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo
1728 .Fl c Ar string Oc Op Fl - Ar arg ...
1731 command performs three different functions:
1734 With no arguments, it lists the values of all shell variables.
1736 If options are given,
1737 either in short form or using the long
1738 .Dq Fl /+o Ar longname
1740 it sets or clears the specified options as described in the section called
1741 .Sx Argument List Processing .
1745 option is specified,
1747 will replace the shell's positional parameters with the subsequent
1749 If no arguments follow the
1752 all the positional parameters will be cleared,
1753 which is equivalent to executing the command
1757 flag may be omitted when specifying arguments to be used
1758 as positional replacement parameters.
1759 This is not recommended,
1760 because the first argument may begin with a dash
1766 command will interpret as a request to enable or disable options.
1768 .It Ic setvar Ar variable Ar value
1769 Assigns the specified
1774 is intended to be used in functions that
1775 assign values to variables whose names are passed as parameters.
1776 In general it is better to write
1777 .Bd -literal -offset indent
1782 .It Ic shift Op Ar n
1783 Shift the positional parameters
1788 A shift sets the value of $1 to the value of $2,
1789 the value of $2 to the value of $3, and so on,
1790 decreasing the value of $# by one.
1791 If there are zero positional parameters, shifting does not do anything.
1792 .It Ic trap Oo Ar action Oc Ar signal ...
1793 Cause the shell to parse and execute
1798 The signals are specified by name or number.
1799 In addition, the pseudo-signal
1801 may be used to specify an action that is performed when the shell terminates.
1804 may be null or omitted;
1805 the former causes the specified signal to be ignored
1806 and the latter causes the default action to be taken.
1807 When the shell forks off a subshell,
1808 it resets trapped (but not ignored) signals to the default action.
1811 command has no effect on signals that were ignored on entry to the shell.
1812 .It Ic type Op Ar name ...
1815 as a command and print the resolution of the command search.
1816 Possible resolutions are:
1817 shell keyword, alias, shell built-in command, command, tracked alias
1819 For aliases the alias expansion is printed;
1820 for commands and tracked aliases
1821 the complete pathname of the command is printed.
1822 .It Ic ulimit Oo Fl HSabcdflmnstuv Oc Op Ar limit
1823 Set or display resource limits (see
1827 is specified, the named resource will be set;
1828 otherwise the current resource value will be displayed.
1832 is specified, the hard limits will be set or displayed.
1833 While everybody is allowed to reduce a hard limit,
1834 only the superuser can increase it.
1838 specifies the soft limits instead. When displaying limits,
1844 The default is to display the soft limits,
1845 and to set both the hard and the soft limits.
1851 command to display all resources.
1854 is not acceptable in this mode.
1856 The remaining options specify which resource value is to be
1857 displayed or modified.
1858 They are mutually exclusive.
1859 .Bl -tag -width indent
1861 The maximum size of socket buffer usage, in bytes.
1862 .It Fl c Ar coredumpsize
1863 The maximal size of core dump files, in 512-byte blocks.
1864 .It Fl d Ar datasize
1865 The maximal size of the data segment of a process, in kilobytes.
1866 .It Fl f Ar filesize
1867 The maximal size of a file, in 512-byte blocks.
1868 .It Fl l Ar lockedmem
1869 The maximal size of memory that can be locked by a process, in
1871 .It Fl m Ar memoryuse
1872 The maximal resident set size of a process, in kilobytes.
1874 The maximal number of descriptors that could be opened by a process.
1875 .It Fl s Ar stacksize
1876 The maximal size of the stack segment, in kilobytes.
1878 The maximal amount of CPU time to be used by each process, in seconds.
1879 .It Fl u Ar userproc
1880 The maximal number of simultaneous processes for this user ID.
1881 .It Fl v Ar virtualmem
1882 The maximal virtual size of a process, in kilobytes.
1884 .It Ic umask Op Ar mask
1885 Set the file creation mask (see
1887 to the octal value specified by
1889 If the argument is omitted, the current mask value is printed.
1890 .It Ic unalias Oo Fl a Oc Op Ar name
1893 is specified, the shell removes that alias.
1896 is specified, all aliases are removed.
1897 .It Ic unset Oo Fl fv Oc Ar name ...
1898 The specified variables or functions are unset and unexported.
1901 option is specified or no options are given, the
1903 arguments are treated as variable names.
1906 option is specified, the
1908 arguments are treated as function names.
1909 .It Ic wait Op Ar job
1910 Wait for the specified
1912 to complete and return the exit status of the last process in the
1914 If the argument is omitted, wait for all jobs to complete
1915 and return an exit status of zero.
1917 .Ss Commandline Editing
1920 is being used interactively from a terminal, the current command
1921 and the command history
1925 .Sx Built-in Commands )
1926 can be edited using vi-mode command line editing.
1927 This mode uses commands similar
1928 to a subset of those described in the vi man page.
1933 enables vi-mode editing and places
1935 into vi insert mode. With vi-mode enabled,
1937 can be switched between insert mode and command mode by typing
1941 while in command mode will pass the line to the shell.
1947 command can be used to enable a subset of
1948 emacs-style command line editing features.
projects / dragonfly.git / blob