1.\" Copyright (c) 1990 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.proprietary.roff% 5.\" 6.\" @(#)sh.1 6.8 (Berkeley) 08/09/91 7.\" 8.Dd 9.Dt SH 1 10.Os ATT 7th 11.Sh NAME 12.Nm sh 13.Nd shell command interpreter 14.Sh SYNOPSIS 15.Nm sh 16.Op Fl ceiknrstuvx 17.Op arg 18.Ar ... 19.Sh DESCRIPTION 20.Nm Sh 21is a command programming language that executes commands read from a terminal 22or a file. The shell this page describes is called the 23.Em Bourne 24shell. 25.Pp 26Command line options: 27.Pp 28If the first character of argument 0 is 29.Fl , 30commands are read from 31.Pa $HOME/.profile , 32if such a file exists. 33The following flags are interpreted by the shell when it is invoked. 34.Bl -tag -width flag 35.It Fl c Ar string 36Commands are read from 37.Ar string. 38.It Fl s 39If the 40.Fl s 41flag is present or if no arguments remain 42then commands are read from the standard input. 43Shell output is written to file descriptor 2. 44.It Fl i 45If the 46.Fl i 47flag is present or 48if the shell input and output are attached to a terminal (as told by 49.Xr getty ) 50then this shell is 51.Em interactive . 52In this case the terminate signal 53.Dv SIGTERM 54(see 55.Xr sigvec 2 ) 56is ignored (so that 'kill 0' 57does not kill an interactive shell) and the interrupt signal 58.Dv SIGINT 59is caught and ignored (so that 60.Xr wait 61is interruptible). 62In all cases 63.Dv SIGQUIT 64is ignored by the shell. 65.El 66.Pp 67This next set of options can be used on the command line invoking 68the 69.Nm sh 70or set with the interactive command 71.Ic set . 72.Bl -tag -width Fl e 73.It Fl e 74If non interactive, exit immediately if a command fails. 75.It Fl k 76All keyword arguments are placed in the environment for a command, 77not just those that precede the command name. 78.It Fl n 79Read commands but do not execute them. 80.It Fl t 81Exit after reading and executing one command. 82.It Fl u 83Treat unset variables as an error when substituting. 84.It Fl v 85Print shell input lines as they are read. 86.It Fl x 87Print commands and their arguments as they are executed. 88.It Fl 89Turn off the 90.Fl x 91and 92.Fl v 93options. 94.El 95.Ss Commands 96A 97.Em simple-command 98is a sequence of non blank 99.Em words 100separated by blanks (a blank is a 101.Em tab 102or a 103.Em space ) . 104The first word specifies the name of the command to be executed. 105Except as specified below the remaining words are passed as arguments 106to the invoked command. 107The command name is passed as argument 0 (see 108.Xr execve 2 ) . 109The 110.Em value 111of a simple-command is its exit status 112if it terminates normally or 113.Li 200+ Ns Ns Em status 114if it terminates abnormally (see 115.Ar sigvec 2 116for a list of status values). 117.Pp 118A 119.Em pipeline 120is a sequence of one or more 121.Em commands 122separated by 123.Sq Nm \&| . 124The standard output of each command but the last is connected by a 125.Xr pipe 2 126to the standard input of the next command. 127Each command is run as a separate process; 128the shell waits for the last command to terminate. 129.Pp 130A 131.Em list 132is a sequence of one or more 133.Em pipelines 134separated by 135.Nm \&; , 136.Nm \&& , 137.Nm \&&& 138or 139.Nm \&| 140or 141.Nm \&|\&| 142and optionally terminated by 143.Nm \&; 144or 145.Nm \&& . 146.Nm \&; 147and 148.Nm \&& 149have equal precedence which is lower than that of 150.Nm \&&& 151and 152.Nm \&|\&| , 153.Nm && 154and 155.Nm \&|\&| , 156also have equal precedence. 157A semicolon causes sequential execution; an ampersand causes the preceding 158.Em pipeline 159to be executed without waiting for it to finish. The symbol 160.Nm \&&& 161.Pq Nm \&|\&| 162causes the 163.Em list 164following to be executed only if the preceding 165.Em pipeline 166returns a zero (non zero) value. Newlines may appear in a 167.Em list , 168instead of semicolons, to delimit commands. 169.Pp 170A 171.Em command 172is either a simple-command or one of the following. 173The value returned by a command is that of the 174last simple-command executed in the command. 175.Bl -tag -width Fl 176.It Xo 177.Ic for Ar name 178.Op Ic \&in Ar word ... 179.Ic \&do Ar list Ic done 180.Xc 181Each time a 182.Ic for 183command is executed 184.Ar name 185is set to the next word in the 186.Ic for 187word list. 188If 189.Ic \&in 190.Ar word \&... 191is omitted, 192.Ic \&in 193.Dq Ic \&$@ 194is assumed. 195Execution ends when there are no more words in the list. 196.It Xo 197.Ic case Ar word 198.Ic \&in 199.Oo Ar pattern Op Ar \&| pattern 200.Ar ... Ic \&) Ar list Ic \&;; Oc 201.Ar ... Ar esac 202.Xc 203A 204.Ic case 205command executes the 206.Ar list 207associated with the first pattern that matches 208.Ar word . 209The form of the patterns is the same as that used for file name generation. 210.It Xo 211.Ic \&if Ar list 212.Ic then Ar list 213.Op Ic elif Ar list Ic then Ar list 214.Ar ... 215.Op Ic else Ar list Ic 216.No \&fi 217.Xc 218The 219.Ar list 220following 221.Ic \&if 222is executed and if it returns zero the 223.Ar list 224following 225.Ic then 226is executed. Otherwise, the 227.Ar list 228following 229.Ic elif 230is executed and if its value is zero the 231.Ar list 232following 233.Ic then 234is executed. Failing that the 235.Ic else 236.Ar list 237is executed. 238.It Xo 239.Ic while Ar list 240.Op Ic \&do Ar list 241.Ic done 242.Xc 243A 244.Ic while 245command repeatedly executes the 246.Ic while 247.Ar list 248and if its value is zero executes the 249.Ic \&do 250.Ar list ; 251otherwise the loop terminates. The value returned by a 252.Ic while 253command is that of the last executed command in the 254.Ic \&do 255.Ar list . 256.Ic until 257may be used in place of 258.Ic while 259to negate the loop termination test. 260.It Ic \&( Ar list Ic \&) 261Execute 262.Ar list 263in a subshell. 264.It Ic \&{ Ar list Ic \&} 265.Ar list 266is simply executed. 267.El 268.Pp 269The following words are only recognized as the first word of a command 270and when not quoted. 271.Bd -filled -offset indent -compact 272.Nm if then else elif fi case in esac 273.Nm for while until do done \&{ \&} 274.Ed 275.Ss Command substitution 276The standard output from a command enclosed in a pair of back quotes 277.Pq Ic \&`` 278may be used as part or all of a word; trailing newlines are removed. 279.Ss Parameter substitution 280The character 281.Ic \&$ 282is used to introduce substitutable parameters. 283Positional parameters may be assigned values by 284.Ic set . 285Variables may be set by writing 286.Pp 287.Bd -filled -offset indent -compact 288.Ar name=value 289.Op Ar name=value 290\&... 291.Ed 292.Pp 293.Bl -tag -width flag 294.It Ic \&$\&{ Ns Ar parameter Ns Ic \&} 295A 296.Ar parameter 297is a sequence of letters, digits or underscores (a 298.Ar name ) , 299a digit, or any of the characters 300.Nm "\&* \&@ \&# \&? \&\- \&$ \&!\ " . 301The value, if any, of the parameter is substituted. 302The braces are required only when 303.Ar parameter 304is followed by a letter, digit, or underscore 305that is not to be interpreted as part of its name. If 306.Ar parameter 307is a digit, it is a positional parameter. If 308.Ar parameter 309is 310.Ic \&* 311or 312.Ic \&@ 313then all the positional parameters, starting with 314.Ic $1 , 315are substituted separated by spaces. 316.Ic $0 317is set from argument zero when the shell is invoked. 318.Sm off 319.It Xo 320.Ic \&$\&{ Ar parameter 321.Ic - Ar word Ic \&} 322.Xc 323.Sm on 324If 325.Ar parameter 326is set, substitute its value; otherwise substitute 327.Ar word . 328.Sm off 329.It Xo 330.Ic \&$\&{ Ar parameter 331.Ic \&= Ar word Ic \&} 332.Xc 333.Sm on 334If 335.Ar parameter 336is not set, set it to 337.Ar word ; 338the value of the parameter is then substituted. 339Positional parameters may not be assigned to in this way. 340.Sm off 341.It Xo 342.Ic \&$\&{ Ar parameter 343.Ic \&? Ar word Ic \&} 344.Xc 345.Sm on 346If 347.Ar parameter 348is set, substitute its value; otherwise, print 349.Ar word 350and exit from the shell. If 351.Ar word 352is omitted, a standard message is printed. 353.Sm off 354.It Xo 355.Ic \&$\&{ Ar parameter 356.Ic \&+ Ar word Ic \&} 357.Xc 358.Sm on 359If 360.Ar parameter 361is set, substitute 362.Ar word ; 363otherwise substitute nothing. 364.El 365.Pp 366In the above 367.Ar word 368is not evaluated unless it is to be used as the substituted string. 369(So that, for example, 370.Li echo ${d\-'pwd'} 371will only execute 372.Ar pwd 373if 374.Ar d 375is unset.) 376.Pp 377The following 378.Ar parameters 379are automatically set by the shell. 380.Pp 381.Bl -tag -width flag -compact 382.It Ic \&# 383The number of positional parameters in decimal. 384.It Fl 385Options supplied to the shell on invocation or by 386.Ar set . 387.It Ic \&? 388The value returned by the last executed command in decimal. 389.It Ic \&$ 390The process number of this shell. 391.It Ic \&! 392The process number of the last background command invoked. 393.El 394.Pp 395The following 396.Ar parameters 397are used but not set by the shell. 398.Pp 399.Bl -tag -width flag -compact 400.It Ev HOME 401The default argument (home directory) for the 402.Ic cd 403command. 404.It Ev PATH 405The search path for commands (see 406.Ar execution ) . 407.It Ev MAIL 408If this variable is set to the name of 409a mail file, the shell informs the user of 410the arrival of mail in the specified file. 411.It Ev PS1 412Primary prompt string, by default '$ '. 413.It Ev PS2 414Secondary prompt string, by default '> '. 415.It Ev IFS 416Internal field separators, normally 417.Em space , 418.Em tab , 419and 420.Em newline . 421.Ev IFS 422is ignored if 423.Nm sh 424is running as root or if the effective user id differs from the real user id. 425.El 426.Ss Blank interpretation 427After parameter and command substitution, 428any results of substitution are scanned for internal field separator 429characters (those found in 430.Ic $ Ns Ev IFS ) 431and split into distinct arguments where such characters are found. 432Explicit null arguments ("" or \'\') are retained. 433Implicit null arguments (those resulting from 434.Em parameters 435that have no values) are removed. 436.Ss File name generation 437Following substitution, each command word is scanned for the characters 438.Ic \&* , 439.Ic \&? 440and 441.Ic \&[ . 442If one of these characters appears, the word is regarded as a pattern. 443The word is replaced with alphabetically sorted file names that match the 444pattern. If no file name is found that matches the pattern, 445the word is left unchanged. The character 446.Ic \&. 447at the start of a file name or immediately following a 448.Ic \&/ , 449and the character 450.Ic \&/ , 451must be matched explicitly. 452.Pp 453.Bl -tag -width x...x -compact 454.It Ic \&*\& 455Matches any string, including the null string. 456.It Ic \&? 457Matches any single character. 458.It Ic \&[...] 459Matches any one of the characters enclosed. 460A pair of characters separated by 461.Fl 462matches any character lexically between the pair. 463.El 464.Ss Quoting 465The following characters have a special meaning to the shell 466and cause termination of a word unless quoted. 467.Bd -filled -offset indent 468.Ic "\&; \&& \&( \&) \&| \&< \&> newline space tab" 469.Ed 470.Pp 471A character may be 472.Ar quoted 473by preceding it with a 474.Sq Ic \e . 475.Ic \enewline 476is ignored. 477All characters enclosed between a pair of quote marks 478.Pq Sq , 479except a single quote, are quoted. Inside double quotes 480.Pq Dq 481parameter and command substitution occurs and 482.Ic \e 483quotes the characters 484.Ic \e' " 485and 486.Ic \&$ . 487.Pp 488.Bd -filled -offset indent -compact 489.Dq Ic \&$\&* 490is equivalent to 491.Dq Ic "$1 $2" \&... 492whereas 493.Ed 494.Bd -filled -offset indent -compact 495.Dq Ic $@ 496is equivalent to 497.Dq Ic "$1" 498.Dq Ic "$2" 499... . 500.Ed 501.Ss Prompting 502When used interactively, the shell prompts with the value of 503.Ev PS1 504before reading a command. 505If at any time a newline is typed and further input is needed 506to complete a command, the secondary prompt 507.Ic $ Ns Ev PS2 508is issued. 509.Ss Input/Output 510Before a command is executed its input and output 511may be redirected using a special notation interpreted by the shell. 512The following may appear anywhere in a simple-command 513or may precede or follow a 514.Ar command 515and are not passed on to the invoked command. 516Substitution occurs before 517.Ar word 518or 519.Ar digit 520is used. 521.Bl -tag -width Ic 522.It Ic \&< Ar word 523Use file 524.Ar word 525as standard input (file descriptor 0). 526.It Ic \&> Ar word 527Use file 528.Ar word 529as standard output (file descriptor 1). 530If the file does not exist, it is created; 531otherwise it is truncated to zero length. 532.It Ic \&>\&> Ar word 533Use file 534.Ar word 535as standard output. 536If the file exists, output is appended (by seeking to the end); 537otherwise the file is created. 538.It Ic \&<\&< Ar word 539The shell input is read up to a line the same as 540.Ar word , 541or end of file. 542The resulting document becomes the standard input. 543If any character of 544.Ar word 545is quoted, no interpretation is placed upon the characters of the document; 546otherwise, parameter and command substitution occurs, 547.Ic \enewline 548is ignored, and 549.Ic \e 550is used to quote the characters 551.Ic \&$ \&' 552and the first character of 553.Ar word . 554.It Ic \&<\&& Ar digit 555The standard input is duplicated from file descriptor 556.Ar digit ; 557see 558.Xr dup 2 . 559Similarly for the standard output using 560.Ic \&> . 561.It Ic \&< \&\- 562The standard input is closed. 563Similarly for the standard output using 564.Ic \&> . 565.El 566.Pp 567If one of the above is preceded by a digit, the 568file descriptor created is that specified by the digit 569(instead of the default 0 or 1). For example, 570.Pp 571.Dl \&... 2>&1 572.Pp 573creates file descriptor 2 to be a duplicate 574of file descriptor 1. 575.Pp 576If a command is followed by 577.Ic \&& 578then the default standard input for the command is the empty file 579.Pq Pa dev/null . 580Otherwise, the environment for the execution of a command contains the 581file descriptors of the invoking shell as modified by input 582output specifications. 583.Ss Environment 584The environment is a list of name-value pairs that is passed to 585an executed program in the same way as a normal argument list; see 586.Xr execve 2 587and 588.Xr environ 7 . 589The shell interacts with the environment in several ways. 590On invocation, the shell scans the environment and creates a 591.Ar parameter 592for each name found, giving it the corresponding value. 593Executed commands inherit the same environment. 594If the user modifies the values of these 595.Ar parameters 596or creates new ones, none of these affects the environment unless the 597.Ic export 598command is used to bind the shell's 599.Ar parameter 600to the environment. 601The environment seen by any executed command is thus composed 602of any unmodified name-value pairs originally inherited by the shell, 603plus any modifications or additions, all of which must be noted in 604.Ic export 605commands. 606.Pp 607The environment for any 608.Ar simple-command 609may be augmented by prefixing it with one or more assignments to 610.Ar parameters . 611Thus these two lines are equivalent 612.Pp 613.Dl TERM=450 cmd args 614.Dl (export TERM; TERM=450; cmd args) 615.Pp 616If the 617.Fl k 618flag is set, 619.Ar all 620keyword arguments are placed in the environment, 621even if they occur after the command name. 622The following prints 623.Ql a=b c 624and 625.Ql c : 626.Bd -literal -offset indent 627echo a=b c 628set \-k 629echo a=b c 630.Ed 631.Ss Signals 632The 633.Dv INTERRUPT 634and 635.Dv QUIT 636signals for an invoked 637command are ignored if the command is followed by 638.Ic \&& ; 639otherwise signals have the values inherited by the shell from its parent. 640(But see also 641.Ic trap . ) 642.Ss Execution 643Each time a command is executed the above substitutions are carried out. 644Except for the 'special commands' listed below a new process is created and 645an attempt is made to execute the command via an 646.Xr execve 2 . 647.Pp 648The shell parameter 649.Ic \&$ Ns Ev PATH 650defines the search path for the directory containing the command. 651Each alternative directory name is separated by a colon 652.Pq Ic \&: . 653The default path is 654.Pa :/bin:/usr/bin . 655If the command name contains a 656.Ql / , 657the search path is not used. 658Otherwise, each directory in the path is searched for an executable file. 659If the file has execute permission but is not an 660.Pa a.out 661file, it is assumed to be a file containing shell commands. 662A subshell (i.e., a separate process) is spawned to read it. 663A parenthesized command is also executed in a subshell. 664.Ss Special commands 665The following commands are executed in the shell process 666and except where specified 667no input output redirection is permitted for such commands. 668.Bl -tag -width indent 669.It Ic \&# 670For non-interactive shells, everything following the 671.Ic \&# 672is treated as a comment, i.e. the rest of the line is ignored. 673For interactive shells, the 674.Ic \&# 675has no special effect. 676.It Ic \&:\& 677No effect; the command does nothing. 678.It Ic \&. Ar file 679Read and execute commands from 680.Ar file 681and return. The search path 682.Ic \&$ Ns Ev PATH 683is used to find the directory containing 684.Ar file . 685.It Ic break Op Ar n 686Exit from the enclosing 687.Ic for 688or 689.Ic while 690loop, if any. 691If 692.Ar n 693is specified, break 694.Ar n 695levels. 696.It Ic continue Op Ar n 697Resume the next iteration of the enclosing 698.Ic for 699or 700.Ic while 701loop. If 702.Ar n 703is specified, resume at the 704.Ar n Ns 'th 705enclosing loop. 706.It Ic cd Op Ar arg 707Change the current directory to 708.Ar arg . 709The shell parameter 710.Ic \&$ Ns Ev HOME 711is the default 712.Ar arg . 713.It Ic eval Op Ar arg \&... 714The arguments are read as input to the shell 715and the resulting command(s) executed. 716.It Ic exec Op Ar arg \&... 717The command specified by the arguments is executed in place of this shell 718without creating a new process. 719Input output arguments may appear and if no other 720arguments are given cause the shell input output to be modified. 721.It Ic exit Op Ar n 722Causes a non interactive shell to exit with the exit status specified by 723.Ar n . 724If 725.Ar n 726is omitted, the exit status is that of the last command executed. 727(An end of file will also exit from the shell.) 728.It Ic export Op Ar name ... 729The given names are marked for automatic export to the 730.Ar environment 731of subsequently-executed commands. 732If no arguments are given, a list of exportable names is printed. 733.It Ic login Op Ar arg ... 734Equivalent to 735.Ql exec login arg ... . 736.It Ic read Ar name \&... 737One line is read from the standard input; 738successive words of the input are assigned to the variables 739.Ar name 740in order, with leftover words to the last variable. 741The return code is 0 unless the end-of-file is encountered. 742.It Ic readonly Op Ar name \&... 743The given names are marked readonly and 744the values of the these names may not be changed 745by subsequent assignment. 746If no arguments are given, a list of all readonly names is printed. 747.It Xo 748.Ic set Oo Fl eknptuvx Op Ar arg ... 749.Oc 750.Xc 751The set flags are described in the options section at the beginning 752of this man page. 753The current set of flags may be found in 754.Ic \&$\- . 755.Pp 756Remaining arguments after the flag are positional 757parameters and are assigned, in order, to 758.Ic \&$1 , 759.Ic \&$2 , 760etc. If no arguments are given, the values of all names are printed. 761.It Ic shift 762The positional parameters from 763.Ic \&$2 ... 764are renamed 765.Ic $1 ... 766.It Ic times 767Print the accumulated user and system times for processes run from the shell. 768.It Xo 769.Ic trap Op Ar arg 770.Op Ar n 771.Ar ... 772.Xc 773.Ar Arg 774is a command to be read and executed when the shell receives signal(s) 775.Ar n . 776(Note that 777.Ar arg 778is scanned once when the trap is set and once when the trap is taken.) 779Trap commands are executed in order of signal number. If 780.Ar arg 781is absent, all trap(s) 782.Ar n 783are reset to their original values. 784If 785.Ar arg 786is the null 787string, this signal is ignored by the shell and by invoked commands. 788If 789.Ar n 790is 0, the command 791.Ar arg 792is executed on exit from the shell, otherwise upon receipt of signal 793.Ar n 794as numbered in 795.Xr sigvec 2 . 796.Ic Trap 797with no arguments prints a list of commands associated with each signal number. 798.It Ic umask Op Ar nnn 799The user file creation mask is set to the octal value 800.Ar nnn 801(see 802.Xr umask 2 ) . 803If 804.Ar nnn 805is omitted, the current value of the mask is printed. 806.It Ic wait Op Ar n 807Wait for the specified process and report its termination status. If 808.Ar n 809is not given, all currently active child processes are waited for. 810The return code from this command is that of the process waited for. 811.El 812.Sh FILES 813.Bl -tag -width xhome/.profile -compact 814.It Pa $HOME/.profile 815User customized environment variables. 816.It Pa /tmp/sh* 817Default temporary file directory. 818.It Pa /dev/null 819Bit bucket. 820.El 821.Sh SEE ALSO 822.Xr csh 1 , 823.Xr test 1 , 824.Xr execve 2 , 825.Xr environ 7 826.Sh DIAGNOSTICS 827Errors detected by the shell, such as syntax errors cause the shell 828to return a non zero exit status. 829If the shell is being used non interactively 830then execution of the shell file is abandoned. 831Otherwise, the shell returns the exit status of 832the last command executed (see also 833.Ic exit ) . 834.Sh HISTORY 835The 836.Nm sh 837shell appeared in 838.At v6 . 839.Sh BUGS 840If 841.Ic \&<\&< 842is used to provide standard input to an asynchronous 843process invoked by 844.Ic \&& , 845the shell gets mixed up about naming the input document. 846A garbage file 847.Pa /tmp/sh* 848is created, and the shell complains about 849not being able to find the file by another name. 850