sh: Add do-nothing -h option.
[dragonfly.git] / bin / sh / sh.1
1 .\"-
2 .\" Copyright (c) 1991, 1993
3 .\"     The Regents of the University of California.  All rights reserved.
4 .\"
5 .\" This code is derived from software contributed to Berkeley by
6 .\" Kenneth Almquist.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\"    notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\"    notice, this list of conditions and the following disclaimer in the
15 .\"    documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\"    must display the following acknowledgement:
18 .\"     This product includes software developed by the University of
19 .\"     California, Berkeley and its contributors.
20 .\" 4. Neither the name of the University nor the names of its contributors
21 .\"    may be used to endorse or promote products derived from this software
22 .\"    without specific prior written permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" SUCH DAMAGE.
35 .\"
36 .\"     from: @(#)sh.1  8.6 (Berkeley) 5/4/95
37 .\" $FreeBSD: src/bin/sh/sh.1,v 1.171 2011/06/18 23:43:28 jilles Exp $
38 .\"
39 .Dd August 21, 2011
40 .Dt SH 1
41 .Os
42 .Sh NAME
43 .Nm sh
44 .Nd command interpreter (shell)
45 .Sh SYNOPSIS
46 .Nm
47 .Op Fl /+abCEefIimnPpTuVvx
48 .Op Fl /+o Ar longname
49 .Oo
50 .Ar script
51 .Op Ar arg ...
52 .Oc
53 .Nm
54 .Op Fl /+abCEefIimnPpTuVvx
55 .Op Fl /+o Ar longname
56 .Fl c Ar string
57 .Oo
58 .Ar name
59 .Op Ar arg ...
60 .Oc
61 .Nm
62 .Op Fl /+abCEefIimnPpTuVvx
63 .Op Fl /+o Ar longname
64 .Fl s
65 .Op Ar arg ...
66 .Sh DESCRIPTION
67 The
68 .Nm
69 utility is the standard command interpreter for the system.
70 The current version of
71 .Nm
72 is close to the
73 .St -p1003.1
74 specification for the shell.
75 It only supports features
76 designated by
77 .Tn POSIX ,
78 plus a few Berkeley extensions.
79 This man page is not intended to be a tutorial nor a complete
80 specification of the shell.
81 .Ss Overview
82 The shell is a command that reads lines from
83 either a file or the terminal, interprets them, and
84 generally executes other commands.
85 It is the program that is started when a user logs into the system,
86 although a user can select a different shell with the
87 .Xr chsh 1
88 command.
89 The shell
90 implements a language that has flow control constructs,
91 a macro facility that provides a variety of features in
92 addition to data storage, along with built-in history and line
93 editing capabilities.
94 It incorporates many features to
95 aid interactive use and has the advantage that the interpretative
96 language is common to both interactive and non-interactive
97 use (shell scripts).
98 That is, commands can be typed directly
99 to the running shell or can be put into a file,
100 which can be executed directly by the shell.
101 .Ss Invocation
102 .\"
103 .\" XXX This next sentence is incredibly confusing.
104 .\"
105 If no arguments are present and if the standard input of the shell
106 is connected to a terminal
107 (or if the
108 .Fl i
109 option is set),
110 the shell is considered an interactive shell.
111 An interactive shell
112 generally prompts before each command and handles programming
113 and command errors differently (as described below).
114 When first starting, the shell inspects argument 0, and
115 if it begins with a dash
116 .Pq Ql - ,
117 the shell is also considered a login shell.
118 This is normally done automatically by the system
119 when the user first logs in.
120 A login shell first reads commands
121 from the files
122 .Pa /etc/profile
123 and then
124 .Pa .profile
125 in a user's home directory,
126 if they exist.
127 If the environment variable
128 .Ev ENV
129 is set on entry to a shell, or is set in the
130 .Pa .profile
131 of a login shell, the shell then subjects its value to parameter expansion
132 and arithmetic expansion and reads commands from the named file.
133 Therefore, a user should place commands that are to be executed only
134 at login time in the
135 .Pa .profile
136 file, and commands that are executed for every shell inside the
137 .Ev ENV
138 file.
139 The user can set the
140 .Ev ENV
141 variable to some file by placing the following line in the file
142 .Pa .profile
143 in the home directory,
144 substituting for
145 .Pa .shinit
146 the filename desired:
147 .Pp
148 .Dl "ENV=$HOME/.shinit; export ENV"
149 .Pp
150 The first non-option argument specified on the command line
151 will be treated as the
152 name of a file from which to read commands (a shell script), and
153 the remaining arguments are set as the positional parameters
154 of the shell
155 .Li ( $1 , $2 ,
156 etc.).
157 Otherwise, the shell reads commands
158 from its standard input.
159 .Pp
160 Unlike older versions of
161 .Nm
162 the
163 .Ev ENV
164 script is only sourced on invocation of interactive shells.
165 This
166 closes a well-known, and sometimes easily exploitable security
167 hole related to poorly thought out
168 .Ev ENV
169 scripts.
170 .Ss Argument List Processing
171 All of the single letter options to
172 .Nm
173 have a corresponding long name,
174 with the exception of
175 .Fl c
176 and
177 .Fl /+o .
178 These long names are provided next to the single letter options
179 in the descriptions below.
180 The long name for an option may be specified as an argument to the
181 .Fl /+o
182 option of
183 .Nm .
184 Once the shell is running,
185 the long name for an option may be specified as an argument to the
186 .Fl /+o
187 option of the
188 .Ic set
189 built-in command
190 (described later in the section called
191 .Sx Built-in Commands ) .
192 Introducing an option with a dash
193 .Pq Ql -
194 enables the option,
195 while using a plus
196 .Pq Ql +
197 disables the option.
198 A
199 .Dq Li --
200 or plain
201 .Ql -
202 will stop option processing and will force the remaining
203 words on the command line to be treated as arguments.
204 The
205 .Fl /+o
206 and
207 .Fl c
208 options do not have long names.
209 They take arguments and are described after the single letter options.
210 .Bl -tag -width indent
211 .It Fl a Li allexport
212 Flag variables for export when assignments are made to them.
213 .It Fl b Li notify
214 Enable asynchronous notification of background job
215 completion.
216 (UNIMPLEMENTED)
217 .It Fl C Li noclobber
218 Do not overwrite existing files with
219 .Ql > .
220 .It Fl E Li emacs
221 Enable the built-in
222 .Xr emacs 1
223 command line editor (disables the
224 .Fl V
225 option if it has been set;
226 set automatically when interactive on terminals).
227 .It Fl e Li errexit
228 Exit immediately if any untested command fails in non-interactive mode.
229 The exit status of a command is considered to be
230 explicitly tested if the command is part of the list used to control
231 an
232 .Ic if , elif , while ,
233 or
234 .Ic until ;
235 if the command is the left
236 hand operand of an
237 .Dq Li &&
238 or
239 .Dq Li ||
240 operator; or if the command is a pipeline preceded by the
241 .Ic !\&
242 operator.
243 If a shell function is executed and its exit status is explicitly
244 tested, all commands of the function are considered to be tested as
245 well.
246 .It Fl f Li noglob
247 Disable pathname expansion.
248 .It Fl h Li trackall
249 A do-nothing option for
250 .Tn POSIX
251 compliance.
252 .It Fl I Li ignoreeof
253 Ignore
254 .Dv EOF Ap s
255 from input when in interactive mode.
256 .It Fl i Li interactive
257 Force the shell to behave interactively.
258 .It Fl m Li monitor
259 Turn on job control (set automatically when interactive).
260 .It Fl n Li noexec
261 If not interactive, read commands but do not
262 execute them.
263 This is useful for checking the
264 syntax of shell scripts.
265 .It Fl P Li physical
266 Change the default for the
267 .Ic cd
268 and
269 .Ic pwd
270 commands from
271 .Fl L
272 (logical directory layout)
273 to
274 .Fl P
275 (physical directory layout).
276 .It Fl p Li privileged
277 Turn on privileged mode.
278 This mode is enabled on startup
279 if either the effective user or group ID is not equal to the
280 real user or group ID.
281 Turning this mode off sets the
282 effective user and group IDs to the real user and group IDs.
283 When this mode is enabled for interactive shells, the file
284 .Pa /etc/suid_profile
285 is sourced instead of
286 .Pa ~/.profile
287 after
288 .Pa /etc/profile
289 is sourced, and the contents of the
290 .Ev ENV
291 variable are ignored.
292 .It Fl s Li stdin
293 Read commands from standard input (set automatically
294 if no file arguments are present).
295 This option has
296 no effect when set after the shell has already started
297 running (i.e., when set with the
298 .Ic set
299 command).
300 .It Fl T Li trapsasync
301 When waiting for a child, execute traps immediately.
302 If this option is not set,
303 traps are executed after the child exits,
304 as specified in
305 .St -p1003.2 .
306 This nonstandard option is useful for putting guarding shells around
307 children that block signals.
308 The surrounding shell may kill the child
309 or it may just return control to the tty and leave the child alone,
310 like this:
311 .Bd -literal -offset indent
312 sh -T -c "trap 'exit 1' 2 ; some-blocking-program"
313 .Ed
314 .It Fl u Li nounset
315 Write a message to standard error when attempting
316 to expand a variable, a positional parameter or
317 the special parameter
318 .Va \&!
319 that is not set, and if the
320 shell is not interactive, exit immediately.
321 .It Fl V Li vi
322 Enable the built-in
323 .Xr vi 1
324 command line editor (disables
325 .Fl E
326 if it has been set).
327 .It Fl v Li verbose
328 The shell writes its input to standard error
329 as it is read.
330 Useful for debugging.
331 .It Fl x Li xtrace
332 Write each command
333 (preceded by the value of the
334 .Va PS4
335 variable subjected to parameter expansion and arithmetic expansion)
336 to standard error before it is executed.
337 Useful for debugging.
338 .It "\ \ " Em tabcomplete
339 Enables filename completion in the command line editor.
340 Typing a tab character will extend the current input word to match a
341 filename.
342 If more than one filename matches it is only extended to be the common prefix.
343 Typing a second tab character will list all the matching names.
344 Turned on by default in an interactive shell.
345 .El
346 .Pp
347 The
348 .Fl c
349 option causes the commands to be read from the
350 .Ar string
351 operand instead of from the standard input.
352 Keep in mind that this option only accepts a single string as its
353 argument, hence multi-word strings must be quoted.
354 .Pp
355 The
356 .Fl /+o
357 option takes as its only argument the long name of an option
358 to be enabled or disabled.
359 For example, the following two invocations of
360 .Nm
361 both enable the built-in
362 .Xr emacs 1
363 command line editor:
364 .Bd -literal -offset indent
365 set -E
366 set -o emacs
367 .Ed
368 .Pp
369 If used without an argument, the
370 .Fl o
371 option displays the current option settings in a human-readable format.
372 If
373 .Cm +o
374 is used without an argument, the current option settings are output
375 in a format suitable for re-input into the shell.
376 .Ss Lexical Structure
377 The shell reads input in terms of lines from a file and breaks
378 it up into words at whitespace (blanks and tabs), and at
379 certain sequences of
380 characters called
381 .Dq operators ,
382 which are special to the shell.
383 There are two types of operators: control operators and
384 redirection operators (their meaning is discussed later).
385 The following is a list of valid operators:
386 .Bl -tag -width indent
387 .It Control operators:
388 .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
389 .It Li & Ta Li && Ta Li ( Ta Li ) Ta Li \en
390 .It Li ;; Ta Li ;& Ta Li ; Ta Li | Ta Li ||
391 .El
392 .It Redirection operators:
393 .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
394 .It Li < Ta Li > Ta Li << Ta Li >> Ta Li <>
395 .It Li <& Ta Li >& Ta Li <<- Ta Li >|
396 .El
397 .El
398 .Pp
399 The character
400 .Ql #
401 introduces a comment if used at the beginning of a word.
402 The word starting with
403 .Ql #
404 and the rest of the line are ignored.
405 .Pp
406 .Tn ASCII
407 .Dv NUL
408 characters (character code 0) are not allowed in shell input.
409 .Ss Quoting
410 Quoting is used to remove the special meaning of certain characters
411 or words to the shell, such as operators, whitespace, keywords,
412 or alias names.
413 .Pp
414 There are four types of quoting: matched single quotes,
415 dollar-single quotes,
416 matched double quotes, and backslash.
417 .Bl -tag -width indent
418 .It Single Quotes
419 Enclosing characters in single quotes preserves the literal
420 meaning of all the characters (except single quotes, making
421 it impossible to put single-quotes in a single-quoted string).
422 .It Dollar-Single Quotes
423 Enclosing characters between
424 .Li $'
425 and
426 .Li '
427 preserves the literal meaning of all characters
428 except backslashes and single quotes.
429 A backslash introduces a C-style escape sequence:
430 .Bl -tag -width xUnnnnnnnn
431 .It \ea
432 Alert (ring the terminal bell)
433 .It \eb
434 Backspace
435 .It \ec Ns Ar c
436 The control character denoted by
437 .Li ^ Ns Ar c
438 in
439 .Xr stty 1 .
440 If
441 .Ar c
442 is a backslash, it must be doubled.
443 .It \ee
444 The ESC character
445 .Tn ( ASCII
446 0x1b)
447 .It \ef
448 Formfeed
449 .It \en
450 Newline
451 .It \er
452 Carriage return
453 .It \et
454 Horizontal tab
455 .It \ev
456 Vertical tab
457 .It \e\e
458 Literal backslash
459 .It \e\&'
460 Literal single-quote
461 .It \e\&"
462 Literal double-quote
463 .It \e Ns Ar nnn
464 The byte whose octal value is
465 .Ar nnn
466 (one to three digits)
467 .It \ex Ns Ar nn
468 The byte whose hexadecimal value is
469 .Ar nn
470 (one or more digits only the last two of which are used)
471 .It \eu Ns Ar nnnn
472 The Unicode code point
473 .Ar nnnn
474 (four hexadecimal digits)
475 .It \eU Ns Ar nnnnnnnn
476 The Unicode code point
477 .Ar nnnnnnnn
478 (eight hexadecimal digits)
479 .El
480 .Pp
481 The sequences for Unicode code points are currently only useful with
482 UTF-8 locales.
483 They reject code point 0 and UTF-16 surrogates.
484 .Pp
485 If an escape sequence would produce a byte with value 0,
486 that byte and the rest of the string until the matching single-quote
487 are ignored.
488 .Pp
489 Any other string starting with a backslash is an error.
490 .It Double Quotes
491 Enclosing characters within double quotes preserves the literal
492 meaning of all characters except dollar sign
493 .Pq Ql $ ,
494 backquote
495 .Pq Ql ` ,
496 and backslash
497 .Pq Ql \e .
498 The backslash inside double quotes is historically weird.
499 It remains literal unless it precedes the following characters,
500 which it serves to quote:
501 .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
502 .It Li $ Ta Li ` Ta Li \&" Ta Li \e\  Ta Li \en
503 .El
504 .It Backslash
505 A backslash preserves the literal meaning of the following
506 character, with the exception of the newline character
507 .Pq Ql \en .
508 A backslash preceding a newline is treated as a line continuation.
509 .El
510 .Ss Keywords
511 Keywords or reserved words are words that have special meaning to the
512 shell and are recognized at the beginning of a line and
513 after a control operator.
514 The following are keywords:
515 .Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center
516 .It Li \&! Ta { Ta } Ta Ic case Ta Ic do
517 .It Ic done Ta Ic elif Ta Ic else Ta Ic esac Ta Ic fi
518 .It Ic for Ta Ic if Ta Ic then Ta Ic until Ta Ic while
519 .El
520 .Ss Aliases
521 An alias is a name and corresponding value set using the
522 .Ic alias
523 built-in command.
524 Wherever the command word of a simple command may occur,
525 and after checking for keywords if a keyword may occur, the shell
526 checks the word to see if it matches an alias.
527 If it does, it replaces it in the input stream with its value.
528 For example, if there is an alias called
529 .Dq Li lf
530 with the value
531 .Dq Li "ls -F" ,
532 then the input
533 .Pp
534 .Dl "lf foobar"
535 .Pp
536 would become
537 .Pp
538 .Dl "ls -F foobar"
539 .Pp
540 Aliases provide a convenient way for naive users to
541 create shorthands for commands without having to learn how
542 to create functions with arguments.
543 Using aliases in scripts is discouraged
544 because the command that defines them must be executed
545 before the code that uses them is parsed.
546 This is fragile and not portable.
547 .Pp
548 An alias name may be escaped in a command line, so that it is not
549 replaced by its alias value, by using quoting characters within or
550 adjacent to the alias name.
551 This is most often done by prefixing
552 an alias name with a backslash to execute a function, built-in, or
553 normal program with the same name.
554 See the
555 .Sx Quoting
556 subsection.
557 .Ss Commands
558 The shell interprets the words it reads according to a
559 language, the specification of which is outside the scope
560 of this man page (refer to the BNF in the
561 .St -p1003.2
562 document).
563 Essentially though, a line is read and if
564 the first word of the line (or after a control operator)
565 is not a keyword, then the shell has recognized a
566 simple command.
567 Otherwise, a complex command or some
568 other special construct may have been recognized.
569 .Ss Simple Commands
570 If a simple command has been recognized, the shell performs
571 the following actions:
572 .Bl -enum
573 .It
574 Leading words of the form
575 .Dq Li name=value
576 are stripped off and assigned to the environment of
577 the simple command.
578 Redirection operators and
579 their arguments (as described below) are stripped
580 off and saved for processing.
581 .It
582 The remaining words are expanded as described in
583 the section called
584 .Sx Word Expansions ,
585 and the first remaining word is considered the command
586 name and the command is located.
587 The remaining
588 words are considered the arguments of the command.
589 If no command name resulted, then the
590 .Dq Li name=value
591 variable assignments recognized in 1) affect the
592 current shell.
593 .It
594 Redirections are performed as described in
595 the next section.
596 .El
597 .Ss Redirections
598 Redirections are used to change where a command reads its input
599 or sends its output.
600 In general, redirections open, close, or
601 duplicate an existing reference to a file.
602 The overall format
603 used for redirection is:
604 .Pp
605 .D1 Oo Ar n Oc Ar redir-op file
606 .Pp
607 The
608 .Ar redir-op
609 is one of the redirection operators mentioned
610 previously.
611 The following gives some examples of how these
612 operators can be used.
613 Note that stdin and stdout are commonly used abbreviations
614 for standard input and standard output respectively.
615 .Bl -tag -width "1234567890XX" -offset indent
616 .It Oo Ar n Oc Ns Li > Ar file
617 redirect stdout (or file descriptor
618 .Ar n )
619 to
620 .Ar file
621 .It Oo Ar n Oc Ns Li >| Ar file
622 same as above, but override the
623 .Fl C
624 option
625 .It Oo Ar n Oc Ns Li >> Ar file
626 append stdout (or file descriptor
627 .Ar n )
628 to
629 .Ar file
630 .It Oo Ar n Oc Ns Li < Ar file
631 redirect stdin (or file descriptor
632 .Ar n )
633 from
634 .Ar file
635 .It Oo Ar n Oc Ns Li <> Ar file
636 redirect stdin (or file descriptor
637 .Ar n )
638 to and from
639 .Ar file
640 .It Oo Ar n1 Oc Ns Li <& Ns Ar n2
641 duplicate stdin (or file descriptor
642 .Ar n1 )
643 from file descriptor
644 .Ar n2
645 .It Oo Ar n Oc Ns Li <&-
646 close stdin (or file descriptor
647 .Ar n )
648 .It Oo Ar n1 Oc Ns Li >& Ns Ar n2
649 duplicate stdout (or file descriptor
650 .Ar n1 )
651 to file descriptor
652 .Ar n2
653 .It Oo Ar n Oc Ns Li >&-
654 close stdout (or file descriptor
655 .Ar n )
656 .El
657 .Pp
658 The following redirection is often called a
659 .Dq here-document .
660 .Bd -unfilled -offset indent
661 .Oo Ar n Oc Ns Li << Ar delimiter
662 .D1 Ar here-doc-text
663 .D1 ...
664 .Ar delimiter
665 .Ed
666 .Pp
667 All the text on successive lines up to the delimiter is
668 saved away and made available to the command on standard
669 input, or file descriptor
670 .Ar n
671 if it is specified.
672 If the
673 .Ar delimiter
674 as specified on the initial line is quoted, then the
675 .Ar here-doc-text
676 is treated literally, otherwise the text is subjected to
677 parameter expansion, command substitution, and arithmetic
678 expansion (as described in the section on
679 .Sx Word Expansions ) .
680 If the operator is
681 .Dq Li <<-
682 instead of
683 .Dq Li << ,
684 then leading tabs
685 in the
686 .Ar here-doc-text
687 are stripped.
688 .Ss Search and Execution
689 There are three types of commands: shell functions,
690 built-in commands, and normal programs.
691 The command is searched for (by name) in that order.
692 The three types of commands are all executed in a different way.
693 .Pp
694 When a shell function is executed, all of the shell positional
695 parameters (except
696 .Li $0 ,
697 which remains unchanged) are
698 set to the arguments of the shell function.
699 The variables which are explicitly placed in the environment of
700 the command (by placing assignments to them before the
701 function name) are made local to the function and are set
702 to the values given.
703 Then the command given in the function definition is executed.
704 The positional parameters are restored to their original values
705 when the command completes.
706 This all occurs within the current shell.
707 .Pp
708 Shell built-in commands are executed internally to the shell, without
709 spawning a new process.
710 There are two kinds of built-in commands: regular and special.
711 Assignments before special builtins persist after they finish
712 executing and assignment errors, redirection errors and certain
713 operand errors cause a script to be aborted.
714 Special builtins cannot be overridden with a function.
715 Both regular and special builtins can affect the shell in ways
716 normal programs cannot.
717 .Pp
718 Otherwise, if the command name does not match a function
719 or built-in command, the command is searched for as a normal
720 program in the file system (as described in the next section).
721 When a normal program is executed, the shell runs the program,
722 passing the arguments and the environment to the program.
723 If the program is not a normal executable file
724 (i.e., if it does not begin with the
725 .Dq "magic number"
726 whose
727 .Tn ASCII
728 representation is
729 .Dq Li #! ,
730 resulting in an
731 .Er ENOEXEC
732 return value from
733 .Xr execve 2 )
734 but appears to be a text file,
735 the shell will run a new instance of
736 .Nm
737 to interpret it.
738 .Pp
739 Note that previous versions of this document
740 and the source code itself misleadingly and sporadically
741 refer to a shell script without a magic number
742 as a
743 .Dq "shell procedure" .
744 .Ss Path Search
745 When locating a command, the shell first looks to see if
746 it has a shell function by that name.
747 Then it looks for a
748 built-in command by that name.
749 If a built-in command is not found,
750 one of two things happen:
751 .Bl -enum
752 .It
753 Command names containing a slash are simply executed without
754 performing any searches.
755 .It
756 The shell searches each entry in the
757 .Va PATH
758 variable
759 in turn for the command.
760 The value of the
761 .Va PATH
762 variable should be a series of
763 entries separated by colons.
764 Each entry consists of a
765 directory name.
766 The current directory
767 may be indicated implicitly by an empty directory name,
768 or explicitly by a single period.
769 .El
770 .Ss Command Exit Status
771 Each command has an exit status that can influence the behavior
772 of other shell commands.
773 The paradigm is that a command exits
774 with zero for normal or success, and non-zero for failure,
775 error, or a false indication.
776 The man page for each command
777 should indicate the various exit codes and what they mean.
778 Additionally, the built-in commands return exit codes, as does
779 an executed shell function.
780 .Pp
781 If a command is terminated by a signal, its exit status is 128 plus
782 the signal number.
783 Signal numbers are defined in the header file
784 .In sys/signal.h .
785 .Ss Complex Commands
786 Complex commands are combinations of simple commands
787 with control operators or keywords, together creating a larger complex
788 command.
789 More generally, a command is one of the following:
790 .Bl -item -offset indent
791 .It
792 simple command
793 .It
794 pipeline
795 .It
796 list or compound-list
797 .It
798 compound command
799 .It
800 function definition
801 .El
802 .Pp
803 Unless otherwise stated, the exit status of a command is
804 that of the last simple command executed by the command.
805 .Ss Pipelines
806 A pipeline is a sequence of one or more commands separated
807 by the control operator
808 .Ql \&| .
809 The standard output of all but
810 the last command is connected to the standard input
811 of the next command.
812 The standard output of the last
813 command is inherited from the shell, as usual.
814 .Pp
815 The format for a pipeline is:
816 .Pp
817 .D1 Oo Li \&! Oc Ar command1 Op Li \&| Ar command2 ...
818 .Pp
819 The standard output of
820 .Ar command1
821 is connected to the standard input of
822 .Ar command2 .
823 The standard input, standard output, or
824 both of a command is considered to be assigned by the
825 pipeline before any redirection specified by redirection
826 operators that are part of the command.
827 .Pp
828 Note that unlike some other shells,
829 .Nm
830 executes each process in a pipeline with more than one command
831 in a subshell environment and as a child of the
832 .Nm
833 process.
834 .Pp
835 If the pipeline is not in the background (discussed later),
836 the shell waits for all commands to complete.
837 .Pp
838 If the keyword
839 .Ic !\&
840 does not precede the pipeline, the
841 exit status is the exit status of the last command specified
842 in the pipeline.
843 Otherwise, the exit status is the logical
844 NOT of the exit status of the last command.
845 That is, if
846 the last command returns zero, the exit status is 1; if
847 the last command returns greater than zero, the exit status
848 is zero.
849 .Pp
850 Because pipeline assignment of standard input or standard
851 output or both takes place before redirection, it can be
852 modified by redirection.
853 For example:
854 .Pp
855 .Dl "command1 2>&1 | command2"
856 .Pp
857 sends both the standard output and standard error of
858 .Ar command1
859 to the standard input of
860 .Ar command2 .
861 .Pp
862 A
863 .Ql \&;
864 or newline terminator causes the preceding
865 AND-OR-list
866 (described below in the section called
867 .Sx Short-Circuit List Operators )
868 to be executed sequentially;
869 an
870 .Ql &
871 causes asynchronous execution of the preceding AND-OR-list.
872 .Ss Background Commands (&)
873 If a command is terminated by the control operator ampersand
874 .Pq Ql & ,
875 the shell executes the command asynchronously;
876 the shell does not wait for the command to finish
877 before executing the next command.
878 .Pp
879 The format for running a command in background is:
880 .Pp
881 .D1 Ar command1 Li & Op Ar command2 Li & Ar ...
882 .Pp
883 If the shell is not interactive, the standard input of an
884 asynchronous command is set to
885 .Pa /dev/null .
886 .Ss Lists (Generally Speaking)
887 A list is a sequence of zero or more commands separated by
888 newlines, semicolons, or ampersands,
889 and optionally terminated by one of these three characters.
890 The commands in a
891 list are executed in the order they are written.
892 If command is followed by an ampersand, the shell starts the
893 command and immediately proceeds onto the next command;
894 otherwise it waits for the command to terminate before
895 proceeding to the next one.
896 .Ss Short-Circuit List Operators
897 .Dq Li &&
898 and
899 .Dq Li ||
900 are AND-OR list operators.
901 .Dq Li &&
902 executes the first command, and then executes the second command
903 if the exit status of the first command is zero.
904 .Dq Li ||
905 is similar, but executes the second command if the exit
906 status of the first command is nonzero.
907 .Dq Li &&
908 and
909 .Dq Li ||
910 both have the same priority.
911 .Ss Flow-Control Constructs (if, while, for, case)
912 The syntax of the
913 .Ic if
914 command is:
915 .Bd -unfilled -offset indent -compact
916 .Ic if Ar list
917 .Ic then Ar list
918 .Oo Ic elif Ar list
919 .Ic then Ar list Oc Ar ...
920 .Op Ic else Ar list
921 .Ic fi
922 .Ed
923 .Pp
924 The syntax of the
925 .Ic while
926 command is:
927 .Bd -unfilled -offset indent -compact
928 .Ic while Ar list
929 .Ic do Ar list
930 .Ic done
931 .Ed
932 .Pp
933 The two lists are executed repeatedly while the exit status of the
934 first list is zero.
935 The
936 .Ic until
937 command is similar, but has the word
938 .Ic until
939 in place of
940 .Ic while ,
941 which causes it to
942 repeat until the exit status of the first list is zero.
943 .Pp
944 The syntax of the
945 .Ic for
946 command is:
947 .Bd -unfilled -offset indent -compact
948 .Ic for Ar variable Op Ic in Ar word ...
949 .Ic do Ar list
950 .Ic done
951 .Ed
952 .Pp
953 If
954 .Ic in
955 and the following words are omitted,
956 .Ic in Li \&"$@\&"
957 is used instead.
958 The words are expanded, and then the list is executed
959 repeatedly with the variable set to each word in turn.
960 The
961 .Ic do
962 and
963 .Ic done
964 commands may be replaced with
965 .Ql {
966 and
967 .Ql } .
968 .Pp
969 The syntax of the
970 .Ic break
971 and
972 .Ic continue
973 commands is:
974 .D1 Ic break Op Ar num
975 .D1 Ic continue Op Ar num
976 .Pp
977 The
978 .Ic break
979 command terminates the
980 .Ar num
981 innermost
982 .Ic for
983 or
984 .Ic while
985 loops.
986 The
987 .Ic continue
988 command continues with the next iteration of the innermost loop.
989 These are implemented as special built-in commands.
990 .Pp
991 The syntax of the
992 .Ic case
993 command is:
994 .Bd -unfilled -offset indent -compact
995 .Ic case Ar word Ic in
996 .Ar pattern Ns Li ) Ar list Li ;;
997 .Ar ...
998 .Ic esac
999 .Ed
1000 .Pp
1001 The pattern can actually be one or more patterns
1002 (see
1003 .Sx Shell Patterns
1004 described later),
1005 separated by
1006 .Ql \&|
1007 characters.
1008 If the selected list is terminated by the control operator
1009 .Ql ;&
1010 instead of
1011 .Ql ;; ,
1012 execution continues with the next list.
1013 The exit code of the
1014 .Ic case
1015 command is the exit code of the last command executed in the list or
1016 zero if no patterns were matched.
1017 .Ss Grouping Commands Together
1018 Commands may be grouped by writing either
1019 .Pp
1020 .D1 Li \&( Ns Ar list Ns Li \%)
1021 .Pp
1022 or
1023 .Pp
1024 .D1 Li { Ar list Ns Li \&; }
1025 .Pp
1026 The first form executes the commands in a subshell environment.
1027 Note that built-in commands thus executed do not affect the current shell.
1028 The second form never forks another shell,
1029 so it is slightly more efficient.
1030 Grouping commands together this way allows the user to
1031 redirect their output as though they were one program:
1032 .Bd -literal -offset indent
1033 { echo -n "hello"; echo " world"; } > greeting
1034 .Ed
1035 .Ss Functions
1036 The syntax of a function definition is
1037 .Pp
1038 .D1 Ar name Li \&( \&) Ar command
1039 .Pp
1040 A function definition is an executable statement; when
1041 executed it installs a function named
1042 .Ar name
1043 and returns an
1044 exit status of zero.
1045 The
1046 .Ar command
1047 is normally a list
1048 enclosed between
1049 .Ql {
1050 and
1051 .Ql } .
1052 .Pp
1053 Variables may be declared to be local to a function by
1054 using the
1055 .Ic local
1056 command.
1057 This should appear as the first statement of a function,
1058 and the syntax is:
1059 .Pp
1060 .D1 Ic local Oo Ar variable ... Oc Op Fl
1061 .Pp
1062 The
1063 .Ic local
1064 command is implemented as a built-in command.
1065 .Pp
1066 When a variable is made local, it inherits the initial
1067 value and exported and readonly flags from the variable
1068 with the same name in the surrounding scope, if there is
1069 one.
1070 Otherwise, the variable is initially unset.
1071 The shell
1072 uses dynamic scoping, so that if the variable
1073 .Va x
1074 is made local to function
1075 .Em f ,
1076 which then calls function
1077 .Em g ,
1078 references to the variable
1079 .Va x
1080 made inside
1081 .Em g
1082 will refer to the variable
1083 .Va x
1084 declared inside
1085 .Em f ,
1086 not to the global variable named
1087 .Va x .
1088 .Pp
1089 The only special parameter that can be made local is
1090 .Ql - .
1091 Making
1092 .Ql -
1093 local causes any shell options that are
1094 changed via the
1095 .Ic set
1096 command inside the function to be
1097 restored to their original values when the function
1098 returns.
1099 .Pp
1100 The syntax of the
1101 .Ic return
1102 command is
1103 .Pp
1104 .D1 Ic return Op Ar exitstatus
1105 .Pp
1106 It terminates the current executional scope, returning from the previous
1107 nested function, sourced script, or shell instance, in that order.
1108 The
1109 .Ic return
1110 command is implemented as a special built-in command.
1111 .Ss Variables and Parameters
1112 The shell maintains a set of parameters.
1113 A parameter
1114 denoted by a name is called a variable.
1115 When starting up,
1116 the shell turns all the environment variables into shell
1117 variables.
1118 New variables can be set using the form
1119 .Pp
1120 .D1 Ar name Ns = Ns Ar value
1121 .Pp
1122 Variables set by the user must have a name consisting solely
1123 of alphabetics, numerics, and underscores.
1124 The first letter of a variable name must not be numeric.
1125 A parameter can also be denoted by a number
1126 or a special character as explained below.
1127 .Ss Positional Parameters
1128 A positional parameter is a parameter denoted by a number greater than zero.
1129 The shell sets these initially to the values of its command line
1130 arguments that follow the name of the shell script.
1131 The
1132 .Ic set
1133 built-in command can also be used to set or reset them.
1134 .Ss Special Parameters
1135 Special parameters are parameters denoted by a single special character
1136 or the digit zero.
1137 They are shown in the following list, exactly as they would appear in input
1138 typed by the user or in the source of a shell script.
1139 .Bl -hang
1140 .It Li $*
1141 Expands to the positional parameters, starting from one.
1142 When
1143 the expansion occurs within a double-quoted string
1144 it expands to a single field with the value of each parameter
1145 separated by the first character of the
1146 .Va IFS
1147 variable,
1148 or by a space if
1149 .Va IFS
1150 is unset.
1151 .It Li $@
1152 Expands to the positional parameters, starting from one.
1153 When
1154 the expansion occurs within double-quotes, each positional
1155 parameter expands as a separate argument.
1156 If there are no positional parameters, the
1157 expansion of
1158 .Li @
1159 generates zero arguments, even when
1160 .Li @
1161 is double-quoted.
1162 What this basically means, for example, is
1163 if
1164 .Li $1
1165 is
1166 .Dq Li abc
1167 and
1168 .Li $2
1169 is
1170 .Dq Li "def ghi" ,
1171 then
1172 .Li \&"$@\&"
1173 expands to
1174 the two arguments:
1175 .Bd -literal -offset indent
1176 "abc"   "def ghi"
1177 .Ed
1178 .It Li $#
1179 Expands to the number of positional parameters.
1180 .It Li $?
1181 Expands to the exit status of the most recent pipeline.
1182 .It Li $-
1183 (hyphen) Expands to the current option flags (the single-letter
1184 option names concatenated into a string) as specified on
1185 invocation, by the
1186 .Ic set
1187 built-in command, or implicitly
1188 by the shell.
1189 .It Li $$
1190 Expands to the process ID of the invoked shell.
1191 A subshell
1192 retains the same value of
1193 .Va $
1194 as its parent.
1195 .It Li $!
1196 Expands to the process ID of the most recent background
1197 command executed from the current shell.
1198 For a
1199 pipeline, the process ID is that of the last command in the
1200 pipeline.
1201 If this parameter is referenced, the shell will remember
1202 the process ID and its exit status until the
1203 .Ic wait
1204 built-in command reports completion of the process.
1205 .It Li $0
1206 (zero) Expands to the name of the shell script if passed on the command line,
1207 the
1208 .Ar name
1209 operand if given (with
1210 .Fl c )
1211 or otherwise argument 0 passed to the shell.
1212 .El
1213 .Ss Special Variables
1214 The following variables are set by the shell or
1215 have special meaning to it:
1216 .Bl -tag -width ".Va HISTSIZE"
1217 .It Va CDPATH
1218 The search path used with the
1219 .Ic cd
1220 built-in.
1221 .It Va EDITOR
1222 The fallback editor used with the
1223 .Ic fc
1224 built-in.
1225 If not set, the default editor is
1226 .Xr ed 1 .
1227 .It Va FCEDIT
1228 The default editor used with the
1229 .Ic fc
1230 built-in.
1231 .It Va HISTSIZE
1232 The number of previous commands that are accessible.
1233 .It Va HOME
1234 The user's home directory,
1235 used in tilde expansion and as a default directory for the
1236 .Ic cd
1237 built-in.
1238 .It Va IFS
1239 Input Field Separators.
1240 This is normally set to
1241 .Aq space ,
1242 .Aq tab ,
1243 and
1244 .Aq newline .
1245 See the
1246 .Sx White Space Splitting
1247 section for more details.
1248 .It Va LINENO
1249 The current line number in the script or function.
1250 .It Va MAIL
1251 The name of a mail file, that will be checked for the arrival of new
1252 mail.
1253 Overridden by
1254 .Va MAILPATH .
1255 .It Va MAILPATH
1256 A colon
1257 .Pq Ql \&:
1258 separated list of file names, for the shell to check for incoming
1259 mail.
1260 This variable overrides the
1261 .Va MAIL
1262 setting.
1263 There is a maximum of 10 mailboxes that can be monitored at once.
1264 .It Va PATH
1265 The default search path for executables.
1266 See the
1267 .Sx Path Search
1268 section for details.
1269 .It Va PPID
1270 The parent process ID of the invoked shell.
1271 This is set at startup
1272 unless this variable is in the environment.
1273 A later change of parent process ID is not reflected.
1274 A subshell retains the same value of
1275 .Va PPID .
1276 .It Va PS1
1277 The primary prompt string, which defaults to
1278 .Dq Li "$ " ,
1279 unless you are the superuser, in which case it defaults to
1280 .Dq Li "# " .
1281 .It Va PS2
1282 The secondary prompt string, which defaults to
1283 .Dq Li "> " .
1284 .It Va PS4
1285 The prefix for the trace output (if
1286 .Fl x
1287 is active).
1288 The default is
1289 .Dq Li "+ " .
1290 .El
1291 .Ss Word Expansions
1292 This clause describes the various expansions that are
1293 performed on words.
1294 Not all expansions are performed on
1295 every word, as explained later.
1296 .Pp
1297 Tilde expansions, parameter expansions, command substitutions,
1298 arithmetic expansions, and quote removals that occur within
1299 a single word expand to a single field.
1300 It is only field
1301 splitting or pathname expansion that can create multiple
1302 fields from a single word.
1303 The single exception to this rule is
1304 the expansion of the special parameter
1305 .Va @
1306 within double-quotes,
1307 as was described above.
1308 .Pp
1309 The order of word expansion is:
1310 .Bl -enum
1311 .It
1312 Tilde Expansion, Parameter Expansion, Command Substitution,
1313 Arithmetic Expansion (these all occur at the same time).
1314 .It
1315 Field Splitting is performed on fields generated by step (1)
1316 unless the
1317 .Va IFS
1318 variable is null.
1319 .It
1320 Pathname Expansion (unless the
1321 .Fl f
1322 option is in effect).
1323 .It
1324 Quote Removal.
1325 .El
1326 .Pp
1327 The
1328 .Ql $
1329 character is used to introduce parameter expansion, command
1330 substitution, or arithmetic expansion.
1331 .Ss Tilde Expansion (substituting a user's home directory)
1332 A word beginning with an unquoted tilde character
1333 .Pq Ql ~
1334 is
1335 subjected to tilde expansion.
1336 All the characters up to a slash
1337 .Pq Ql /
1338 or the end of the word are treated as a username
1339 and are replaced with the user's home directory.
1340 If the
1341 username is missing (as in
1342 .Pa ~/foobar ) ,
1343 the tilde is replaced with the value of the
1344 .Va HOME
1345 variable (the current user's home directory).
1346 .Ss Parameter Expansion
1347 The format for parameter expansion is as follows:
1348 .Pp
1349 .D1 Li ${ Ns Ar expression Ns Li }
1350 .Pp
1351 where
1352 .Ar expression
1353 consists of all characters until the matching
1354 .Ql } .
1355 Any
1356 .Ql }
1357 escaped by a backslash or within a single-quoted or double-quoted
1358 string, and characters in
1359 embedded arithmetic expansions, command substitutions, and variable
1360 expansions, are not examined in determining the matching
1361 .Ql } .
1362 If the variants with
1363 .Ql + ,
1364 .Ql - ,
1365 .Ql =
1366 or
1367 .Ql ?\&
1368 occur within a double-quoted string,
1369 as an extension there may be unquoted parts
1370 (via double-quotes inside the expansion);
1371 .Ql }
1372 within such parts are also not examined in determining the matching
1373 .Ql } .
1374 .Pp
1375 The simplest form for parameter expansion is:
1376 .Pp
1377 .D1 Li ${ Ns Ar parameter Ns Li }
1378 .Pp
1379 The value, if any, of
1380 .Ar parameter
1381 is substituted.
1382 .Pp
1383 The parameter name or symbol can be enclosed in braces, which are
1384 optional except for positional parameters with more than one digit or
1385 when parameter is followed by a character that could be interpreted as
1386 part of the name.
1387 If a parameter expansion occurs inside double-quotes:
1388 .Bl -enum
1389 .It
1390 Pathname expansion is not performed on the results of the
1391 expansion.
1392 .It
1393 Field splitting is not performed on the results of the
1394 expansion, with the exception of the special parameter
1395 .Va @ .
1396 .El
1397 .Pp
1398 In addition, a parameter expansion can be modified by using one of the
1399 following formats.
1400 .Bl -tag -width indent
1401 .It Li ${ Ns Ar parameter Ns Li :- Ns Ar word Ns Li }
1402 Use Default Values.
1403 If
1404 .Ar parameter
1405 is unset or null, the expansion of
1406 .Ar word
1407 is substituted; otherwise, the value of
1408 .Ar parameter
1409 is substituted.
1410 .It Li ${ Ns Ar parameter Ns Li := Ns Ar word Ns Li }
1411 Assign Default Values.
1412 If
1413 .Ar parameter
1414 is unset or null, the expansion of
1415 .Ar word
1416 is assigned to
1417 .Ar parameter .
1418 In all cases, the
1419 final value of
1420 .Ar parameter
1421 is substituted.
1422 Quoting inside
1423 .Ar word
1424 does not prevent field splitting or pathname expansion.
1425 Only variables, not positional
1426 parameters or special parameters, can be
1427 assigned in this way.
1428 .It Li ${ Ns Ar parameter Ns Li :? Ns Oo Ar word Oc Ns Li }
1429 Indicate Error if Null or Unset.
1430 If
1431 .Ar parameter
1432 is unset or null, the expansion of
1433 .Ar word
1434 (or a message indicating it is unset if
1435 .Ar word
1436 is omitted) is written to standard
1437 error and the shell exits with a nonzero
1438 exit status.
1439 Otherwise, the value of
1440 .Ar parameter
1441 is substituted.
1442 An
1443 interactive shell need not exit.
1444 .It Li ${ Ns Ar parameter Ns Li :+ Ns Ar word Ns Li }
1445 Use Alternate Value.
1446 If
1447 .Ar parameter
1448 is unset or null, null is substituted;
1449 otherwise, the expansion of
1450 .Ar word
1451 is substituted.
1452 .El
1453 .Pp
1454 In the parameter expansions shown previously, use of the colon in the
1455 format results in a test for a parameter that is unset or null; omission
1456 of the colon results in a test for a parameter that is only unset.
1457 .Pp
1458 The
1459 .Ar word
1460 inherits the type of quoting
1461 (unquoted, double-quoted or here-document)
1462 from the surroundings,
1463 with the exception that a backslash that quotes a closing brace is removed
1464 during quote removal.
1465 .Bl -tag -width indent
1466 .It Li ${# Ns Ar parameter Ns Li }
1467 String Length.
1468 The length in characters of
1469 the value of
1470 .Ar parameter .
1471 .El
1472 .Pp
1473 The following four varieties of parameter expansion provide for substring
1474 processing.
1475 In each case, pattern matching notation
1476 (see
1477 .Sx Shell Patterns ) ,
1478 rather than regular expression notation,
1479 is used to evaluate the patterns.
1480 If parameter is one of the special parameters
1481 .Va *
1482 or
1483 .Va @ ,
1484 the result of the expansion is unspecified.
1485 Enclosing the full parameter expansion string in double-quotes does not
1486 cause the following four varieties of pattern characters to be quoted,
1487 whereas quoting characters within the braces has this effect.
1488 .Bl -tag -width indent
1489 .It Li ${ Ns Ar parameter Ns Li % Ns Ar word Ns Li }
1490 Remove Smallest Suffix Pattern.
1491 The
1492 .Ar word
1493 is expanded to produce a pattern.
1494 The
1495 parameter expansion then results in
1496 .Ar parameter ,
1497 with the smallest portion of the
1498 suffix matched by the pattern deleted.
1499 .It Li ${ Ns Ar parameter Ns Li %% Ns Ar word Ns Li }
1500 Remove Largest Suffix Pattern.
1501 The
1502 .Ar word
1503 is expanded to produce a pattern.
1504 The
1505 parameter expansion then results in
1506 .Ar parameter ,
1507 with the largest portion of the
1508 suffix matched by the pattern deleted.
1509 .It Li ${ Ns Ar parameter Ns Li # Ns Ar word Ns Li }
1510 Remove Smallest Prefix Pattern.
1511 The
1512 .Ar word
1513 is expanded to produce a pattern.
1514 The
1515 parameter expansion then results in
1516 .Ar parameter ,
1517 with the smallest portion of the
1518 prefix matched by the pattern deleted.
1519 .It Li ${ Ns Ar parameter Ns Li ## Ns Ar word Ns Li }
1520 Remove Largest Prefix Pattern.
1521 The
1522 .Ar word
1523 is expanded to produce a pattern.
1524 The
1525 parameter expansion then results in
1526 .Ar parameter ,
1527 with the largest portion of the
1528 prefix matched by the pattern deleted.
1529 .El
1530 .Ss Command Substitution
1531 Command substitution allows the output of a command to be substituted in
1532 place of the command name itself.
1533 Command substitution occurs when
1534 the command is enclosed as follows:
1535 .Pp
1536 .D1 Li $( Ns Ar command Ns Li )\&
1537 .Pp
1538 or the backquoted version:
1539 .Pp
1540 .D1 Li ` Ns Ar command Ns Li `
1541 .Pp
1542 The shell expands the command substitution by executing command
1543 and replacing the command substitution
1544 with the standard output of the command,
1545 removing sequences of one or more newlines at the end of the substitution.
1546 Embedded newlines before the end of the output are not removed;
1547 however, during field splitting, they may be translated into spaces
1548 depending on the value of
1549 .Va IFS
1550 and the quoting that is in effect.
1551 The command is executed in a subshell environment,
1552 except that the built-in commands
1553 .Ic jobid ,
1554 .Ic jobs ,
1555 .Ic times
1556 and
1557 .Ic trap
1558 return information about the main shell environment
1559 if they are the only command in a command substitution.
1560 .Ss Arithmetic Expansion
1561 Arithmetic expansion provides a mechanism for evaluating an arithmetic
1562 expression and substituting its value.
1563 The format for arithmetic expansion is as follows:
1564 .Pp
1565 .D1 Li $(( Ns Ar expression Ns Li ))
1566 .Pp
1567 The
1568 .Ar expression
1569 is treated as if it were in double-quotes, except
1570 that a double-quote inside the expression is not treated specially.
1571 The
1572 shell expands all tokens in the
1573 .Ar expression
1574 for parameter expansion,
1575 command substitution,
1576 arithmetic expansion
1577 and quote removal.
1578 .Pp
1579 The allowed expressions are a subset of C expressions,
1580 summarized below.
1581 .Bl -tag -width "Variables" -offset indent
1582 .It Values
1583 All values are of type
1584 .Ft intmax_t .
1585 .It Constants
1586 Decimal, octal (starting with
1587 .Li 0 )
1588 and hexadecimal (starting with
1589 .Li 0x )
1590 integer constants.
1591 .It Variables
1592 Shell variables can be read and written
1593 and contain integer constants.
1594 .It Unary operators
1595 .Li "! ~ + -"
1596 .It Binary operators
1597 .Li "* / % + - << >> < <= > >= == != & ^ | && ||"
1598 .It Assignment operators
1599 .Li "= += -= *= /= %= <<= >>= &= ^= |="
1600 .It Conditional operator
1601 .Li "? :"
1602 .El
1603 .Pp
1604 The result of the expression is substituted in decimal.
1605 .Ss White Space Splitting (Field Splitting)
1606 After parameter expansion, command substitution, and
1607 arithmetic expansion the shell scans the results of
1608 expansions and substitutions that did not occur in double-quotes for
1609 field splitting and multiple fields can result.
1610 .Pp
1611 The shell treats each character of the
1612 .Va IFS
1613 variable as a delimiter and uses
1614 the delimiters to split the results of parameter expansion and command
1615 substitution into fields.
1616 .Ss Pathname Expansion (File Name Generation)
1617 Unless the
1618 .Fl f
1619 option is set,
1620 file name generation is performed
1621 after word splitting is complete.
1622 Each word is
1623 viewed as a series of patterns, separated by slashes.
1624 The
1625 process of expansion replaces the word with the names of
1626 all existing files whose names can be formed by replacing
1627 each pattern with a string that matches the specified pattern.
1628 There are two restrictions on this: first, a pattern cannot match
1629 a string containing a slash, and second,
1630 a pattern cannot match a string starting with a period
1631 unless the first character of the pattern is a period.
1632 The next section describes the patterns used for both
1633 Pathname Expansion and the
1634 .Ic case
1635 command.
1636 .Ss Shell Patterns
1637 A pattern consists of normal characters, which match themselves,
1638 and meta-characters.
1639 The meta-characters are
1640 .Ql \&! ,
1641 .Ql * ,
1642 .Ql \&? ,
1643 and
1644 .Ql \&[ .
1645 These characters lose their special meanings if they are quoted.
1646 When command or variable substitution is performed and the dollar sign
1647 or back quotes are not double-quoted, the value of the
1648 variable or the output of the command is scanned for these
1649 characters and they are turned into meta-characters.
1650 .Pp
1651 An asterisk
1652 .Pq Ql *
1653 matches any string of characters.
1654 A question mark
1655 .Pq Ql \&?
1656 matches any single character.
1657 A left bracket
1658 .Pq Ql \&[
1659 introduces a character class.
1660 The end of the character class is indicated by a
1661 .Ql \&] ;
1662 if the
1663 .Ql \&]
1664 is missing then the
1665 .Ql \&[
1666 matches a
1667 .Ql \&[
1668 rather than introducing a character class.
1669 A character class matches any of the characters between the square brackets.
1670 A range of characters may be specified using a minus sign.
1671 A named class of characters (see
1672 .Xr wctype 3 )
1673 may be specified by surrounding the name with
1674 .Ql \&[:
1675 and
1676 .Ql :\&] .
1677 For example,
1678 .Ql \&[\&[:alpha:\&]\&]
1679 is a shell pattern that matches a single letter.
1680 The character class may be complemented by making an exclamation point
1681 .Pq Ql !\&
1682 or the caret
1683 .Pq Ql ^\&
1684 the first character of the character class.
1685 .Pp
1686 To include a
1687 .Ql \&]
1688 in a character class, make it the first character listed
1689 (after the
1690 .Ql \&!
1691 or
1692 .Ql \&^ ,
1693 if any).
1694 To include a
1695 .Ql - ,
1696 make it the first or last character listed.
1697 .Ss Built-in Commands
1698 This section lists the built-in commands.
1699 .Bl -tag -width indent
1700 .It Ic \&:
1701 A null command that returns a 0 (true) exit value.
1702 .It Ic \&. Ar file
1703 The commands in the specified file are read and executed by the shell.
1704 The
1705 .Ic return
1706 command may be used to return to the
1707 .Ic \&.
1708 command's caller.
1709 If
1710 .Ar file
1711 contains any
1712 .Ql /
1713 characters, it is used as is.
1714 Otherwise, the shell searches the
1715 .Va PATH
1716 for the file.
1717 If it is not found in the
1718 .Va PATH ,
1719 it is sought in the current working directory.
1720 .It Ic \&[
1721 A built-in equivalent of
1722 .Xr test 1 .
1723 .It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc Ar ... Oc
1724 If
1725 .Ar name Ns = Ns Ar string
1726 is specified, the shell defines the alias
1727 .Ar name
1728 with value
1729 .Ar string .
1730 If just
1731 .Ar name
1732 is specified, the value of the alias
1733 .Ar name
1734 is printed.
1735 With no arguments, the
1736 .Ic alias
1737 built-in command prints the names and values of all defined aliases
1738 (see
1739 .Ic unalias ) .
1740 Alias values are written with appropriate quoting so that they are
1741 suitable for re-input to the shell.
1742 Also see the
1743 .Sx Aliases
1744 subsection.
1745 .It Ic bg Op Ar job ...
1746 Continue the specified jobs
1747 (or the current job if no jobs are given)
1748 in the background.
1749 .It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc
1750 List or alter key bindings for the line editor.
1751 This command is documented in
1752 .Xr editrc 5 .
1753 .It Ic break Op Ar num
1754 See the
1755 .Sx Flow-Control Constructs
1756 subsection.
1757 .It Ic builtin Ar cmd Op Ar arg ...
1758 Execute the specified built-in command,
1759 .Ar cmd .
1760 This is useful when the user wishes to override a shell function
1761 with the same name as a built-in command.
1762 .It Ic cd Oo Fl L | P Oc Oo Fl e Oc Op Ar directory
1763 Switch to the specified
1764 .Ar directory ,
1765 or to the directory specified in the
1766 .Va HOME
1767 environment variable if no
1768 .Ar directory
1769 is specified.
1770 If
1771 .Ar directory
1772 does not begin with
1773 .Pa / , \&. ,
1774 or
1775 .Pa .. ,
1776 then the directories listed in the
1777 .Va CDPATH
1778 variable will be
1779 searched for the specified
1780 .Ar directory .
1781 If
1782 .Va CDPATH
1783 is unset, the current directory is searched.
1784 The format of
1785 .Va CDPATH
1786 is the same as that of
1787 .Va PATH .
1788 In an interactive shell,
1789 the
1790 .Ic cd
1791 command will print out the name of the directory
1792 that it actually switched to
1793 if this is different from the name that the user gave.
1794 These may be different either because the
1795 .Va CDPATH
1796 mechanism was used or because a symbolic link was crossed.
1797 .Pp
1798 If the
1799 .Fl P
1800 option is specified,
1801 .Pa ..
1802 is handled physically and symbolic links are resolved before
1803 .Pa ..
1804 components are processed.
1805 If the
1806 .Fl L
1807 option is specified,
1808 .Pa ..
1809 is handled logically.
1810 This is the default.
1811 .Pp
1812 The
1813 .Fl e
1814 option causes
1815 .Ic cd
1816 to return exit status 1 if the full pathname of the new directory
1817 cannot be determined reliably or at all.
1818 Normally this is not considered an error,
1819 although a warning is printed.
1820 .It Ic chdir
1821 A synonym for the
1822 .Ic cd
1823 built-in command.
1824 .It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ...
1825 .It Ic command Oo Fl p Oc Fl v Ar utility
1826 .It Ic command Oo Fl p Oc Fl V Ar utility
1827 The first form of invocation executes the specified
1828 .Ar utility ,
1829 ignoring shell functions in the search.
1830 If
1831 .Ar utility
1832 is a special builtin,
1833 it is executed as if it were a regular builtin.
1834 .Pp
1835 If the
1836 .Fl p
1837 option is specified, the command search is performed using a
1838 default value of
1839 .Va PATH
1840 that is guaranteed to find all of the standard utilities.
1841 .Pp
1842 If the
1843 .Fl v
1844 option is specified,
1845 .Ar utility
1846 is not executed but a description of its interpretation by the shell is
1847 printed.
1848 For ordinary commands the output is the path name; for shell built-in
1849 commands, shell functions and keywords only the name is written.
1850 Aliases are printed as
1851 .Dq Ic alias Ar name Ns = Ns Ar value .
1852 .Pp
1853 The
1854 .Fl V
1855 option is identical to
1856 .Fl v
1857 except for the output.
1858 It prints
1859 .Dq Ar utility Ic is Ar description
1860 where
1861 .Ar description
1862 is either
1863 the path name to
1864 .Ar utility ,
1865 a special shell builtin,
1866 a shell builtin,
1867 a shell function,
1868 a shell keyword
1869 or
1870 an alias for
1871 .Ar value .
1872 .It Ic continue Op Ar num
1873 See the
1874 .Sx Flow-Control Constructs
1875 subsection.
1876 .It Ic echo Oo Fl e | n Oc Op Ar string ...
1877 Print a space-separated list of the arguments to the standard output
1878 and append a newline character.
1879 .Bl -tag -width indent
1880 .It Fl n
1881 Suppress the output of the trailing newline.
1882 .It Fl e
1883 Process C-style backslash escape sequences.
1884 The
1885 .Ic echo
1886 command understands the following character escapes:
1887 .Bl -tag -width indent
1888 .It \ea
1889 Alert (ring the terminal bell)
1890 .It \eb
1891 Backspace
1892 .It \ec
1893 Suppress the trailing newline (this has the side-effect of truncating the
1894 line if it is not the last character)
1895 .It \ee
1896 The ESC character
1897 .Tn ( ASCII
1898 0x1b)
1899 .It \ef
1900 Formfeed
1901 .It \en
1902 Newline
1903 .It \er
1904 Carriage return
1905 .It \et
1906 Horizontal tab
1907 .It \ev
1908 Vertical tab
1909 .It \e\e
1910 Literal backslash
1911 .It \e0nnn
1912 (Zero) The character whose octal value is
1913 .Ar nnn
1914 .El
1915 .Pp
1916 If
1917 .Ar string
1918 is not enclosed in quotes then the backslash itself must be escaped
1919 with a backslash to protect it from the shell.
1920 For example
1921 .Bd -literal -offset indent
1922 $ echo -e "a\evb"
1923 a
1924  b
1925 $ echo -e a\e\evb
1926 a
1927  b
1928 $ echo -e "a\e\eb"
1929 a\eb
1930 $ echo -e a\e\e\e\eb
1931 a\eb
1932 .Ed
1933 .El
1934 .Pp
1935 Only one of the
1936 .Fl e
1937 and
1938 .Fl n
1939 options may be specified.
1940 .It Ic eval Ar string ...
1941 Concatenate all the arguments with spaces.
1942 Then re-parse and execute the command.
1943 .It Ic exec Op Ar command Op Ar arg ...
1944 Unless
1945 .Ar command
1946 is omitted,
1947 the shell process is replaced with the specified program
1948 (which must be a real program, not a shell built-in command or function).
1949 Any redirections on the
1950 .Ic exec
1951 command are marked as permanent,
1952 so that they are not undone when the
1953 .Ic exec
1954 command finishes.
1955 .It Ic exit Op Ar exitstatus
1956 Terminate the shell process.
1957 If
1958 .Ar exitstatus
1959 is given
1960 it is used as the exit status of the shell.
1961 Otherwise, if the shell is executing an
1962 .Cm EXIT
1963 trap, the exit status of the last command before the trap is used;
1964 if the shell is executing a trap for a signal,
1965 the shell exits by resending the signal to itself.
1966 Otherwise, the exit status of the preceding command is used.
1967 The exit status should be an integer between 0 and 255.
1968 .It Ic export Ar name ...
1969 .It Ic export Op Fl p
1970 The specified names are exported so that they will
1971 appear in the environment of subsequent commands.
1972 The only way to un-export a variable is to
1973 .Ic unset
1974 it.
1975 The shell allows the value of a variable to be set
1976 at the same time as it is exported by writing
1977 .Pp
1978 .D1 Ic export Ar name Ns = Ns Ar value
1979 .Pp
1980 With no arguments the
1981 .Ic export
1982 command lists the names
1983 of all exported variables.
1984 If the
1985 .Fl p
1986 option is specified, the exported variables are printed as
1987 .Dq Ic export Ar name Ns = Ns Ar value
1988 lines, suitable for re-input to the shell.
1989 .It Ic false
1990 A null command that returns a non-zero (false) exit value.
1991 .It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last
1992 .It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last
1993 .It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first
1994 The
1995 .Ic fc
1996 built-in command lists, or edits and re-executes,
1997 commands previously entered to an interactive shell.
1998 .Bl -tag -width indent
1999 .It Fl e Ar editor
2000 Use the editor named by
2001 .Ar editor
2002 to edit the commands.
2003 The
2004 .Ar editor
2005 string is a command name,
2006 subject to search via the
2007 .Va PATH
2008 variable.
2009 The value in the
2010 .Va FCEDIT
2011 variable is used as a default when
2012 .Fl e
2013 is not specified.
2014 If
2015 .Va FCEDIT
2016 is null or unset, the value of the
2017 .Va EDITOR
2018 variable is used.
2019 If
2020 .Va EDITOR
2021 is null or unset,
2022 .Xr ed 1
2023 is used as the editor.
2024 .It Fl l No (ell)
2025 List the commands rather than invoking
2026 an editor on them.
2027 The commands are written in the
2028 sequence indicated by the
2029 .Ar first
2030 and
2031 .Ar last
2032 operands, as affected by
2033 .Fl r ,
2034 with each command preceded by the command number.
2035 .It Fl n
2036 Suppress command numbers when listing with
2037 .Fl l .
2038 .It Fl r
2039 Reverse the order of the commands listed
2040 (with
2041 .Fl l )
2042 or edited
2043 (with neither
2044 .Fl l
2045 nor
2046 .Fl s ) .
2047 .It Fl s
2048 Re-execute the command without invoking an editor.
2049 .It Ar first
2050 .It Ar last
2051 Select the commands to list or edit.
2052 The number of previous commands that can be accessed
2053 are determined by the value of the
2054 .Va HISTSIZE
2055 variable.
2056 The value of
2057 .Ar first
2058 or
2059 .Ar last
2060 or both are one of the following:
2061 .Bl -tag -width indent
2062 .It Oo Cm + Oc Ns Ar num
2063 A positive number representing a command number;
2064 command numbers can be displayed with the
2065 .Fl l
2066 option.
2067 .It Fl Ar num
2068 A negative decimal number representing the
2069 command that was executed
2070 .Ar num
2071 of
2072 commands previously.
2073 For example, \-1 is the immediately previous command.
2074 .It Ar string
2075 A string indicating the most recently entered command
2076 that begins with that string.
2077 If the
2078 .Ar old Ns = Ns Ar new
2079 operand is not also specified with
2080 .Fl s ,
2081 the string form of the first operand cannot contain an embedded equal sign.
2082 .El
2083 .El
2084 .Pp
2085 The following variables affect the execution of
2086 .Ic fc :
2087 .Bl -tag -width ".Va HISTSIZE"
2088 .It Va FCEDIT
2089 Name of the editor to use for history editing.
2090 .It Va HISTSIZE
2091 The number of previous commands that are accessible.
2092 .El
2093 .It Ic fg Op Ar job
2094 Move the specified
2095 .Ar job
2096 or the current job to the foreground.
2097 .It Ic getopts Ar optstring var
2098 The
2099 .Tn POSIX
2100 .Ic getopts
2101 command.
2102 The
2103 .Ic getopts
2104 command deprecates the older
2105 .Xr getopt 1
2106 command.
2107 The first argument should be a series of letters, each possibly
2108 followed by a colon which indicates that the option takes an argument.
2109 The specified variable is set to the parsed option.
2110 The index of
2111 the next argument is placed into the shell variable
2112 .Va OPTIND .
2113 If an option takes an argument, it is placed into the shell variable
2114 .Va OPTARG .
2115 If an invalid option is encountered,
2116 .Ar var
2117 is set to
2118 .Ql \&? .
2119 It returns a false value (1) when it encounters the end of the options.
2120 .It Ic hash Oo Fl rv Oc Op Ar command ...
2121 The shell maintains a hash table which remembers the locations of commands.
2122 With no arguments whatsoever, the
2123 .Ic hash
2124 command prints out the contents of this table.
2125 Entries which have not been looked at since the last
2126 .Ic cd
2127 command are marked with an asterisk;
2128 it is possible for these entries to be invalid.
2129 .Pp
2130 With arguments, the
2131 .Ic hash
2132 command removes each specified
2133 .Ar command
2134 from the hash table (unless they are functions) and then locates it.
2135 With the
2136 .Fl v
2137 option,
2138 .Ic hash
2139 prints the locations of the commands as it finds them.
2140 The
2141 .Fl r
2142 option causes the
2143 .Ic hash
2144 command to delete all the entries in the hash table except for functions.
2145 .It Ic jobid Op Ar job
2146 Print the process IDs of the processes in the specified
2147 .Ar job .
2148 If the
2149 .Ar job
2150 argument is omitted, use the current job.
2151 .It Ic jobs Oo Fl lps Oc Op Ar job ...
2152 Print information about the specified jobs, or all jobs if no
2153 .Ar job
2154 argument is given.
2155 The information printed includes job ID, status and command name.
2156 .Pp
2157 If the
2158 .Fl l
2159 option is specified, the PID of each job is also printed.
2160 If the
2161 .Fl p
2162 option is specified, only the process IDs for the process group leaders
2163 are printed, one per line.
2164 If the
2165 .Fl s
2166 option is specified, only the PIDs of the job commands are printed, one per
2167 line.
2168 .It Ic kill
2169 A built-in equivalent of
2170 .Xr kill 1
2171 that additionally supports sending signals to jobs.
2172 .It Ic local Oo Ar variable ... Oc Op Fl
2173 See the
2174 .Sx Functions
2175 subsection.
2176 .It Ic printf
2177 A built-in equivalent of
2178 .Xr printf 1 .
2179 .It Ic pwd Op Fl L | P
2180 Print the path of the current directory.
2181 The built-in command may
2182 differ from the program of the same name because the
2183 built-in command remembers what the current directory
2184 is rather than recomputing it each time.
2185 This makes
2186 it faster.
2187 However, if the current directory is
2188 renamed,
2189 the built-in version of
2190 .Xr pwd 1
2191 will continue to print the old name for the directory.
2192 .Pp
2193 If the
2194 .Fl P
2195 option is specified, symbolic links are resolved.
2196 If the
2197 .Fl L
2198 option is specified, the shell's notion of the current directory
2199 is printed (symbolic links are not resolved).
2200 This is the default.
2201 .It Ic read Oo Fl p Ar prompt Oc Oo
2202 .Fl t Ar timeout Oc Oo Fl er Oc Ar variable ...
2203 The
2204 .Ar prompt
2205 is printed if the
2206 .Fl p
2207 option is specified
2208 and the standard input is a terminal.
2209 Then a line is
2210 read from the standard input.
2211 The trailing newline
2212 is deleted from the line and the line is split as
2213 described in the section on
2214 .Sx White Space Splitting (Field Splitting)
2215 above, and
2216 the pieces are assigned to the variables in order.
2217 If there are more pieces than variables, the remaining
2218 pieces (along with the characters in
2219 .Va IFS
2220 that separated them)
2221 are assigned to the last variable.
2222 If there are more variables than pieces, the remaining
2223 variables are assigned the null string.
2224 .Pp
2225 Backslashes are treated specially, unless the
2226 .Fl r
2227 option is
2228 specified.
2229 If a backslash is followed by
2230 a newline, the backslash and the newline will be
2231 deleted.
2232 If a backslash is followed by any other
2233 character, the backslash will be deleted and the following
2234 character will be treated as though it were not in
2235 .Va IFS ,
2236 even if it is.
2237 .Pp
2238 If the
2239 .Fl t
2240 option is specified and the
2241 .Ar timeout
2242 elapses before a complete line of input is supplied,
2243 the
2244 .Ic read
2245 command will return an exit status of 1 without assigning any values.
2246 The
2247 .Ar timeout
2248 value may optionally be followed by one of
2249 .Ql s ,
2250 .Ql m
2251 or
2252 .Ql h
2253 to explicitly specify seconds, minutes or hours.
2254 If none is supplied,
2255 .Ql s
2256 is assumed.
2257 .Pp
2258 The
2259 .Fl e
2260 option exists only for backward compatibility with older scripts.
2261 .It Ic readonly Oo Fl p Oc Op Ar name ...
2262 Each specified
2263 .Ar name
2264 is marked as read only,
2265 so that it cannot be subsequently modified or unset.
2266 The shell allows the value of a variable to be set
2267 at the same time as it is marked read only
2268 by using the following form:
2269 .Pp
2270 .D1 Ic readonly Ar name Ns = Ns Ar value
2271 .Pp
2272 With no arguments the
2273 .Ic readonly
2274 command lists the names of all read only variables.
2275 If the
2276 .Fl p
2277 option is specified, the read-only variables are printed as
2278 .Dq Ic readonly Ar name Ns = Ns Ar value
2279 lines, suitable for re-input to the shell.
2280 .It Ic return Op Ar exitstatus
2281 See the
2282 .Sx Functions
2283 subsection.
2284 .It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo
2285 .Fl c Ar string Oc Op Fl - Ar arg ...
2286 The
2287 .Ic set
2288 command performs three different functions:
2289 .Bl -item
2290 .It
2291 With no arguments, it lists the values of all shell variables.
2292 .It
2293 If options are given,
2294 either in short form or using the long
2295 .Dq Fl /+o Ar longname
2296 form,
2297 it sets or clears the specified options as described in the section called
2298 .Sx Argument List Processing .
2299 .It
2300 If the
2301 .Dq Fl -
2302 option is specified,
2303 .Ic set
2304 will replace the shell's positional parameters with the subsequent
2305 arguments.
2306 If no arguments follow the
2307 .Dq Fl -
2308 option,
2309 all the positional parameters will be cleared,
2310 which is equivalent to executing the command
2311 .Dq Li "shift $#" .
2312 The
2313 .Dq Fl -
2314 flag may be omitted when specifying arguments to be used
2315 as positional replacement parameters.
2316 This is not recommended,
2317 because the first argument may begin with a dash
2318 .Pq Ql -
2319 or a plus
2320 .Pq Ql + ,
2321 which the
2322 .Ic set
2323 command will interpret as a request to enable or disable options.
2324 .El
2325 .It Ic setvar Ar variable value
2326 Assigns the specified
2327 .Ar value
2328 to the specified
2329 .Ar variable .
2330 The
2331 .Ic setvar
2332 command is intended to be used in functions that
2333 assign values to variables whose names are passed as parameters.
2334 In general it is better to write
2335 .Dq Ar variable Ns = Ns Ar value
2336 rather than using
2337 .Ic setvar .
2338 .It Ic shift Op Ar n
2339 Shift the positional parameters
2340 .Ar n
2341 times, or once if
2342 .Ar n
2343 is not specified.
2344 A shift sets the value of
2345 .Li $1
2346 to the value of
2347 .Li $2 ,
2348 the value of
2349 .Li $2
2350 to the value of
2351 .Li $3 ,
2352 and so on,
2353 decreasing the value of
2354 .Li $#
2355 by one.
2356 If there are zero positional parameters, shifting does not do anything.
2357 .It Ic test
2358 A built-in equivalent of
2359 .Xr test 1 .
2360 .It Ic times
2361 Print the amount of time spent executing the shell and its children.
2362 The first output line shows the user and system times for the shell
2363 itself, the second one contains the user and system times for the
2364 children.
2365 .It Ic trap Oo Ar action Oc Ar signal ...
2366 .It Ic trap Fl l
2367 Cause the shell to parse and execute
2368 .Ar action
2369 when any specified
2370 .Ar signal
2371 is received.
2372 The signals are specified by name or number.
2373 In addition, the pseudo-signal
2374 .Cm EXIT
2375 may be used to specify an
2376 .Ar action
2377 that is performed when the shell terminates.
2378 The
2379 .Ar action
2380 may be an empty string or a dash
2381 .Pq Ql - ;
2382 the former causes the specified signal to be ignored
2383 and the latter causes the default action to be taken.
2384 Omitting the
2385 .Ar action
2386 is another way to request the default action, for compatibility reasons this
2387 usage is not recommended though.
2388 In a subshell environment,
2389 the shell resets trapped (but not ignored) signals to the default action.
2390 The
2391 .Ic trap
2392 command has no effect on signals that were ignored on entry to the shell.
2393 .Pp
2394 Option
2395 .Fl l
2396 causes the
2397 .Ic trap
2398 command to display a list of valid signal names.
2399 .It Ic true
2400 A null command that returns a 0 (true) exit value.
2401 .It Ic type Op Ar name ...
2402 Interpret each
2403 .Ar name
2404 as a command and print the resolution of the command search.
2405 Possible resolutions are:
2406 shell keyword, alias, special shell builtin, shell builtin, command,
2407 tracked alias
2408 and not found.
2409 For aliases the alias expansion is printed;
2410 for commands and tracked aliases
2411 the complete pathname of the command is printed.
2412 .It Ic ulimit Oo Fl HSabcdflmnstuv Oc Op Ar limit
2413 Set or display resource limits (see
2414 .Xr getrlimit 2 ) .
2415 If
2416 .Ar limit
2417 is specified, the named resource will be set;
2418 otherwise the current resource value will be displayed.
2419 .Pp
2420 If
2421 .Fl H
2422 is specified, the hard limits will be set or displayed.
2423 While everybody is allowed to reduce a hard limit,
2424 only the superuser can increase it.
2425 The
2426 .Fl S
2427 option
2428 specifies the soft limits instead.
2429 When displaying limits,
2430 only one of
2431 .Fl S
2432 or
2433 .Fl H
2434 can be given.
2435 The default is to display the soft limits,
2436 and to set both the hard and the soft limits.
2437 .Pp
2438 Option
2439 .Fl a
2440 causes the
2441 .Ic ulimit
2442 command to display all resources.
2443 The parameter
2444 .Ar limit
2445 is not acceptable in this mode.
2446 .Pp
2447 The remaining options specify which resource value is to be
2448 displayed or modified.
2449 They are mutually exclusive.
2450 .Bl -tag -width indent
2451 .It Fl b Ar sbsize
2452 The maximum size of socket buffer usage, in bytes.
2453 .It Fl c Ar coredumpsize
2454 The maximal size of core dump files, in 512-byte blocks.
2455 .It Fl d Ar datasize
2456 The maximal size of the data segment of a process, in kilobytes.
2457 .It Fl f Ar filesize
2458 The maximal size of a file, in 512-byte blocks.
2459 .It Fl l Ar lockedmem
2460 The maximal size of memory that can be locked by a process, in
2461 kilobytes.
2462 .It Fl m Ar memoryuse
2463 The maximal resident set size of a process, in kilobytes.
2464 .It Fl n Ar nofiles
2465 The maximal number of descriptors that could be opened by a process.
2466 .It Fl s Ar stacksize
2467 The maximal size of the stack segment, in kilobytes.
2468 .It Fl t Ar time
2469 The maximal amount of CPU time to be used by each process, in seconds.
2470 .It Fl u Ar userproc
2471 The maximal number of simultaneous processes for this user ID.
2472 .It Fl v Ar virtualmem
2473 The maximal virtual size of a process, in kilobytes.
2474 .El
2475 .It Ic umask Oo Fl S Oc Op Ar mask
2476 Set the file creation mask (see
2477 .Xr umask 2 )
2478 to the octal or symbolic (see
2479 .Xr chmod 1 )
2480 value specified by
2481 .Ar mask .
2482 If the argument is omitted, the current mask value is printed.
2483 If the
2484 .Fl S
2485 option is specified, the output is symbolic, otherwise the output is octal.
2486 .It Ic unalias Oo Fl a Oc Op Ar name ...
2487 The specified alias names are removed.
2488 If
2489 .Fl a
2490 is specified, all aliases are removed.
2491 .It Ic unset Oo Fl fv Oc Ar name ...
2492 The specified variables or functions are unset and unexported.
2493 If the
2494 .Fl v
2495 option is specified or no options are given, the
2496 .Ar name
2497 arguments are treated as variable names.
2498 If the
2499 .Fl f
2500 option is specified, the
2501 .Ar name
2502 arguments are treated as function names.
2503 .It Ic wait Op Ar job
2504 Wait for the specified
2505 .Ar job
2506 to complete and return the exit status of the last process in the
2507 .Ar job .
2508 If the argument is omitted, wait for all jobs to complete
2509 and return an exit status of zero.
2510 .El
2511 .Ss Commandline Editing
2512 When
2513 .Nm
2514 is being used interactively from a terminal, the current command
2515 and the command history
2516 (see
2517 .Ic fc
2518 in
2519 .Sx Built-in Commands )
2520 can be edited using
2521 .Nm vi Ns -mode
2522 command line editing.
2523 This mode uses commands similar
2524 to a subset of those described in the
2525 .Xr vi 1
2526 man page.
2527 The command
2528 .Dq Li "set -o vi"
2529 (or
2530 .Dq Li "set -V" )
2531 enables
2532 .Nm vi Ns -mode
2533 editing and places
2534 .Nm
2535 into
2536 .Nm vi
2537 insert mode.
2538 With
2539 .Nm vi Ns -mode
2540 enabled,
2541 .Nm
2542 can be switched between insert mode and command mode by typing
2543 .Aq ESC .
2544 Hitting
2545 .Aq return
2546 while in command mode will pass the line to the shell.
2547 .Pp
2548 Similarly, the
2549 .Dq Li "set -o emacs"
2550 (or
2551 .Dq Li "set -E" )
2552 command can be used to enable a subset of
2553 .Nm emacs Ns -style
2554 command line editing features.
2555 .Sh ENVIRONMENT
2556 The following environment variables affect the execution of
2557 .Nm :
2558 .Bl -tag -width ".Ev LANGXXXXXX"
2559 .It Ev ENV
2560 Initialization file for interactive shells.
2561 .It Ev LANG , Ev LC_*
2562 Locale settings.
2563 These are inherited by children of the shell,
2564 and is used in a limited manner by the shell itself.
2565 .It Ev PWD
2566 An absolute pathname for the current directory,
2567 possibly containing symbolic links.
2568 This is used and updated by the shell.
2569 .It Ev TERM
2570 The default terminal setting for the shell.
2571 This is inherited by children of the shell, and is used in the history
2572 editing modes.
2573 .El
2574 .Pp
2575 Additionally, all environment variables are turned into shell variables
2576 at startup,
2577 which may affect the shell as described under
2578 .Sx Special Variables .
2579 .Sh EXIT STATUS
2580 Errors that are detected by the shell, such as a syntax error, will
2581 cause the shell to exit with a non-zero exit status.
2582 If the shell is not an interactive shell, the execution of the shell
2583 file will be aborted.
2584 Otherwise the shell will return the exit status of the last command
2585 executed, or if the
2586 .Ic exit
2587 builtin is used with a numeric argument, it
2588 will return the argument.
2589 .Sh SEE ALSO
2590 .Xr builtin 1 ,
2591 .Xr chsh 1 ,
2592 .Xr echo 1 ,
2593 .Xr ed 1 ,
2594 .Xr emacs 1 Pq Pa pkgsrc/editors/emacs ,
2595 .Xr kill 1 ,
2596 .Xr printf 1 ,
2597 .Xr pwd 1 ,
2598 .Xr test 1 ,
2599 .Xr vi 1 ,
2600 .Xr execve 2 ,
2601 .Xr getrlimit 2 ,
2602 .Xr umask 2 ,
2603 .Xr wctype 3 ,
2604 .Xr editrc 5 ,
2605 .Xr script 7
2606 .Sh HISTORY
2607 A
2608 .Nm
2609 command, the Thompson shell, appeared in
2610 .At v1 .
2611 It was superseded in
2612 .At v7
2613 by the Bourne shell, which inherited the name
2614 .Nm .
2615 .Pp
2616 This version of
2617 .Nm
2618 was rewritten in 1989 under the
2619 .Bx
2620 license after the Bourne shell from
2621 .At V.4 .
2622 .Sh AUTHORS
2623 This version of
2624 .Nm
2625 was originally written by
2626 .An Kenneth Almquist .
2627 .Sh BUGS
2628 The
2629 .Nm
2630 utility does not recognize multibyte characters other than UTF-8.
2631 Splitting using
2632 .Va IFS
2633 and the line editing library
2634 .Xr editline 3
2635 do not recognize multibyte characters.
2636 .Pp
2637 The characters generated by filename completion should probably be quoted
2638 to ensure that the filename is still valid after the input line has been
2639 processed.