37.\"
38.na
39.TH SH 1
40.SH NAME
41sh \- command interpreter (shell)
42.SH SYNOPSIS
43sh [-/+aCefnuvxIimsVEb] [-/+o longname] [arg ...]
44.SH DESCRIPTION
45.LP
46Sh is the standard command interpreter for the system.
47The current version of sh is in the process of being changed to
48conform with the POSIX 1003.2 and 1003.2a specifications for
49the shell. This version has many features which make it appear
50similar in some respects to the Korn shell, but it is not a Korn
51shell clone (run GNU's bash if you want that). Only features
52designated by POSIX, plus a few Berkeley extensions, are being
53incorporated into this shell. We expect POSIX conformance by the
54time 4.4 BSD is released.
55This man page is not intended to be a tutorial or a complete
56specification of the shell.
57.sp 2
58.B Overview
59.sp
60.LP
61The shell is a command that reads lines from
62either a file or the terminal, interprets them, and
63generally executes other commands. It is the program that is running
64when a user logs into the system (although a user can select
65a different shell with the chsh(1) command).
66The shell
67implements a language that has flow control constructs,
68a macro facility that provides a variety of features in
69addition to data storage, along with built in history and line
70editing capabilities. It incorporates many features to
71aid interactive use and has the advantage that the interpretative
72language is common to both interactive and non-interactive
73use (shell scripts). That is, commands can be typed directly
74to the running shell or can be put into a file and the file
75can be executed directly by the shell.
76.sp 2
77.B Invocation
78.sp
79.LP
80If no args are present and if the standard input of the shell
81is connected to a terminal (or if the -i flag is set), the shell
82is considered an interactive shell. An interactive shell
83generally prompts before each command and handles programming
84and command errors differently (as described below).
85When first starting, the shell inspects argument 0, and
86if it begins with a dash '-', the shell is also considered
87a login shell. This is normally done automatically by the system
88when the user first logs in. A login shell first reads commands
89from the files /etc/profile and .profile if they exist.
90If the environment variable ENV is set on entry to a shell,
91or is set in the .profile of a login shell, the shell next reads
92commands from the file named in ENV. Therefore, a user should
93place commands that are to be executed only at login time in
94the .profile file, and commands that are executed for every
95shell inside the ENV file. To set the ENV variable to some
96file, place the following line in your .profile of your home
97directory
98.nf
99
100 ENV=$HOME/.shinit; export ENV
101
102.fi
103substituting for ``.shinit'' any filename you wish.
104Since the ENV file is read for
105every invocation of the shell, including shell scripts and
106non-interactive shells, the following paradigm is useful
107for restricting commands in the ENV file to interactive invocations.
108Place commands within the ``case'' and ``esac'' below (these
109commands are described later):
110.nf
111
112 case $- in *i*)
113 # commands for interactive use only
114 ...
115 esac
116
117.fi
118If command line arguments besides the options have been
119specified, then the shell treats the first argument as the
120name of a file from which to read commands (a shell script), and
121the remaining arguments are set as the positional parameters
122of the shell ($1, $2, etc). Otherwise, the shell reads commands
123from its standard input.
124.sp 2
125.B Argument List Processing
126.sp
127.LP
128All of the single letter options have a corresponding name
129that can be used as an argument to the '-o' option. The
130set -o name is provided next to the single letter option in
131the description below.
132Specifying a dash ``-'' turns the option on, while using a plus ``+''
133disables the option.
134The following options can be set from the command line or
135with the set(1) builtin (described later).
136.TP
137-a allexport
138Export all variables assigned to.
139(UNIMPLEMENTED for 4.4alpha)
140.TP
141-C noclobber
142Don't overwrite existing files with ``>''.
143(UNIMPLEMENTED for 4.4alpha)
144.TP
145-e errexit
146If not interactive, exit immediately if any
147untested command fails.
148The exit status of a command is considered to be
149explicitly tested if the command is used to control
150an if, elif, while, or until; or if the command is the left
151hand operand of an ``&&'' or ``||'' operator.
152
153.TP
154-f noglob
155Disable pathname expansion.
156.TP
157-n noexec
158If not interactive, read commands but do not
159execute them. This is useful for checking the
160syntax of shell scripts.
161.TP
162-u nounset
163Write a message to standard error when attempting
164to expand a variable that is not set, and if the
165shell is not interactive, exit immediately.
166(UNIMPLEMENTED for 4.4alpha)
167.TP
168-v verbose
169The shell writes its input to standard error
170as it is read. Useful for debugging.
171.TP
172-x xtrace
173Write each command to standard error (preceded
174by a '+ ') before it is executed. Useful for
175debugging.
176.TP
177-I ignoreeof
178Ignore EOF's from input when interactive.
179.TP
180-i interactive
181Force the shell to behave interactively.
182.TP
183-m monitor
184Turn on job control (set automatically when
185interactive).
186.TP
187-s stdin
188Read commands from standard input (set automatically
189if no file arguments are present). This option has
190no effect when set after the shell has already started
191running (i.e. with set(1)).
192.TP
193-V vi
194Enable the builtin vi(1) command line editor (disables
195-E if it has been set).
196.TP
197-E emacs
198Enable the builtin emacs(1) command line editor (disables
199-V if it has been set).
200.TP
201-b notify
202Enable asynchronous notification of background job
203completion.
204(UNIMPLEMENTED for 4.4alpha)
205.LP
206.sp 2
207.B Lexical Structure
208.sp
209.LP
210The shell reads input in terms of lines from a file and breaks
211it up into words at whitespace (blanks and tabs), and at
212certain sequences of
213characters that are special to the shell called ``operators''.
214There are two types of operators: control operators and
215redirection operators (their meaning is discussed later).
216Following is a list of operators:
217.nf
218.sp
219Control operators: & && ( ) ; ;; | || <newline>
220.sp
221Redirection operator: < > >| << >> <& >& <<- <>
222.sp
223.fi
224.sp 2
225.B Quoting
226.sp
227.LP
228Quoting is used to remove the special meaning of certain characters
229or words to the shell, such as operators, whitespace, or
230keywords. There are three types of quoting: matched single quotes,
231matched double quotes, and backslash.
232.sp 2
233.B Backslash
234.sp
235.LP
236A backslash preserves the literal meaning of the following
237character, with the exception of <newline>. A backslash preceding
238a <newline> is treated as a line continuation.
239.sp 2
240.B Single Quotes
241.sp
242.LP
243Enclosing characters in single quotes preserves the literal
244meaning of all the characters.
245.sp 2
246.B Double Quotes
247.sp
248.LP
249Enclosing characters within double quotes preserves the literal
250meaning of all characters except dollarsign ($), backquote (`),
251and backslash (\\). The backslash inside double quotes is
252historically weird, and serves to quote only the following
253characters: $ ` " \\ <newline>.
254Otherwise it remains literal.
255.sp 2
256.B Reserved Words
257.sp
258.LP
259Reserved words are words that have special meaning to the
260shell and are recognized at the beginning of a line and
261after a control operator. The following are reserved words:
262.nf
263
264 ! elif fi while case
265 else for then { }
266 do done until if esac
267
268.fi
269Their meaning is discussed later.
270.sp 2
271.B Aliases
272.sp
273.LP
274An alias is a name and corresponding value set using the alias(1)
275builtin command. Whenever a reserved word may occur (see above),
276and after checking for reserved words, the shell
277checks the word to see if it matches an alias. If it does,
278it replaces it in the input stream with its value. For example,
279if there is an alias called ``lf'' with the value ``ls -F'',
280then the input
281.nf
282
283 lf foobar <return>
284
285 would become
286
287 ls -F foobar <return>
288
289.fi
290.LP
291Aliases provide a convenient way for naive users to
292create shorthands for commands without having to learn how
293to create functions with arguments. They can also be
294used to create lexically obscure code. This use is discouraged.
295.sp 2
296.B Commands
297.sp
298.LP
299The shell interprets the words it reads according to a
300language, the specification of which is outside the scope
301of this man page (refer to the BNF in the POSIX 1003.2
302document). Essentially though, a line is read and if
303the first word of the line (or after a control operator)
304is not a reserved word, then the shell has recognized a
305simple command. Otherwise, a complex command or some
306other special construct may have been recognized.
307.sp 2
308.B Simple Commands
309.sp
310.LP
311If a simple command has been recognized, the shell performs
312the following actions:
313.sp
3141) Leading words of the form ``name=value'' are
315stripped off and assigned to the environment of
316the simple command. Redirection operators and
317their arguments (as described below) are stripped
318off and saved for processing.
319.sp
3202) The remaining words are expanded as described in
321the section called ``Expansions'', and the
322first remaining word is considered the command
323name and the command is located. The remaining
324words are considered the arguments of the command.
325If no command name resulted, then the ``name=value''
326variable assignments recognized in 1) affect the
327current shell.
328.sp
3293) Redirections are performed as described in
330the next section.
331.sp 2
332.B Redirections
333.sp
334.LP
335Redirections are used to change where a command reads its input
336or sends its output. In general, redirections open, close, or
337duplicate an existing reference to a file. The overall format
338used for redirection is:
339.nf
340
341 [n] redir-op file
342
343.fi
344where redir-op is one of the redirection operators mentioned
345previously. Following is a list of the possible redirections.
346The [n] is an optional number, as in '3' (not '[3]'), that
347refers to a file descriptor.
348.TP
349[n]> file
350Redirect standard output (or n) to file.
351.TP
352[n]>| file
353Same, but override the -C option.
354.TP
355[n]>> file
356Append standard output (or n) to file.
357.TP
358[n]< file
359Redirect standard input (or n) from file.
360.TP
361[n1]<&n2
362Duplicate standard input (or n1) from
363file descriptor n2.
364.TP
365[n]<&-
366Close standard input (or n).
367.TP
368[n1]>&n2
369Duplicate standard output (or n) from
370n2.
371.TP
372[n]>&-
373Close standard output (or n).
374.TP
375[n]<> file
376Open file for reading and writing on
377standard input (or n).
378.LP
379The following redirection is often called a ``here-document''.
380.nf
381
382 [n]<< delimiter
383 here-doc-text...
384 delimiter
385
386.fi
387All the text on successive lines up to the delimiter is
388saved away and made available to the command on standard
389input, or file descriptor n if it is specified. If the delimiter
390as specified on the initial line is quoted, then the here-doc-text
391is treated literally, otherwise the text is subjected to
392parameter expansion, command substitution, and arithmetic
393expansion (as described in the section on ``Expansions''). If
394the operator is ``<<-'' instead of ``<<'', then leading tabs
395in the here-doc-text are stripped.
396.sp 2
397.B Search and Execution
398.sp
399.LP
400There are three types of commands: shell functions, builtin commands, and normal programs -- and the
401command is searched for (by name) in that order. They
402each are executed in a different way.
403.LP
404When a shell function is executed, all of the shell positional parameters (except $0, which remains unchanged) are
405set to the arguments of the shell function.
406The variables which are explicitly placed in the environment of
407the command (by placing assignments to them before the
408function name) are made local to the function and are set
409to the values given. Then the command given in the function
410definition is executed. The positional parameters are
411restored to their original values when the command completes.
412.LP
413Shell builtins are executed internally to the shell, without spawning a new process.
414.LP
415Otherwise, if the command name doesn't match a function
416or builtin, the command is searched for as a normal
417program in the filesystem (as described in the next section).
418When a normal program is executed, the shell runs the program,
419passing the arguments and the environment to the
420program. If the program is a shell procedure, the shell
421will interpret the program in a subshell. The shell will
422reinitialize itself in this case, so that the effect will
423be as if a new shell had been invoked to handle the shell
424procedure, except that the location of commands located in
425the parent shell will be remembered by the child.
426.sp 2
427.B Path Search
428.sp
429.LP
430When locating a command, the shell first looks to see if
431it has a shell function by that name. Then it looks for a
432builtin command by that name.
433Finally, it searches each
434entry in PATH in turn for the command.
435.LP
436The value of the PATH variable should be a series of
437entries separated by colons. Each entry consists of a
438directory name.
439The current directory
440may be indicated by an empty directory name.
441.LP
442Command names containing a slash are simply executed without performing any of the above searches.
443.sp 2
444.B Command Exit Status
445.sp
446.LP
447Each command has an exit status that can influence the behavior
448of other shell commands. The paradigm is that a command exits
449with zero for normal or success, and non-zero for failure,
450error, or a false indication. The man page for each command
451should indicate the various exit codes and what they mean.
452Additionally, the builtin commands return exit codes, as does
453an executed function.
454.sp 2
455.B Complex Commands
456.sp
457.LP
458Complex commands are combinations of simple commands
459with control operators or reserved words, together creating a larger complex
460command. More generally, a command is one of the following:
461.nf
462
463 - simple command
464
465 - pipeline
466
467 - list or compound-list
468
469 - compound command
470
471 - function definition
472
473.fi
474.LP
475Unless otherwise stated, the exit status of a command is
476that of the last simple command executed by the command.
477.sp 2
478.B Pipeline
479.sp
480.LP
481A pipeline is a sequence of one or more commands separated
482by the control operator |. The standard output of all but
483the last command is connected to the standard input
484of the next command.
485.LP
486The format for a pipeline is:
487.nf
488
489[!] command1 [ | command2 ...]
490
491.fi
492.LP
493The standard output of command1 is connected to the standard
494input of command2. The standard input, standard output, or
495both of a command is considered to be assigned by the
496pipeline before any redirection specified by redirection
497operators that are part of the command.
498.LP
499If the pipeline is not in the background (discussed later),
500the shell waits for all commands to complete.
501.LP
502If the reserved word ! does not precede the pipeline, the
503exit status is the exit status of the last command specified
504in the pipeline. Otherwise, the exit status is the logical
505NOT of the exit status of the last command. That is, if
506the last command returns zero, the exit status is 1; if
507the last command returns greater than zero, the exit status
508is zero.
509.LP
510Because pipeline assignment of standard input or standard
511output or both takes place before redirection, it can be
512modified by redirection. For example:
513.nf
514
515$ command1 2>&1 | command2
516
517.fi
518sends both the standard output and standard error of command1
519to the standard input of command2.
520.LP
521A ; or <newline> terminator causes the preceding
522AND-OR-list (described next) to be executed sequentially; a & causes
523asynchronous execution of the preceding AND-OR-list.
524.sp 2
525.B Background Commands -- &
526.sp
527.LP
528If a command is terminated by the control operator ampersand
529(&), the shell executes the command asynchronously -- that is,
530the shell does not wait for
531the command to finish before executing the next command.
532.LP
533The format for running a command in background is:
534.nf
535
536command1 & [command2 & ...]
537
538.fi
539If the shell is not interactive, the standard input of an
540asynchronous command is set to /dev/null.
541.sp 2
542.B Lists -- Generally Speaking
543.sp
544.LP
545A list is a sequence of zero or more commands separated by
546newlines, semicolons, or ampersands,
547and optionally terminated by one of these three characters.
548The commands in a
549list are executed in the order they are written.
550If command is followed by an ampersand, the shell starts the
551command and immediately proceed onto the next command;
552otherwise it waits for the command to terminate before
553proceeding to the next one.
554.LP
555``&&'' and ``||'' are AND-OR list operators. ``&&'' executes
556the first command, and then executes the second command
557iff the exit status of the first command is zero. ``||''
558is similar, but executes the second command iff the exit
559status of the first command is nonzero. ``&&'' and ``||''
560both have the same priority.
561.LP
562The syntax of the if command is
563.nf
564
565 if list
566 then list
567 [ elif list
568 then list ] ...
569 [ else list ]
570 fi
571
572.fi
573The syntax of the while command is
574.nf
575
576 while list
577 do list
578 done
579
580.fi
581The two lists are executed repeatedly while the exit status of the first list is zero. The until command is similar, but has the word until in place of while
582repeat until the exit status of the first list is zero.
583.LP
584The syntax of the for command is
585.nf
586
587 for variable in word...
588 do list
589 done
590
591.fi
592The words are expanded, and then the list is executed
593repeatedly with the variable set to each word in turn. do
594and done may be replaced with ``{'' and ``}''.
595.LP
596The syntax of the break and continue command is
597.nf
598
599 break [ num ]
600 continue [ num ]
601
602.fi
603Break terminates the num innermost for or while loops.
604Continue continues with the next iteration of the innermost loop. These are implemented as builtin commands.
605.LP
606The syntax of the case command is
607.nf
608
609 case word in
610 pattern) list ;;
611 ...
612 esac
613
614.fi
615.LP
616The pattern can actually be one or more patterns (see Shell
617Patterns described later), separated by ``|'' characters.
618
619.LP
620Commands may be grouped by writing either
621.nf
622
623 (list)
624
625.fi
626or
627.nf
628
629 { list; }
630
631.fi
632The first of these executes the commands in a subshell.
633.sp 2
634.B Functions
635.sp
636.LP
637The syntax of a function definition is
638.nf
639
640 name ( ) command
641
642.fi
643.LP
644A function definition is an executable statement; when
645executed it installs a function named name and returns an
646exit status of zero. The command is normally a list
647enclosed between ``{'' and ``}''.
648.LP
649Variables may be declared to be local to a function by
650using a local command. This should appear as the first
651statement of a function, and the syntax is
652.nf
653
654 local [ variable | - ] ...
655
656.fi
657Local is implemented as a builtin command.
658.LP
659When a variable is made local, it inherits the initial
660value and exported and readonly flags from the variable
661with the same name in the surrounding scope, if there is
662one. Otherwise, the variable is initially unset. The shell
663uses dynamic scoping, so that if you make the variable x
664local to function f, which then calls function g, references
665to the variable x made inside g will refer to the
666variable x declared inside f, not to the global variable
667named x.
668.LP
669The only special parameter than can be made local is
670``-''. Making ``-'' local any shell options that are
671changed via the set command inside the function to be
672restored to their original values when the function
673returns.
674.LP
675The syntax of the return command is
676.nf
677
678 return [ exitstatus ]
679
680.fi
681It terminates the currently executing function. Return is
682implemented as a builtin command.
683.sp 2
684.B Variables and Parameters
685.sp
686.LP
687The shell maintains a set of parameters. A parameter
688denoted by a name is called a variable. When starting up,
689the shell turns all the environment variables into shell
690variables. New variables can be set using the form
691.nf
692
693 name=value
694
695.fi
696.LP
697Variables set by the user must have a name consisting solely
698of alphabetics, numerics, and underscores - the first of which
699must not be numeric. A parameter can also be denoted by a number
700or a special character as explained below.
701.sp 2
702.B Positional Parameters
703.sp
704.LP
705A positional parameter is a parameter denoted by a number (n > 0).
706The shell sets these initially to the values of its command
707line arguments that follow the name of the shell script.
708The set(1) builtin can also be used to set or reset them.
709.sp 2
710.B Special Parameters
711.sp
712.LP
713A special parameter is a parameter denoted by one of the following
714special characters. The value of the parameter is listed
715next to its character.
716.TP
717*
718Expands to the positional parameters, starting from one. When
719the expansion occurs within a double-quoted string
720it expands to a single field with the value of each parameter
721separated by the first character of the IFS variable, or by a
722<space> if IFS is unset.
723.TP
724@
725Expands to the positional parameters, starting from one. When
726the expansion occurs within double-quotes, each positional
727parameter expands as a separate argument.
728If there are no positional parameters, the
729expansion of @ generates zero arguments, even when @ is
730double-quoted. What this basically means, for example, is
731if $1 is ``abc'' and $2 is ``def ghi'', then "$@" expands to
732the two arguments:
733
734"abc" "def ghi"
735.TP
736#
737Expands to the number of positional parameters.
738.TP
739?
740Expands to the exit status of the most recent pipeline.
741.TP
742- (Hyphen)
743Expands to the current option flags (the single-letter
744option names concatenated into a string) as specified on
745invocation, by the set builtin command, or implicitly
746by the shell.
747.TP
748$
749Expands to the process ID of the invoked shell. A subshell
750retains the same value of $ as its parent.
751.TP
752!
753Expands to the process ID of the most recent background
754command executed from the current shell. For a
755pipeline, the process ID is that of the last command in the
756pipeline.
757.TP
7580 (Zero.)
759Expands to the name of the shell or shell script.
760.LP
761.sp 2
762.B Word Expansions
763.sp
764.LP
765This clause describes the various expansions that are
766performed on words. Not all expansions are performed on
767every word, as explained later.
768.LP
769Tilde expansions, parameter expansions, command substitutions,
770arithmetic expansions, and quote removals that occur within
771a single word expand to a single field. It is only field
772splitting or pathname expansion that can create multiple
773fields from a single word. The single exception to this
774rule is the expansion of the special parameter @ within
775double-quotes, as was described above.
776.LP
777The order of word expansion is:
778.LP
779(1) Tilde Expansion, Parameter Expansion, Command Substitution,
780Arithmetic Expansion (these all occur at the same time).
781.LP
782(2) Field Splitting is performed on fields
783generated by step (1) unless the IFS variable is null.
784.LP
785(3) Pathname Expansion (unless set -f is in effect).
786.LP
787(4) Quote Removal.
788.LP
789The $ character is used to introduce parameter expansion, command
790substitution, or arithmetic evaluation.
791.sp 2
792.B Tilde Expansion (substituting a user's home directory)
793.sp
794.LP
795A word beginning with an unquoted tilde character (~) is
796subjected to tilde expansion. All the characters up to
797a slash (/) or the end of the word are treated as a username
798and are replaced with the user's home directory. If the
799username is missing (as in ~/foobar), the tilde is replaced
800with the value of the HOME variable (the current user's
801home directory).
802
803.sp 2
804.B Parameter Expansion
805.sp
806.LP
807The format for parameter expansion is as follows:
808.nf
809
810 ${expression}
811
812.fi
813where expression consists of all characters until the matching }. Any }
814escaped by a backslash or within a quoted string, and characters in
815embedded arithmetic expansions, command substitutions, and variable
816expansions, are not examined in determining the matching }.
817.LP
818The simplest form for parameter expansion is:
819.nf
820
821 ${parameter}
822
823.fi
824The value, if any, of parameter is substituted.
825.LP
826The parameter name or symbol can be enclosed in braces, which are
827optional except for positional parameters with more than one digit or
828when parameter is followed by a character that could be interpreted as
829part of the name.
830If a parameter expansion occurs inside
831double-quotes:
832.LP
8331) Pathname expansion is not performed on the results of the
834expansion.
835.LP
8362) Field splitting is not performed on the results of the
837expansion, with the exception of @.
838.LP
839In addition, a parameter expansion can be modified by using one of the
840following formats.
841.sp
842.TP
843${parameter:-word}
844Use Default Values. If parameter is unset or
845null, the expansion of word is
846substituted; otherwise, the value of
847parameter is substituted.
848.TP
849${parameter:=word}
850Assign Default Values. If parameter is unset
851or null, the expansion of word is
852assigned to parameter. In all cases, the
853final value of parameter is
854substituted. Only variables, not positional
855parameters or special parameters, can be
856assigned in this way.
857.TP
858${parameter:?[word]}
859Indicate Error if Null or Unset. If
860parameter is unset or null, the expansion of
861word (or a message indicating it is unset if
862word is omitted) is written to standard
863error and the shell exits with a nonzero
864exit status. Otherwise, the value of
865parameter is substituted. An
866interactive shell need not exit.
867.TP
868${parameter:+word}
869Use Alternate Value. If parameter is unset
870or null, null is substituted;
871otherwise, the expansion of word is
872substituted.
873.LP
874In the parameter expansions shown previously, use of the colon in the
875format results in a test for a parameter that is unset or null; omission
876of the colon results in a test for a parameter that is only unset.
877.TP
878${#parameter}
879String Length. The length in characters of
880the value of parameter.
881.LP
882The following four varieties of parameter expansion provide for substring
883processing. In each case, pattern matching notation (see Shell Patterns), rather
884than regular expression notation, is used to evaluate the patterns.
885If parameter is * or @, the result of the expansion is unspecified.
886Enclosing the full parameter expansion string in double-quotes does not
887cause the following four varieties of pattern characters to be quoted,
888whereas quoting characters within the braces has this effect.
889(UNIMPLEMENTED IN 4.4alpha)
890.TP
891${parameter%word}
892Remove Smallest Suffix Pattern. The word
893is expanded to produce a pattern. The
894parameter expansion then results in
895parameter, with the smallest portion of the
896suffix matched by the pattern deleted.
897
898.TP
899${parameter%%word}
900Remove Largest Suffix Pattern. The word
901is expanded to produce a pattern. The
902parameter expansion then results in
903parameter, with the largest portion of the
904suffix matched by the pattern deleted.
905.TP
906${parameter#word}
907Remove Smallest Prefix Pattern. The word
908is expanded to produce a pattern. The
909parameter expansion then results in
910parameter, with the smallest portion of the
911prefix matched by the pattern deleted.
912.TP
913${parameter##word}
914Remove Largest Prefix Pattern. The word
915is expanded to produce a pattern. The
916parameter expansion then results in
917parameter, with the largest portion of the
918prefix matched by the pattern deleted.
919.LP
920.sp 2
921.B Command Substitution
922.sp
923.LP
924Command substitution allows the output of a command to be substituted in
925place of the command name itself. Command substitution occurs when
926the command is enclosed as follows:
927.nf
928
929 $(command)
930
931.fi
932or (``backquoted'' version):
933.nf
934
935 `command`
936
937.fi
938.LP
939The shell expands the command substitution by executing command in a
940subshell environment and replacing the command substitution
941with the
942standard output of the command, removing sequences of one or more
943<newline>s at the end of the substitution. (Embedded <newline>s before
944the end of the output are not removed; however, during field
945splitting, they may be translated into <space>s, depending on the value
946of IFS and quoting that is in effect.)
947
948.sp 2
949.B Arithmetic Expansion
950.sp
951.LP
952Arithmetic expansion provides a mechanism for evaluating an arithmetic
953expression and substituting its value. The format for arithmetic
954expansion is as follows:
955.nf
956
957 $((expression))
958
959.fi
960The expression is treated as if it were in double-quotes, except
961that a double-quote inside the expression is not treated specially. The
962shell expands all tokens in the expression for parameter expansion,
963command substitution, and quote removal.
964.LP
965Next, the shell treats this as an arithmetic expression and
966substitutes the value of the expression.
967
968.sp 2
969.B White Space Splitting (Field Splitting)
970.sp
971.LP
972After parameter expansion, command substitution, and
973arithmetic expansion the shell scans the results of
974expansions and substitutions that did not occur in double-quotes for
975field splitting and multiple fields can result.
976.LP
977The shell treats each character of the IFS as a delimiter and use
978the delimiters to split the results of parameter expansion and command
979substitution into fields.
980
981.sp 2
982.B Pathname Expansion (File Name Generation)
983.sp
984.LP
985Unless the -f flag is set, file name generation is performed after word splitting is complete. Each word is
986viewed as a series of patterns, separated by slashes. The
987process of expansion replaces the word with the names of
988all existing files whose names can be formed by replacing
989each pattern with a string that matches the specified pattern.
990There are two restrictions on this: first, a pattern cannot match a string containing a slash, and second,
991a pattern cannot match a string starting with a period
992unless the first character of the pattern is a period.
993The next section describes the patterns used for both
994Pathname Expansion and the case(1) command.
995
996.sp 2
997.B Shell Patterns
998.sp
999.LP
1000A pattern consists of normal characters, which match themselves,
1001and meta-characters. The meta-characters are
1002``!'', ``*'', ``?'', and ``[''. These characters lose
1003their special meanings if they are quoted. When command
1004or variable substitution is performed and the dollar sign
1005or back quotes are not double quoted, the value of the
1006variable or the output of the command is scanned for these
1007characters and they are turned into meta-characters.
1008.LP
1009An asterisk (``*'') matches any string of characters. A
1010question mark matches any single character. A left
1011bracket (``['') introduces a character class. The end of
1012the character class is indicated by a ``]''; if the ``]''
1013is missing then the ``['' matches a ``['' rather than
1014introducing a character class. A character class matches
1015any of the characters between the square brackets. A
1016range of characters may be specified using a minus sign.
1017The character class may be complemented by making an
1018exclamation point the first character of the character
1019class.
1020.LP
1021To include a ``]'' in a character class, make it the first
1022character listed (after the ``!'', if any). To include a
1023minus sign, make it the first or last character listed
1024
1025.sp 2
1026.B Builtins
1027.sp
1028.LP
1029This section lists the builtin commands which
1030are builtin because they need to perform some operation
1031that can't be performed by a separate process. In addition
1032to these, there are several other commands that may
1033be builtin for efficiency (e.g. printf(1), echo(1), test(1),
1034etc).
1035.TP
1036:
1037A null command that returns a 0 (true) exit value.
1038.TP
1039\&. file
1040The commands in the specified file are read and executed by the shell.
1041.TP
1042alias [ name[=string] ... ]
1043If name=string is specified, the shell defines the
1044alias ``name'' with value ``string''. If just ``name''
1045is specified, the value of the alias ``name'' is printed.
1046With no arguments, the alias builtin prints the
1047names and values of all defined aliases (see unalias).
1048.TP
1049bg [ job ] ...
1050Continue the specified jobs (or the current job if no
1051jobs are given) in the background.
1052.TP
1053command command arg...
1054Execute the specified builtin command. (This is useful
1055when you have a shell function with the same name
1056as a builtin command.)
1057.TP
1058cd [ directory ]
1059Switch to the specified directory (default $HOME).
1060If the an entry for CDPATH appears in the environment
1061of the cd command or the shell variable CDPATH is set
1062and the directory name does not begin with a slash,
1063then the directories listed in CDPATH will be
1064searched for the specified directory. The format of
1065CDPATH is the same as that of PATH. In an interactive shell, the cd command will print out the name of
1066the directory that it actually switched to if this is
1067different from the name that the user gave. These
1068may be different either because the CDPATH mechanism
1069was used or because a symbolic link was crossed.
1070.TP
1071eval string...
1072Concatenate all the arguments with spaces. Then
1073re-parse and execute the command.
1074.TP
1075exec [ command arg... ]
1076Unless command is omitted, the shell process is
1077replaced with the specified program (which must be a
1078real program, not a shell builtin or function). Any
1079redirections on the exec command are marked as permanent, so that they are not undone when the exec command finishes.
1080.TP
1081exit [ exitstatus ]
1082Terminate the shell process. If exitstatus is given
1083it is used as the exit status of the shell; otherwise
1084the exit status of the preceding command is used.
1085.TP
1086export name...
1087The specified names are exported so that they will
1088appear in the environment of subsequent commands.
1089The only way to un-export a variable is to unset it.
1090The shell allows the value of a variable to be set at the
1091same time it is exported by writing
1092.nf
1093
1094 export name=value
1095
1096.fi
1097With no arguments the export command lists the names
1098of all exported variables.
1099.TP
1100fc [-e editor] [first [last]]
1101.TP
1102fc -l [-nr] [first [last]]
1103.TP
1104fc -s [old=new] [first]
1105The fc builtin lists, or edits and re-executes, commands
1106previously entered to an interactive shell.
1107.RS +.5i
1108.TP 2
1109-e editor
1110Use the editor named by editor to edit the commands. The
1111editor string is a command name, subject to search via the
1112PATH variable. The value in the FCEDIT variable
1113is used as a default when -e is not specified. If
1114FCEDIT is null or unset, the value of the EDITOR
1115variable is used. If EDITOR is null or unset,
1116ed(1) is used as the editor.
1117.TP 2
1118-l (ell)
1119List the commands rather than invoking
1120an editor on them. The commands are written in the
1121sequence indicated by the first and last operands, as
1122affected by -r, with each command preceded by the command
1123number.
1124.TP 2
1125-n
1126Suppress command numbers when listing with -l.
1127.TP 2
1128-r
1129Reverse the order of the commands listed (with -l) or
1130edited (with neither -l nor -s).
1131.TP 2
1132-s
1133Re-execute the command without invoking an editor.
1134.TP 2
1135first
1136.TP 2
1137last
1138Select the commands to list or edit. The number of
1139previous commands that can be accessed are determined
1140by the value of the HISTSIZE variable. The value of first
1141or last or both are one of the following:
1142.TP 2
1143[+]number
1144A positive number representing a command
1145number; command numbers can be displayed
1146with the -l option.
1147.TP 2
1148-number
1149A negative decimal number representing the
1150command that was executed number of
1151commands previously. For example, -1 is
1152the immediately previous command.
1153.TP 2
1154string
1155A string indicating the most recently
1156entered command that begins with that
1157string. If the old=new operand is not also
1158specified with -s, the string form of the
1159first operand cannot contain an embedded
1160equal sign.
1161.TP
1162The following environment variables affect the execution of fc:
1163.TP 2
1164FCEDIT
1165Name of the editor to use.
1166.TP 2
1167HISTSIZE
1168The number of previous commands that are accessable.
1169.RE
1170.TP
1171fg [ job ]
1172Move the specified job or the current job to the
1173foreground.
1174.TP
1175getopts optstring var
1176The POSIX getopts command.
1177.TP
1178hash -rv command...
1179The shell maintains a hash table which remembers the
1180locations of commands. With no arguments whatsoever,
1181the hash command prints out the contents of this
1182table. Entries which have not been looked at since
1183the last cd command are marked with an asterisk; it
1184is possible for these entries to be invalid.
1185.sp
1186With arguments, the hash command removes the specified
1187commands from the hash table (unless they are
1188functions) and then locates them. With the -v
1189option, hash prints the locations of the commands as
1190it finds them. The -r option causes the hash command
1191to delete all the entries in the hash table except
1192for functions.
1193.TP
1194jobid [ job ]
1195Print the process id's of the processes in the job.
1196If the job argument is omitted, use the current job.
1197.TP
1198jobs
1199This command lists out all the background processes
1200which are children of the current shell process.
1201.TP
1202pwd
1203Print the current directory. The builtin command may
1204differ from the program of the same name because the
1205builtin command remembers what the current directory
1206is rather than recomputing it each time. This makes
1207it faster. However, if the current directory is
1208renamed, the builtin version of pwd will continue to
1209print the old name for the directory.
1210.TP
1211read [ -p prompt ] [ -e ] variable...
1212The prompt is printed if the -p option is specified
1213and the standard input is a terminal. Then a line is
1214read from the standard input. The trailing newline
1215is deleted from the line and the line is split as
1216described in the section on word splitting above, and
1217the pieces are assigned to the variables in order.
1218If there are more pieces than variables, the remaining
1219pieces (along with the characters in IFS that
1220separated them) are assigned to the last variable.
1221If there are more variables than pieces, the remaining
1222variables are assigned the null string.
1223.sp
1224The -e option causes any backslashes in the input to
1225be treated specially. If a backslash is followed by
1226a newline, the backslash and the newline will be
1227deleted. If a backslash is followed by any other
1228character, the backslash will be deleted and the following
1229character will be treated as though it were
1230not in IFS, even if it is.
1231.TP
1232readonly name...
1233The specified names are marked as read only, so that
1234they cannot be subsequently modified or unset. The shell
1235allows the value of a variable to be set at the same
1236time it is marked read only by writing
1237.TP
1238readonly name=value
1239With no arguments the readonly command lists the
1240names of all read only variables.
1241.TP
1242set [ { -options | +options | -- } ] arg...
1243The set command performs three different functions.
1244.sp
1245With no arguments, it lists the values of all shell
1246variables.
1247.sp
1248If options are given, it sets the specified option
1249flags, or clears them as described in the section
1250called ``Argument List Processing''.
1251.sp
1252The third use of the set command is to set the values
1253of the shell's positional parameters to the specified
1254args. To change the positional parameters without
1255changing any options, use ``--'' as the first argument to set. If no args are present, the set command
1256will clear all the positional parameters (equivalent
1257to executing ``shift $#''.
1258.TP
1259setvar variable value
1260Assigns value to variable. (In general it is better
1261to write variable=value rather than using setvar.
1262Setvar is intended to be used in functions that
1263assign values to variables whose names are passed as
1264parameters.)
1265.TP
1266shift [ n ]
1267Shift the positional parameters n times. A shift
1268sets the value of $1 to the value of $2, the value of
1269$2 to the value of $3, and so on, decreasing the
1270value of $# by one. If there are zero positional
1271parameters, shifting doesn't do anything.
1272.TP
1273trap [ action ] signal...
1274Cause the shell to parse and execute action when any
1275of the specified signals are received. The signals
1276are specified by signal number. Action may be null
1277or omitted; the former causes the specified signal to
1278be ignored and the latter causes the default action
1279to be taken. When the shell forks off a subshell, it
1280resets trapped (but not ignored) signals to the
1281default action. The trap command has no effect on
1282signals that were ignored on entry to the shell.
1283.TP
| 37.\"
38.na
39.TH SH 1
40.SH NAME
41sh \- command interpreter (shell)
42.SH SYNOPSIS
43sh [-/+aCefnuvxIimsVEb] [-/+o longname] [arg ...]
44.SH DESCRIPTION
45.LP
46Sh is the standard command interpreter for the system.
47The current version of sh is in the process of being changed to
48conform with the POSIX 1003.2 and 1003.2a specifications for
49the shell. This version has many features which make it appear
50similar in some respects to the Korn shell, but it is not a Korn
51shell clone (run GNU's bash if you want that). Only features
52designated by POSIX, plus a few Berkeley extensions, are being
53incorporated into this shell. We expect POSIX conformance by the
54time 4.4 BSD is released.
55This man page is not intended to be a tutorial or a complete
56specification of the shell.
57.sp 2
58.B Overview
59.sp
60.LP
61The shell is a command that reads lines from
62either a file or the terminal, interprets them, and
63generally executes other commands. It is the program that is running
64when a user logs into the system (although a user can select
65a different shell with the chsh(1) command).
66The shell
67implements a language that has flow control constructs,
68a macro facility that provides a variety of features in
69addition to data storage, along with built in history and line
70editing capabilities. It incorporates many features to
71aid interactive use and has the advantage that the interpretative
72language is common to both interactive and non-interactive
73use (shell scripts). That is, commands can be typed directly
74to the running shell or can be put into a file and the file
75can be executed directly by the shell.
76.sp 2
77.B Invocation
78.sp
79.LP
80If no args are present and if the standard input of the shell
81is connected to a terminal (or if the -i flag is set), the shell
82is considered an interactive shell. An interactive shell
83generally prompts before each command and handles programming
84and command errors differently (as described below).
85When first starting, the shell inspects argument 0, and
86if it begins with a dash '-', the shell is also considered
87a login shell. This is normally done automatically by the system
88when the user first logs in. A login shell first reads commands
89from the files /etc/profile and .profile if they exist.
90If the environment variable ENV is set on entry to a shell,
91or is set in the .profile of a login shell, the shell next reads
92commands from the file named in ENV. Therefore, a user should
93place commands that are to be executed only at login time in
94the .profile file, and commands that are executed for every
95shell inside the ENV file. To set the ENV variable to some
96file, place the following line in your .profile of your home
97directory
98.nf
99
100 ENV=$HOME/.shinit; export ENV
101
102.fi
103substituting for ``.shinit'' any filename you wish.
104Since the ENV file is read for
105every invocation of the shell, including shell scripts and
106non-interactive shells, the following paradigm is useful
107for restricting commands in the ENV file to interactive invocations.
108Place commands within the ``case'' and ``esac'' below (these
109commands are described later):
110.nf
111
112 case $- in *i*)
113 # commands for interactive use only
114 ...
115 esac
116
117.fi
118If command line arguments besides the options have been
119specified, then the shell treats the first argument as the
120name of a file from which to read commands (a shell script), and
121the remaining arguments are set as the positional parameters
122of the shell ($1, $2, etc). Otherwise, the shell reads commands
123from its standard input.
124.sp 2
125.B Argument List Processing
126.sp
127.LP
128All of the single letter options have a corresponding name
129that can be used as an argument to the '-o' option. The
130set -o name is provided next to the single letter option in
131the description below.
132Specifying a dash ``-'' turns the option on, while using a plus ``+''
133disables the option.
134The following options can be set from the command line or
135with the set(1) builtin (described later).
136.TP
137-a allexport
138Export all variables assigned to.
139(UNIMPLEMENTED for 4.4alpha)
140.TP
141-C noclobber
142Don't overwrite existing files with ``>''.
143(UNIMPLEMENTED for 4.4alpha)
144.TP
145-e errexit
146If not interactive, exit immediately if any
147untested command fails.
148The exit status of a command is considered to be
149explicitly tested if the command is used to control
150an if, elif, while, or until; or if the command is the left
151hand operand of an ``&&'' or ``||'' operator.
152
153.TP
154-f noglob
155Disable pathname expansion.
156.TP
157-n noexec
158If not interactive, read commands but do not
159execute them. This is useful for checking the
160syntax of shell scripts.
161.TP
162-u nounset
163Write a message to standard error when attempting
164to expand a variable that is not set, and if the
165shell is not interactive, exit immediately.
166(UNIMPLEMENTED for 4.4alpha)
167.TP
168-v verbose
169The shell writes its input to standard error
170as it is read. Useful for debugging.
171.TP
172-x xtrace
173Write each command to standard error (preceded
174by a '+ ') before it is executed. Useful for
175debugging.
176.TP
177-I ignoreeof
178Ignore EOF's from input when interactive.
179.TP
180-i interactive
181Force the shell to behave interactively.
182.TP
183-m monitor
184Turn on job control (set automatically when
185interactive).
186.TP
187-s stdin
188Read commands from standard input (set automatically
189if no file arguments are present). This option has
190no effect when set after the shell has already started
191running (i.e. with set(1)).
192.TP
193-V vi
194Enable the builtin vi(1) command line editor (disables
195-E if it has been set).
196.TP
197-E emacs
198Enable the builtin emacs(1) command line editor (disables
199-V if it has been set).
200.TP
201-b notify
202Enable asynchronous notification of background job
203completion.
204(UNIMPLEMENTED for 4.4alpha)
205.LP
206.sp 2
207.B Lexical Structure
208.sp
209.LP
210The shell reads input in terms of lines from a file and breaks
211it up into words at whitespace (blanks and tabs), and at
212certain sequences of
213characters that are special to the shell called ``operators''.
214There are two types of operators: control operators and
215redirection operators (their meaning is discussed later).
216Following is a list of operators:
217.nf
218.sp
219Control operators: & && ( ) ; ;; | || <newline>
220.sp
221Redirection operator: < > >| << >> <& >& <<- <>
222.sp
223.fi
224.sp 2
225.B Quoting
226.sp
227.LP
228Quoting is used to remove the special meaning of certain characters
229or words to the shell, such as operators, whitespace, or
230keywords. There are three types of quoting: matched single quotes,
231matched double quotes, and backslash.
232.sp 2
233.B Backslash
234.sp
235.LP
236A backslash preserves the literal meaning of the following
237character, with the exception of <newline>. A backslash preceding
238a <newline> is treated as a line continuation.
239.sp 2
240.B Single Quotes
241.sp
242.LP
243Enclosing characters in single quotes preserves the literal
244meaning of all the characters.
245.sp 2
246.B Double Quotes
247.sp
248.LP
249Enclosing characters within double quotes preserves the literal
250meaning of all characters except dollarsign ($), backquote (`),
251and backslash (\\). The backslash inside double quotes is
252historically weird, and serves to quote only the following
253characters: $ ` " \\ <newline>.
254Otherwise it remains literal.
255.sp 2
256.B Reserved Words
257.sp
258.LP
259Reserved words are words that have special meaning to the
260shell and are recognized at the beginning of a line and
261after a control operator. The following are reserved words:
262.nf
263
264 ! elif fi while case
265 else for then { }
266 do done until if esac
267
268.fi
269Their meaning is discussed later.
270.sp 2
271.B Aliases
272.sp
273.LP
274An alias is a name and corresponding value set using the alias(1)
275builtin command. Whenever a reserved word may occur (see above),
276and after checking for reserved words, the shell
277checks the word to see if it matches an alias. If it does,
278it replaces it in the input stream with its value. For example,
279if there is an alias called ``lf'' with the value ``ls -F'',
280then the input
281.nf
282
283 lf foobar <return>
284
285 would become
286
287 ls -F foobar <return>
288
289.fi
290.LP
291Aliases provide a convenient way for naive users to
292create shorthands for commands without having to learn how
293to create functions with arguments. They can also be
294used to create lexically obscure code. This use is discouraged.
295.sp 2
296.B Commands
297.sp
298.LP
299The shell interprets the words it reads according to a
300language, the specification of which is outside the scope
301of this man page (refer to the BNF in the POSIX 1003.2
302document). Essentially though, a line is read and if
303the first word of the line (or after a control operator)
304is not a reserved word, then the shell has recognized a
305simple command. Otherwise, a complex command or some
306other special construct may have been recognized.
307.sp 2
308.B Simple Commands
309.sp
310.LP
311If a simple command has been recognized, the shell performs
312the following actions:
313.sp
3141) Leading words of the form ``name=value'' are
315stripped off and assigned to the environment of
316the simple command. Redirection operators and
317their arguments (as described below) are stripped
318off and saved for processing.
319.sp
3202) The remaining words are expanded as described in
321the section called ``Expansions'', and the
322first remaining word is considered the command
323name and the command is located. The remaining
324words are considered the arguments of the command.
325If no command name resulted, then the ``name=value''
326variable assignments recognized in 1) affect the
327current shell.
328.sp
3293) Redirections are performed as described in
330the next section.
331.sp 2
332.B Redirections
333.sp
334.LP
335Redirections are used to change where a command reads its input
336or sends its output. In general, redirections open, close, or
337duplicate an existing reference to a file. The overall format
338used for redirection is:
339.nf
340
341 [n] redir-op file
342
343.fi
344where redir-op is one of the redirection operators mentioned
345previously. Following is a list of the possible redirections.
346The [n] is an optional number, as in '3' (not '[3]'), that
347refers to a file descriptor.
348.TP
349[n]> file
350Redirect standard output (or n) to file.
351.TP
352[n]>| file
353Same, but override the -C option.
354.TP
355[n]>> file
356Append standard output (or n) to file.
357.TP
358[n]< file
359Redirect standard input (or n) from file.
360.TP
361[n1]<&n2
362Duplicate standard input (or n1) from
363file descriptor n2.
364.TP
365[n]<&-
366Close standard input (or n).
367.TP
368[n1]>&n2
369Duplicate standard output (or n) from
370n2.
371.TP
372[n]>&-
373Close standard output (or n).
374.TP
375[n]<> file
376Open file for reading and writing on
377standard input (or n).
378.LP
379The following redirection is often called a ``here-document''.
380.nf
381
382 [n]<< delimiter
383 here-doc-text...
384 delimiter
385
386.fi
387All the text on successive lines up to the delimiter is
388saved away and made available to the command on standard
389input, or file descriptor n if it is specified. If the delimiter
390as specified on the initial line is quoted, then the here-doc-text
391is treated literally, otherwise the text is subjected to
392parameter expansion, command substitution, and arithmetic
393expansion (as described in the section on ``Expansions''). If
394the operator is ``<<-'' instead of ``<<'', then leading tabs
395in the here-doc-text are stripped.
396.sp 2
397.B Search and Execution
398.sp
399.LP
400There are three types of commands: shell functions, builtin commands, and normal programs -- and the
401command is searched for (by name) in that order. They
402each are executed in a different way.
403.LP
404When a shell function is executed, all of the shell positional parameters (except $0, which remains unchanged) are
405set to the arguments of the shell function.
406The variables which are explicitly placed in the environment of
407the command (by placing assignments to them before the
408function name) are made local to the function and are set
409to the values given. Then the command given in the function
410definition is executed. The positional parameters are
411restored to their original values when the command completes.
412.LP
413Shell builtins are executed internally to the shell, without spawning a new process.
414.LP
415Otherwise, if the command name doesn't match a function
416or builtin, the command is searched for as a normal
417program in the filesystem (as described in the next section).
418When a normal program is executed, the shell runs the program,
419passing the arguments and the environment to the
420program. If the program is a shell procedure, the shell
421will interpret the program in a subshell. The shell will
422reinitialize itself in this case, so that the effect will
423be as if a new shell had been invoked to handle the shell
424procedure, except that the location of commands located in
425the parent shell will be remembered by the child.
426.sp 2
427.B Path Search
428.sp
429.LP
430When locating a command, the shell first looks to see if
431it has a shell function by that name. Then it looks for a
432builtin command by that name.
433Finally, it searches each
434entry in PATH in turn for the command.
435.LP
436The value of the PATH variable should be a series of
437entries separated by colons. Each entry consists of a
438directory name.
439The current directory
440may be indicated by an empty directory name.
441.LP
442Command names containing a slash are simply executed without performing any of the above searches.
443.sp 2
444.B Command Exit Status
445.sp
446.LP
447Each command has an exit status that can influence the behavior
448of other shell commands. The paradigm is that a command exits
449with zero for normal or success, and non-zero for failure,
450error, or a false indication. The man page for each command
451should indicate the various exit codes and what they mean.
452Additionally, the builtin commands return exit codes, as does
453an executed function.
454.sp 2
455.B Complex Commands
456.sp
457.LP
458Complex commands are combinations of simple commands
459with control operators or reserved words, together creating a larger complex
460command. More generally, a command is one of the following:
461.nf
462
463 - simple command
464
465 - pipeline
466
467 - list or compound-list
468
469 - compound command
470
471 - function definition
472
473.fi
474.LP
475Unless otherwise stated, the exit status of a command is
476that of the last simple command executed by the command.
477.sp 2
478.B Pipeline
479.sp
480.LP
481A pipeline is a sequence of one or more commands separated
482by the control operator |. The standard output of all but
483the last command is connected to the standard input
484of the next command.
485.LP
486The format for a pipeline is:
487.nf
488
489[!] command1 [ | command2 ...]
490
491.fi
492.LP
493The standard output of command1 is connected to the standard
494input of command2. The standard input, standard output, or
495both of a command is considered to be assigned by the
496pipeline before any redirection specified by redirection
497operators that are part of the command.
498.LP
499If the pipeline is not in the background (discussed later),
500the shell waits for all commands to complete.
501.LP
502If the reserved word ! does not precede the pipeline, the
503exit status is the exit status of the last command specified
504in the pipeline. Otherwise, the exit status is the logical
505NOT of the exit status of the last command. That is, if
506the last command returns zero, the exit status is 1; if
507the last command returns greater than zero, the exit status
508is zero.
509.LP
510Because pipeline assignment of standard input or standard
511output or both takes place before redirection, it can be
512modified by redirection. For example:
513.nf
514
515$ command1 2>&1 | command2
516
517.fi
518sends both the standard output and standard error of command1
519to the standard input of command2.
520.LP
521A ; or <newline> terminator causes the preceding
522AND-OR-list (described next) to be executed sequentially; a & causes
523asynchronous execution of the preceding AND-OR-list.
524.sp 2
525.B Background Commands -- &
526.sp
527.LP
528If a command is terminated by the control operator ampersand
529(&), the shell executes the command asynchronously -- that is,
530the shell does not wait for
531the command to finish before executing the next command.
532.LP
533The format for running a command in background is:
534.nf
535
536command1 & [command2 & ...]
537
538.fi
539If the shell is not interactive, the standard input of an
540asynchronous command is set to /dev/null.
541.sp 2
542.B Lists -- Generally Speaking
543.sp
544.LP
545A list is a sequence of zero or more commands separated by
546newlines, semicolons, or ampersands,
547and optionally terminated by one of these three characters.
548The commands in a
549list are executed in the order they are written.
550If command is followed by an ampersand, the shell starts the
551command and immediately proceed onto the next command;
552otherwise it waits for the command to terminate before
553proceeding to the next one.
554.LP
555``&&'' and ``||'' are AND-OR list operators. ``&&'' executes
556the first command, and then executes the second command
557iff the exit status of the first command is zero. ``||''
558is similar, but executes the second command iff the exit
559status of the first command is nonzero. ``&&'' and ``||''
560both have the same priority.
561.LP
562The syntax of the if command is
563.nf
564
565 if list
566 then list
567 [ elif list
568 then list ] ...
569 [ else list ]
570 fi
571
572.fi
573The syntax of the while command is
574.nf
575
576 while list
577 do list
578 done
579
580.fi
581The two lists are executed repeatedly while the exit status of the first list is zero. The until command is similar, but has the word until in place of while
582repeat until the exit status of the first list is zero.
583.LP
584The syntax of the for command is
585.nf
586
587 for variable in word...
588 do list
589 done
590
591.fi
592The words are expanded, and then the list is executed
593repeatedly with the variable set to each word in turn. do
594and done may be replaced with ``{'' and ``}''.
595.LP
596The syntax of the break and continue command is
597.nf
598
599 break [ num ]
600 continue [ num ]
601
602.fi
603Break terminates the num innermost for or while loops.
604Continue continues with the next iteration of the innermost loop. These are implemented as builtin commands.
605.LP
606The syntax of the case command is
607.nf
608
609 case word in
610 pattern) list ;;
611 ...
612 esac
613
614.fi
615.LP
616The pattern can actually be one or more patterns (see Shell
617Patterns described later), separated by ``|'' characters.
618
619.LP
620Commands may be grouped by writing either
621.nf
622
623 (list)
624
625.fi
626or
627.nf
628
629 { list; }
630
631.fi
632The first of these executes the commands in a subshell.
633.sp 2
634.B Functions
635.sp
636.LP
637The syntax of a function definition is
638.nf
639
640 name ( ) command
641
642.fi
643.LP
644A function definition is an executable statement; when
645executed it installs a function named name and returns an
646exit status of zero. The command is normally a list
647enclosed between ``{'' and ``}''.
648.LP
649Variables may be declared to be local to a function by
650using a local command. This should appear as the first
651statement of a function, and the syntax is
652.nf
653
654 local [ variable | - ] ...
655
656.fi
657Local is implemented as a builtin command.
658.LP
659When a variable is made local, it inherits the initial
660value and exported and readonly flags from the variable
661with the same name in the surrounding scope, if there is
662one. Otherwise, the variable is initially unset. The shell
663uses dynamic scoping, so that if you make the variable x
664local to function f, which then calls function g, references
665to the variable x made inside g will refer to the
666variable x declared inside f, not to the global variable
667named x.
668.LP
669The only special parameter than can be made local is
670``-''. Making ``-'' local any shell options that are
671changed via the set command inside the function to be
672restored to their original values when the function
673returns.
674.LP
675The syntax of the return command is
676.nf
677
678 return [ exitstatus ]
679
680.fi
681It terminates the currently executing function. Return is
682implemented as a builtin command.
683.sp 2
684.B Variables and Parameters
685.sp
686.LP
687The shell maintains a set of parameters. A parameter
688denoted by a name is called a variable. When starting up,
689the shell turns all the environment variables into shell
690variables. New variables can be set using the form
691.nf
692
693 name=value
694
695.fi
696.LP
697Variables set by the user must have a name consisting solely
698of alphabetics, numerics, and underscores - the first of which
699must not be numeric. A parameter can also be denoted by a number
700or a special character as explained below.
701.sp 2
702.B Positional Parameters
703.sp
704.LP
705A positional parameter is a parameter denoted by a number (n > 0).
706The shell sets these initially to the values of its command
707line arguments that follow the name of the shell script.
708The set(1) builtin can also be used to set or reset them.
709.sp 2
710.B Special Parameters
711.sp
712.LP
713A special parameter is a parameter denoted by one of the following
714special characters. The value of the parameter is listed
715next to its character.
716.TP
717*
718Expands to the positional parameters, starting from one. When
719the expansion occurs within a double-quoted string
720it expands to a single field with the value of each parameter
721separated by the first character of the IFS variable, or by a
722<space> if IFS is unset.
723.TP
724@
725Expands to the positional parameters, starting from one. When
726the expansion occurs within double-quotes, each positional
727parameter expands as a separate argument.
728If there are no positional parameters, the
729expansion of @ generates zero arguments, even when @ is
730double-quoted. What this basically means, for example, is
731if $1 is ``abc'' and $2 is ``def ghi'', then "$@" expands to
732the two arguments:
733
734"abc" "def ghi"
735.TP
736#
737Expands to the number of positional parameters.
738.TP
739?
740Expands to the exit status of the most recent pipeline.
741.TP
742- (Hyphen)
743Expands to the current option flags (the single-letter
744option names concatenated into a string) as specified on
745invocation, by the set builtin command, or implicitly
746by the shell.
747.TP
748$
749Expands to the process ID of the invoked shell. A subshell
750retains the same value of $ as its parent.
751.TP
752!
753Expands to the process ID of the most recent background
754command executed from the current shell. For a
755pipeline, the process ID is that of the last command in the
756pipeline.
757.TP
7580 (Zero.)
759Expands to the name of the shell or shell script.
760.LP
761.sp 2
762.B Word Expansions
763.sp
764.LP
765This clause describes the various expansions that are
766performed on words. Not all expansions are performed on
767every word, as explained later.
768.LP
769Tilde expansions, parameter expansions, command substitutions,
770arithmetic expansions, and quote removals that occur within
771a single word expand to a single field. It is only field
772splitting or pathname expansion that can create multiple
773fields from a single word. The single exception to this
774rule is the expansion of the special parameter @ within
775double-quotes, as was described above.
776.LP
777The order of word expansion is:
778.LP
779(1) Tilde Expansion, Parameter Expansion, Command Substitution,
780Arithmetic Expansion (these all occur at the same time).
781.LP
782(2) Field Splitting is performed on fields
783generated by step (1) unless the IFS variable is null.
784.LP
785(3) Pathname Expansion (unless set -f is in effect).
786.LP
787(4) Quote Removal.
788.LP
789The $ character is used to introduce parameter expansion, command
790substitution, or arithmetic evaluation.
791.sp 2
792.B Tilde Expansion (substituting a user's home directory)
793.sp
794.LP
795A word beginning with an unquoted tilde character (~) is
796subjected to tilde expansion. All the characters up to
797a slash (/) or the end of the word are treated as a username
798and are replaced with the user's home directory. If the
799username is missing (as in ~/foobar), the tilde is replaced
800with the value of the HOME variable (the current user's
801home directory).
802
803.sp 2
804.B Parameter Expansion
805.sp
806.LP
807The format for parameter expansion is as follows:
808.nf
809
810 ${expression}
811
812.fi
813where expression consists of all characters until the matching }. Any }
814escaped by a backslash or within a quoted string, and characters in
815embedded arithmetic expansions, command substitutions, and variable
816expansions, are not examined in determining the matching }.
817.LP
818The simplest form for parameter expansion is:
819.nf
820
821 ${parameter}
822
823.fi
824The value, if any, of parameter is substituted.
825.LP
826The parameter name or symbol can be enclosed in braces, which are
827optional except for positional parameters with more than one digit or
828when parameter is followed by a character that could be interpreted as
829part of the name.
830If a parameter expansion occurs inside
831double-quotes:
832.LP
8331) Pathname expansion is not performed on the results of the
834expansion.
835.LP
8362) Field splitting is not performed on the results of the
837expansion, with the exception of @.
838.LP
839In addition, a parameter expansion can be modified by using one of the
840following formats.
841.sp
842.TP
843${parameter:-word}
844Use Default Values. If parameter is unset or
845null, the expansion of word is
846substituted; otherwise, the value of
847parameter is substituted.
848.TP
849${parameter:=word}
850Assign Default Values. If parameter is unset
851or null, the expansion of word is
852assigned to parameter. In all cases, the
853final value of parameter is
854substituted. Only variables, not positional
855parameters or special parameters, can be
856assigned in this way.
857.TP
858${parameter:?[word]}
859Indicate Error if Null or Unset. If
860parameter is unset or null, the expansion of
861word (or a message indicating it is unset if
862word is omitted) is written to standard
863error and the shell exits with a nonzero
864exit status. Otherwise, the value of
865parameter is substituted. An
866interactive shell need not exit.
867.TP
868${parameter:+word}
869Use Alternate Value. If parameter is unset
870or null, null is substituted;
871otherwise, the expansion of word is
872substituted.
873.LP
874In the parameter expansions shown previously, use of the colon in the
875format results in a test for a parameter that is unset or null; omission
876of the colon results in a test for a parameter that is only unset.
877.TP
878${#parameter}
879String Length. The length in characters of
880the value of parameter.
881.LP
882The following four varieties of parameter expansion provide for substring
883processing. In each case, pattern matching notation (see Shell Patterns), rather
884than regular expression notation, is used to evaluate the patterns.
885If parameter is * or @, the result of the expansion is unspecified.
886Enclosing the full parameter expansion string in double-quotes does not
887cause the following four varieties of pattern characters to be quoted,
888whereas quoting characters within the braces has this effect.
889(UNIMPLEMENTED IN 4.4alpha)
890.TP
891${parameter%word}
892Remove Smallest Suffix Pattern. The word
893is expanded to produce a pattern. The
894parameter expansion then results in
895parameter, with the smallest portion of the
896suffix matched by the pattern deleted.
897
898.TP
899${parameter%%word}
900Remove Largest Suffix Pattern. The word
901is expanded to produce a pattern. The
902parameter expansion then results in
903parameter, with the largest portion of the
904suffix matched by the pattern deleted.
905.TP
906${parameter#word}
907Remove Smallest Prefix Pattern. The word
908is expanded to produce a pattern. The
909parameter expansion then results in
910parameter, with the smallest portion of the
911prefix matched by the pattern deleted.
912.TP
913${parameter##word}
914Remove Largest Prefix Pattern. The word
915is expanded to produce a pattern. The
916parameter expansion then results in
917parameter, with the largest portion of the
918prefix matched by the pattern deleted.
919.LP
920.sp 2
921.B Command Substitution
922.sp
923.LP
924Command substitution allows the output of a command to be substituted in
925place of the command name itself. Command substitution occurs when
926the command is enclosed as follows:
927.nf
928
929 $(command)
930
931.fi
932or (``backquoted'' version):
933.nf
934
935 `command`
936
937.fi
938.LP
939The shell expands the command substitution by executing command in a
940subshell environment and replacing the command substitution
941with the
942standard output of the command, removing sequences of one or more
943<newline>s at the end of the substitution. (Embedded <newline>s before
944the end of the output are not removed; however, during field
945splitting, they may be translated into <space>s, depending on the value
946of IFS and quoting that is in effect.)
947
948.sp 2
949.B Arithmetic Expansion
950.sp
951.LP
952Arithmetic expansion provides a mechanism for evaluating an arithmetic
953expression and substituting its value. The format for arithmetic
954expansion is as follows:
955.nf
956
957 $((expression))
958
959.fi
960The expression is treated as if it were in double-quotes, except
961that a double-quote inside the expression is not treated specially. The
962shell expands all tokens in the expression for parameter expansion,
963command substitution, and quote removal.
964.LP
965Next, the shell treats this as an arithmetic expression and
966substitutes the value of the expression.
967
968.sp 2
969.B White Space Splitting (Field Splitting)
970.sp
971.LP
972After parameter expansion, command substitution, and
973arithmetic expansion the shell scans the results of
974expansions and substitutions that did not occur in double-quotes for
975field splitting and multiple fields can result.
976.LP
977The shell treats each character of the IFS as a delimiter and use
978the delimiters to split the results of parameter expansion and command
979substitution into fields.
980
981.sp 2
982.B Pathname Expansion (File Name Generation)
983.sp
984.LP
985Unless the -f flag is set, file name generation is performed after word splitting is complete. Each word is
986viewed as a series of patterns, separated by slashes. The
987process of expansion replaces the word with the names of
988all existing files whose names can be formed by replacing
989each pattern with a string that matches the specified pattern.
990There are two restrictions on this: first, a pattern cannot match a string containing a slash, and second,
991a pattern cannot match a string starting with a period
992unless the first character of the pattern is a period.
993The next section describes the patterns used for both
994Pathname Expansion and the case(1) command.
995
996.sp 2
997.B Shell Patterns
998.sp
999.LP
1000A pattern consists of normal characters, which match themselves,
1001and meta-characters. The meta-characters are
1002``!'', ``*'', ``?'', and ``[''. These characters lose
1003their special meanings if they are quoted. When command
1004or variable substitution is performed and the dollar sign
1005or back quotes are not double quoted, the value of the
1006variable or the output of the command is scanned for these
1007characters and they are turned into meta-characters.
1008.LP
1009An asterisk (``*'') matches any string of characters. A
1010question mark matches any single character. A left
1011bracket (``['') introduces a character class. The end of
1012the character class is indicated by a ``]''; if the ``]''
1013is missing then the ``['' matches a ``['' rather than
1014introducing a character class. A character class matches
1015any of the characters between the square brackets. A
1016range of characters may be specified using a minus sign.
1017The character class may be complemented by making an
1018exclamation point the first character of the character
1019class.
1020.LP
1021To include a ``]'' in a character class, make it the first
1022character listed (after the ``!'', if any). To include a
1023minus sign, make it the first or last character listed
1024
1025.sp 2
1026.B Builtins
1027.sp
1028.LP
1029This section lists the builtin commands which
1030are builtin because they need to perform some operation
1031that can't be performed by a separate process. In addition
1032to these, there are several other commands that may
1033be builtin for efficiency (e.g. printf(1), echo(1), test(1),
1034etc).
1035.TP
1036:
1037A null command that returns a 0 (true) exit value.
1038.TP
1039\&. file
1040The commands in the specified file are read and executed by the shell.
1041.TP
1042alias [ name[=string] ... ]
1043If name=string is specified, the shell defines the
1044alias ``name'' with value ``string''. If just ``name''
1045is specified, the value of the alias ``name'' is printed.
1046With no arguments, the alias builtin prints the
1047names and values of all defined aliases (see unalias).
1048.TP
1049bg [ job ] ...
1050Continue the specified jobs (or the current job if no
1051jobs are given) in the background.
1052.TP
1053command command arg...
1054Execute the specified builtin command. (This is useful
1055when you have a shell function with the same name
1056as a builtin command.)
1057.TP
1058cd [ directory ]
1059Switch to the specified directory (default $HOME).
1060If the an entry for CDPATH appears in the environment
1061of the cd command or the shell variable CDPATH is set
1062and the directory name does not begin with a slash,
1063then the directories listed in CDPATH will be
1064searched for the specified directory. The format of
1065CDPATH is the same as that of PATH. In an interactive shell, the cd command will print out the name of
1066the directory that it actually switched to if this is
1067different from the name that the user gave. These
1068may be different either because the CDPATH mechanism
1069was used or because a symbolic link was crossed.
1070.TP
1071eval string...
1072Concatenate all the arguments with spaces. Then
1073re-parse and execute the command.
1074.TP
1075exec [ command arg... ]
1076Unless command is omitted, the shell process is
1077replaced with the specified program (which must be a
1078real program, not a shell builtin or function). Any
1079redirections on the exec command are marked as permanent, so that they are not undone when the exec command finishes.
1080.TP
1081exit [ exitstatus ]
1082Terminate the shell process. If exitstatus is given
1083it is used as the exit status of the shell; otherwise
1084the exit status of the preceding command is used.
1085.TP
1086export name...
1087The specified names are exported so that they will
1088appear in the environment of subsequent commands.
1089The only way to un-export a variable is to unset it.
1090The shell allows the value of a variable to be set at the
1091same time it is exported by writing
1092.nf
1093
1094 export name=value
1095
1096.fi
1097With no arguments the export command lists the names
1098of all exported variables.
1099.TP
1100fc [-e editor] [first [last]]
1101.TP
1102fc -l [-nr] [first [last]]
1103.TP
1104fc -s [old=new] [first]
1105The fc builtin lists, or edits and re-executes, commands
1106previously entered to an interactive shell.
1107.RS +.5i
1108.TP 2
1109-e editor
1110Use the editor named by editor to edit the commands. The
1111editor string is a command name, subject to search via the
1112PATH variable. The value in the FCEDIT variable
1113is used as a default when -e is not specified. If
1114FCEDIT is null or unset, the value of the EDITOR
1115variable is used. If EDITOR is null or unset,
1116ed(1) is used as the editor.
1117.TP 2
1118-l (ell)
1119List the commands rather than invoking
1120an editor on them. The commands are written in the
1121sequence indicated by the first and last operands, as
1122affected by -r, with each command preceded by the command
1123number.
1124.TP 2
1125-n
1126Suppress command numbers when listing with -l.
1127.TP 2
1128-r
1129Reverse the order of the commands listed (with -l) or
1130edited (with neither -l nor -s).
1131.TP 2
1132-s
1133Re-execute the command without invoking an editor.
1134.TP 2
1135first
1136.TP 2
1137last
1138Select the commands to list or edit. The number of
1139previous commands that can be accessed are determined
1140by the value of the HISTSIZE variable. The value of first
1141or last or both are one of the following:
1142.TP 2
1143[+]number
1144A positive number representing a command
1145number; command numbers can be displayed
1146with the -l option.
1147.TP 2
1148-number
1149A negative decimal number representing the
1150command that was executed number of
1151commands previously. For example, -1 is
1152the immediately previous command.
1153.TP 2
1154string
1155A string indicating the most recently
1156entered command that begins with that
1157string. If the old=new operand is not also
1158specified with -s, the string form of the
1159first operand cannot contain an embedded
1160equal sign.
1161.TP
1162The following environment variables affect the execution of fc:
1163.TP 2
1164FCEDIT
1165Name of the editor to use.
1166.TP 2
1167HISTSIZE
1168The number of previous commands that are accessable.
1169.RE
1170.TP
1171fg [ job ]
1172Move the specified job or the current job to the
1173foreground.
1174.TP
1175getopts optstring var
1176The POSIX getopts command.
1177.TP
1178hash -rv command...
1179The shell maintains a hash table which remembers the
1180locations of commands. With no arguments whatsoever,
1181the hash command prints out the contents of this
1182table. Entries which have not been looked at since
1183the last cd command are marked with an asterisk; it
1184is possible for these entries to be invalid.
1185.sp
1186With arguments, the hash command removes the specified
1187commands from the hash table (unless they are
1188functions) and then locates them. With the -v
1189option, hash prints the locations of the commands as
1190it finds them. The -r option causes the hash command
1191to delete all the entries in the hash table except
1192for functions.
1193.TP
1194jobid [ job ]
1195Print the process id's of the processes in the job.
1196If the job argument is omitted, use the current job.
1197.TP
1198jobs
1199This command lists out all the background processes
1200which are children of the current shell process.
1201.TP
1202pwd
1203Print the current directory. The builtin command may
1204differ from the program of the same name because the
1205builtin command remembers what the current directory
1206is rather than recomputing it each time. This makes
1207it faster. However, if the current directory is
1208renamed, the builtin version of pwd will continue to
1209print the old name for the directory.
1210.TP
1211read [ -p prompt ] [ -e ] variable...
1212The prompt is printed if the -p option is specified
1213and the standard input is a terminal. Then a line is
1214read from the standard input. The trailing newline
1215is deleted from the line and the line is split as
1216described in the section on word splitting above, and
1217the pieces are assigned to the variables in order.
1218If there are more pieces than variables, the remaining
1219pieces (along with the characters in IFS that
1220separated them) are assigned to the last variable.
1221If there are more variables than pieces, the remaining
1222variables are assigned the null string.
1223.sp
1224The -e option causes any backslashes in the input to
1225be treated specially. If a backslash is followed by
1226a newline, the backslash and the newline will be
1227deleted. If a backslash is followed by any other
1228character, the backslash will be deleted and the following
1229character will be treated as though it were
1230not in IFS, even if it is.
1231.TP
1232readonly name...
1233The specified names are marked as read only, so that
1234they cannot be subsequently modified or unset. The shell
1235allows the value of a variable to be set at the same
1236time it is marked read only by writing
1237.TP
1238readonly name=value
1239With no arguments the readonly command lists the
1240names of all read only variables.
1241.TP
1242set [ { -options | +options | -- } ] arg...
1243The set command performs three different functions.
1244.sp
1245With no arguments, it lists the values of all shell
1246variables.
1247.sp
1248If options are given, it sets the specified option
1249flags, or clears them as described in the section
1250called ``Argument List Processing''.
1251.sp
1252The third use of the set command is to set the values
1253of the shell's positional parameters to the specified
1254args. To change the positional parameters without
1255changing any options, use ``--'' as the first argument to set. If no args are present, the set command
1256will clear all the positional parameters (equivalent
1257to executing ``shift $#''.
1258.TP
1259setvar variable value
1260Assigns value to variable. (In general it is better
1261to write variable=value rather than using setvar.
1262Setvar is intended to be used in functions that
1263assign values to variables whose names are passed as
1264parameters.)
1265.TP
1266shift [ n ]
1267Shift the positional parameters n times. A shift
1268sets the value of $1 to the value of $2, the value of
1269$2 to the value of $3, and so on, decreasing the
1270value of $# by one. If there are zero positional
1271parameters, shifting doesn't do anything.
1272.TP
1273trap [ action ] signal...
1274Cause the shell to parse and execute action when any
1275of the specified signals are received. The signals
1276are specified by signal number. Action may be null
1277or omitted; the former causes the specified signal to
1278be ignored and the latter causes the default action
1279to be taken. When the shell forks off a subshell, it
1280resets trapped (but not ignored) signals to the
1281default action. The trap command has no effect on
1282signals that were ignored on entry to the shell.
1283.TP
|