1.\" $OpenBSD: sh.1,v 1.130 2015/10/12 12:34:42 jmc Exp $ 2.\" 3.\" Copyright (c) 2015 Jason McIntyre <jmc@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: October 12 2015 $ 18.Dt SH 1 19.Os 20.Sh NAME 21.Nm sh 22.Nd command language interpreter 23.Sh SYNOPSIS 24.Nm sh 25.Op Fl abCefhimnuvx 26.Op Fl o Ar option 27.Op Fl c Ar string | Fl s | Ar file 28.Sh DESCRIPTION 29The 30.Nm 31utility is a 32.Em command language interpreter : 33it reads its input, 34breaks it down into parts, 35and then executes those parts. 36Its chief uses are in interfacing between the user and the operating system, 37reading commands on the command line, 38and in chaining together groups of commands in a very flexible manner, 39through a shell script. 40.Pp 41This version of 42.Nm 43is actually 44.Nm ksh 45in disguise. 46As such, it will also accept options documented in 47.Xr ksh 1 . 48This manual page describes only features 49relevant to a POSIX compliant 50.Nm . 51If portability is a concern, 52use only those features described in this page. 53.Pp 54The shell receives input as follows: 55.Pp 56.Bl -tag -width "-c stringXXX" -offset indent -compact 57.It Fl c Ar string 58Read commands from 59.Ar string . 60.It Fl s 61Read commands from standard input 62(the default). 63.It Ar file 64Read commands from 65.Ar file . 66.El 67.Pp 68The options below can be specified with a 69.Sq Cm + 70rather than 71.Sq Fl , 72meaning to unset the option. 73They can also be set or unset using the 74.Ic set 75command. 76Some options have equivalent long names, 77indicated at the start of the description, 78which can be used with the 79.Fl o 80option. 81.Bl -tag -width Ds 82.It Fl a 83Allexport. 84Variable assignments are exported to all child processes 85of the running shell. 86If the assignment precedes a command it does not persist 87after that command has finished running, 88unless the command is a special builtin 89or one of the builtins 90.Ic getopts 91or 92.Ic read 93makes the assignment. 94.It Fl b 95Notify. 96The user is given notice asynchronously when background jobs complete. 97.It Fl C 98Noclobber. 99Do not permit the redirection operator 100.Pq Sq > 101to clobber (overwrite) existing files. 102.It Fl e 103Errexit. 104Exit the shell immediately should an error occur or a command fail. 105For pipelines and 106.Cm && 107and 108.Cm || 109constructs, only exit if the last component fails. 110Errexit is ignored for 111.Ic while , 112.Ic until , 113.Ic if , 114and 115.Ic elif 116lists and pipelines beginning 117.Sq !\& . 118.It Fl f 119Noglob. 120Do not expand file name patterns. 121.It Fl h 122When a utility is first executed, 123hash (record) its location 124so that future invocations do not need to search for it. 125Builtins are not hashed, regardless of whether this option is set or not. 126This option is set by default for non-interactive shells. 127.It Fl i 128Enable behaviour convenient for an interactive shell. 129This option is set by default 130if the session is attached to a terminal. 131.It Fl m 132Monitor. 133Fully enable job control: 134enable the 135.Ic bg 136and 137.Ic fg 138builtins; 139report completion status when jobs finish; 140report when a foreground process stops; 141and report when a job changes status. 142The processes of a job share their own process group. 143This option is set by default for interactive shells. 144.It Fl n 145Noexec. 146Read commands but do not execute them \(en 147useful for checking syntax errors in scripts. 148This option is ignored for interactive shells. 149.It Fl o Ar option 150Specify an option by its long name. 151Those described below have no equivalent option letter: 152.Pp 153.Bl -tag -width "ignoreeof" -offset 3n -compact 154.It ignoreeof 155Ignore an end-of-file 156.Pq Sq ^D . 157EOF normally logs a user out, 158so setting this can prevent accidental logouts 159(the user will need to explicitly use the 160.Ic exit 161command). 162.It nolog 163Do not enter function definitions into command history. 164.It posix 165Enable POSIX mode 166(see 167.Sx STANDARDS ) . 168.It vi 169Enable 170.Xr vi 1 171command line editing. 172.El 173.It Fl u 174Nounset. 175If a command references an unset parameter, 176write an error to standard output instead of executing the command. 177This option is ignored for the special parameters 178.Sq * 179and 180.Sq @ . 181If the shell is not interactive, 182immediately exit. 183.It Fl v 184Verbose. 185Write input to standard error after reading it. 186.It Fl x 187Xtrace. 188Write a trace for each command to standard error after expanding it, 189and before executing it. 190.El 191.Sh BUILTINS 192The shell has a number of 193.Em built-ins 194available: 195utilities that are included as part of the shell. 196The shell does not need to search for them 197and can execute them directly. 198.Pp 199A number of built-ins are special in that 200a syntax error can cause a running shell to abort, 201and, after the built-in completes, 202variable assignments remain in the current environment. 203The following built-ins are special: 204.Ic .\& , :\& , break , continue , 205.Ic eval , exec , exit , export , 206.Ic readonly , return , set , shift , 207.Ic times , trap , 208and 209.Ic unset . 210.Pp 211The built-ins available to 212.Nm 213are listed below. 214Unless otherwise indicated, 215they exit 0 on success, 216and >0 if an error occurs. 217.Bl -tag -width 2n 218.It Ic .\& Ar file 219Execute the commands in 220.Ar file , 221in the current environment. 222The actual file need not be executable, 223and its location is determined by searching 224.Ev PATH 225if there are no slashes in the filename. 226The exit status is that of the last command returned, 227or zero if no commands were executed. 228If no readable file can be found, 229a non-interactive shell will abort; 230an interactive shell writes an error message 231and returns a non-zero exit status. 232.It Ic :\& Op Ar arg ... 233The 234.Ic :\& 235command does nothing \(en 236it is a placeholder for when a command is required. 237Its exit status is always zero. 238.It Ic alias Op Ar name Ns Oo = Ns Ar value Oc Ar ... 239Define an alias 240.Ar name 241to 242.Ar value ; 243when the shell encounters a command name that is an alias, 244its value is substituted. 245If 246.Ar value 247ends in a blank, 248the next word is checked for alias substitution too. 249If only a 250.Ar name 251is specified, 252display the value of that alias; 253if no arguments are given, 254list all aliases and their values. 255Aliases are visible in the current environment and that of subshells, 256but not by the parent process of the current shell 257or by utilities invoked by it. 258.It Ic bg Op Ar id ... 259Select a job by 260.Ar id 261(see the 262.Ic jobs 263command, below) 264to run in the background. 265The default job is 266.Qq %+ . 267.It Ic break Op Ar n 268Exit from the innermost 269.Ic for , while , 270or 271.Ic until 272loop, 273or from loop level 274.Ar n . 275.It Ic cd Oo Fl L | P Oc Op Ar dir 276Change the current working directory to 277.Ar dir , 278or 279.Ev $HOME 280by default. 281If 282.Ar dir 283is set to 284.Sq - , 285change to the previous working directory and 286print the (now current) working directory. 287If 288.Ar dir 289does not begin with a slash or dot, 290.Ev CDPATH 291is searched for the directory. 292.Pp 293The options to the 294.Ic cd 295command are as follows: 296.Pp 297.Bl -tag -width Ds -offset 3n -compact 298.It Fl L 299Do not resolve symbolic links before processing 300.Qq .. 301components. 302.It Fl P 303Resolve symbolic links before processing 304.Qq .. 305components. 306.El 307.It Ic command Oo Fl p | V | v Oc Ar command Op Ar arg ... 308Invoke 309.Ar command 310(and any optional arguments), 311overriding any functions with the same name, 312and without any of the properties that special built-ins have. 313.Pp 314The options to 315.Ic command 316are as follows: 317.Pp 318.Bl -tag -width Ds -offset 3n -compact 319.It Fl p 320Use a default value for 321.Ev PATH 322to search for the command. 323.It Fl V 324Do not invoke 325.Ar command , 326but identify how the shell will interpret it 327(such as a function or special built-in). 328.It Fl v 329Do not invoke 330.Ar command , 331but identify the pathname the shell will use to run it. 332.El 333.Pp 334The exit status is that of 335.Ar command , 336or 126 if 337.Ar command 338could not be invoked, 339or 127 if an error occurred in 340.Ic command 341itself or 342.Ar command 343could not be found. 344If the options 345.Fl V 346or 347.Fl v 348are given, 349the exit status is 0 on success, 350or >0 if an error occurs. 351.It Ic continue Op Ar n 352Go directly to the next iteration of the innermost 353.Ic for , while , 354or 355.Ic until 356loop, 357or from loop level 358.Ar n . 359.It Ic eval Op Ar arg ... 360Concatenate the arguments given 361and interpret them as a command. 362The exit status is that of the resulting command, 363zero if no arguments are given, 364or >0 if the resulting command could not be correctly parsed. 365.It Ic exec Op Ar command Op Ar arg ... 366Replace the shell with 367.Ar command 368(and any optional arguments), 369without creating a new process. 370The exit status is that of 371.Ar command , 372or 126 if 373.Ar command 374could not be invoked, 375or 127 if 376.Ar command 377could not be found. 378If no command is given but a redirection happens, 379the exit status is 1\(en125; 380otherwise 381.Ic exec 382returns 0. 383.It Ic exit Op Ar n 384Exit the shell with exit status 385.Ar n , 386or that of the last command executed. 387.It Ic export Oo Fl p Oc Ar name Ns Oo = Ns Ar value Oc Ar ... 388Make the variable 389.Ar name 390visible to subsequently run commands, 391optionally setting it to 392.Ar value . 393.Pp 394The options to the 395.Ic export 396command are as follows: 397.Pp 398.Bl -tag -width Ds -offset 3n -compact 399.It Fl p 400List all exported variables in a manner that can be reinput to the shell. 401.El 402.It Ic false 403Return a false (non-zero) value. 404.It Xo 405.Ic fc 406.Op Fl lnr 407.Op Fl e Ar editor 408.Op Fl s Op Ar old Ns = Ns Ar new 409.Op Ar first Op Ar last 410.Xc 411Edit commands from command history using 412.Xr ed 1 . 413After editing, 414the new commands are executed by the shell. 415.Pp 416The options to the 417.Ic fc 418command are as follows: 419.Pp 420.Bl -tag -width "-s [old=new]" -offset 3n -compact 421.It Fl e Ar editor 422Edit commands using 423.Ar editor . 424See also 425.Ev FCEDIT . 426.It Fl l 427List the command history. 428.It Fl ln 429List the command history without command numbers. 430.It Fl r 431Edit or list 432.Pq Fl lr 433commands in reverse order. 434.It Fl s Op Ar old Ns = Ns Ar new 435Reexecute a single command 436without invoking an editor. 437The first occurrence of the string 438.Ar old 439in the command is replaced by 440.Ar new . 441.El 442.Pp 443A range of commands can be specified, 444.Ar first 445to 446.Ar last . 447Their format can be numerical, 448to select by command number; 449.Sq - Ns Ar n , 450to select a command executed that number of commands previous; 451or a string which matches the beginning of the command. 452If no range is given, 453the last command in command history is edited, 454or reexecuted 455.Pq Fl s , 456or the previous 16 commands in command history are listed 457.Pq Fl l . 458If 459.Ar first 460is newer than 461.Ar last , 462commands are processed in reverse order 463(as if 464.Fl r 465had been given); 466if either are out of range, 467the oldest or newest values are used. 468.It Ic fg Op Ar id ... 469Select a job by 470.Ar id 471(see the 472.Ic jobs 473command, below) 474to run in the foreground. 475The default job is 476.Qq %+ . 477.It Ic getopts Ar optstring name Op Ar arg ... 478When invoked, 479.Ic getopts 480processes the positional parameters 481(or any 482.Ar arg 483passed to it) 484as a list of options and option arguments. 485.Ic getopts 486sets the variable 487.Ar name 488to the option found, 489.Ev OPTARG 490to its argument, 491and 492.Ev OPTIND 493to the index of the next variable to be processed. 494.Pp 495The string 496.Ar optstring 497contains a list of acceptable options; 498a colon following an option indicates it may take an argument. 499If an option not recognised by 500.Ar optstring 501is found, 502.Ar name 503is set to 504.Sq ?\& ; 505if the first character of 506.Ar optstring 507is a colon, 508.Ev OPTARG 509is set to the unsupported option, 510otherwise an error message is displayed. 511.It Ic jobs Oo Fl l | p Oc Op Ar id ... 512Display the status of all jobs in the current shell environment, 513or those selected by 514.Ar id . 515.Pp 516The options to the 517.Ic jobs 518command are as follows: 519.Pp 520.Bl -tag -width Ds -offset 3n -compact 521.It Fl l 522Additionally display the process group ID. 523.It Fl p 524Display only the process group ID. 525.El 526.Pp 527Job 528.Ar id 529can be selected in one of the following ways: 530.Pp 531.Bl -tag -width "%?string" -offset 3n -compact 532.It %% 533The current job. 534.It %+ 535The current job. 536.It %- 537The previous job. 538.It % Ns Ar n 539Job number 540.Ar n . 541.It % Ns Ar string 542Job with command matching 543.Ar string . 544.It %? Ns Ar string 545Job with command containing 546.Ar string . 547.El 548.It Xo 549.Ic kill 550.Op Fl l Op Ar signal 551.Op Fl s Ar signal 552.Oo Fl Ar signal Oc Ar pid ... 553.Xc 554Send a signal, 555by default 556.Dv SIGTERM , 557to the process with ID 558.Ar pid . 559.Pp 560The options to the 561.Ic kill 562command are as follows: 563.Pp 564.Bl -tag -width "-l [signal]" -offset 3n -compact 565.It Fl l Op Ar signal 566List all supported signals, 567or the signal name corresponding to 568.Ar signal 569number or the exit status of a command killed by a signal. 570.It Fl s Ar signal 571Send the process 572.Ar signal 573name. 574.It Fl Ar signal 575Send the process 576.Ar signal 577name or number. 578.It Ar pid 579A process ID, 580process group ID, 581or a job ID (see 582.Ic jobs , 583above). 584The process ID 0 signals all processes in the current process group. 585.El 586.Pp 587The supported signal numbers are: 588.Pp 589.Bl -tag -width Ds -offset 3n -compact 590.It " 0" 591Do not signal a process, 592but determine whether an ID exists. 593.It " 1" 594.Dv SIGHUP : 595Terminal line hangup. 596.It " 2" 597.Dv SIGINT : 598Interrupt a program. 599.It " 3" 600.Dv SIGQUIT : 601Quit a program. 602.It " 6" 603.Dv SIGABRT : 604Call 605.Xr abort 3 . 606.It " 9" 607.Dv SIGKILL : 608Kill a program. 609Cannot be caught or ignored. 610.It "14" 611.Dv SIGALRM : 612Real-time timer expired. 613.It "15" 614.Dv SIGTERM : 615Software termination signal. 616.El 617.It Ic pwd Op Fl L | P 618Print the current working directory. 619.Pp 620The options to the 621.Ic pwd 622command are as follows: 623.Pp 624.Bl -tag -width Ds -offset 3n -compact 625.It Fl L 626Print the logical path to the current working directory 627i.e. display symbolic links followed. 628.It Fl P 629Print the physical path to the current working directory 630i.e. display symbolic links resolved. 631.El 632.Pp 633If both options are given, 634the last specified is used; 635if none are given, 636the default is 637.Fl L . 638.It Ic read Oo Fl r Oc Ar name ... 639Read a line from standard input. 640The line is split into fields, 641with each field assigned to a variable, 642.Ar name , 643in turn 644(first field assigned to first variable, and so on). 645If there are more fields than variables, 646the last variable will contain all the remaining fields. 647If there are more variables than fields, 648the remaining variables are set to empty strings. 649A backslash in the input line causes the shell to prompt for further input. 650.Pp 651The options to the 652.Ic read 653command are as follows: 654.Pp 655.Bl -tag -width Ds -offset 3n -compact 656.It Fl r 657Ignore backslash sequences. 658.El 659.It Ic readonly Oo Fl p Oc Ar name Ns Op = Ns Ar value 660Mark variable 661.Ar name 662as readonly, 663and optionally set it to 664.Ar value . 665Readonly variables cannot be later assigned values or unset. 666.Pp 667The options to the 668.Ic readonly 669command are as follows: 670.Pp 671.Bl -tag -width Ds -offset 3n -compact 672.It Fl p 673Display the names and values of all readonly variables 674in a manner which can be reinput to the shell. 675.El 676.It Ic return Op Ar n 677Exit the current function or 678.Ic .\& 679script with exit status 680.Ar n , 681or that of the last command executed. 682.It Xo 683.Ic set 684.Op Fl abCefhmnuvx 685.Op Fl o Op Ar option 686.Op Ar arg ... 687.Xc 688Set options and positional parameters. 689Without options or arguments, 690display the names and values of all shell variables. 691.Pp 692The options are described in the options description 693at the beginning of this manual. 694The sequence 695.Qq set -o 696displays the current option settings; 697the sequence 698.Qq set +o 699displays, 700in a format suitable to be reinput to the shell, 701a command suitable to achieve the current option settings. 702.Pp 703Any arguments are assigned to the positional parameters, 704with the special parameter 705.Sq # 706set to the number of positional parameters. 707The sequence 708.Qq set -- 709indicates an end to option processing 710(i.e. only arguments follow); 711.Qq set -- 712by itself unsets all positional parameters 713and sets 714.Sq # 715to zero. 716.It Ic shift Op Ar n 717Shift the positional parameters 718.Ar n 719times 720(by default once). 721Parameter 1 takes the value of parameter 722.Sq 1+ Ns Ar n , 723parameter 2 takes 724.Sq 2+ Ns Ar n , 725and so on. 726Parameters 727.Sq # 728to 729.Sq Po #\(mi Ns Ar n Pc Ns +1 730and downwards are unset and 731.Sq # 732is updated to the new number of positional parameters. 733If 734.Ar n 735is 0, 736no change occurs. 737.It Ic times 738Display accumulated process times for the shell (user and system) 739and all child processes (user and system). 740.It Ic true 741Return a true (zero) value. 742.It Ic trap Op Ar action signal ... 743Perform 744.Ar action 745whenever 746.Ar signal 747is caught. 748Without arguments, 749display a list of all traps and actions, 750in a format suitable to be reinput to the shell. 751.Pp 752If 753.Ar action 754is 755.Sq - 756or an integer, 757reset 758.Ar signal 759to its default value; 760if it is empty 761.Pq Qq , 762ignore 763.Ar signal . 764If 765.Ar signal 766is 767.Qq EXIT 768or 0, 769perform 770.Ar action 771when the shell exits; 772otherwise 773.Ar signal 774should be a signal name 775(without the SIG prefix) 776or number. 777.It Ic umask Oo Fl S Oc Op Ar mask 778Set the file mode creation mask to 779.Ar mask . 780The creation mask determines the default permissions 781a newly created file or directory will have. 782If 783.Ar mask 784is not specified, 785display the current creation mask. 786.Pp 787The options to the 788.Ic umask 789command are as follows: 790.Pp 791.Bl -tag -width Ds -offset 3n -compact 792.It Fl S 793Display symbolic output. 794.El 795.Pp 796See 797.Xr chmod 1 798for the format of 799.Ar mask . 800.It Ic unalias Oo Fl a Oc Ar name ... 801Remove the alias definition of alias 802.Ar name . 803.Pp 804The options to the 805.Ic unalias 806command are as follows: 807.Pp 808.Bl -tag -width Ds -offset 3n -compact 809.It Fl a 810Remove all alias definitions. 811.El 812.It Ic unset Oo Fl fv Oc Ar name ... 813Unset variable or function 814.Ar name . 815.Pp 816The options to the 817.Ic unset 818command are as follows: 819.Pp 820.Bl -tag -width Ds -offset 3n -compact 821.It Fl f 822Treat 823.Ar name 824as a function. 825.It Fl v 826Treat 827.Ar name 828as a variable (the default). 829.El 830.It Ic wait Op Ar pid ... 831Wait until all the processes specified by process or job ID 832.Ar pid 833have terminated. 834If no 835.Ar pid 836is specified, 837wait until all processes have terminated. 838The exit status is 0 on success, 8391\(en126 if an error occurs, 840or 127 if 841.Ar pid 842was unknown. 843.El 844.Sh COMMAND HISTORY AND COMMAND LINE EDITING 845When a shell is interactive, 846it keeps a record of commands run in a 847.Em command history , 848either internally in memory or in a file, 849as determined by 850.Dv HISTFILE . 851The command line and all the commands in command history 852can be edited using commands similar to those of 853.Xr vi 1 . 854.Pp 855There are two modes, 856.Em interactive 857and 858.Em command . 859The shell starts in interactive mode. 860In this mode text is entered normally. 861A 862.Aq newline 863executes the current command line. 864The command line, unless empty, is entered into command history. 865The 866.Aq ESC 867key is used to enter command mode, 868where commands similar to those used by 869.Xr vi 1 870are available. 871A Ctrl-L sequence 872.Pq ^L 873can be used in this mode to 874redraw the current command line. 875.Pp 876Where noted, 877some commands may be preceded by a numerical 878.Ar count , 879which causes the command to be repeated that number of times. 880The term 881.Em word 882is used to denote a sequence of letters, digits, or underscores; 883.Em bigword 884denotes a sequence of whitespace delineated characters. 885.Pp 886The commands for command mode: 887.Bl -tag -width "<newline>" 888.It Ic = 889Display the possible shell word expansion. 890.It Ic \e 891Perform pathname expansion on the current word, 892matching the largest possible unique expansion, 893then enter insert mode. 894.It Ic * 895Perform pathname expansion on the current word, 896substituting every possible expansion, 897then enter insert mode. 898.It Ic @ Ns Ar c 899Perform the commands defined by the alias 900.No _ Ns Ar c , 901where 902.Ar c 903is a single letter alphabetical character. 904.It Oo Ar count Oc Ns Ic ~ 905Convert the character from lowercase to upper or vice versa. 906.It Oo Ar count Oc Ns Ic .\& 907Repeat the most recent non-motion command. 908If no 909.Ar count 910is given, use that of the repeated command, 911if any. 912.It Oo Ar n Oc Ns Ic v 913Use 914.Xr vi 1 915to edit command number 916.Ar n 917in command history, 918or the current command if none given. 919.It Xo 920.Oo Ar count Oc Ns Ic l , 921.Oo Ar count Oc Ns Aq space 922.Xc 923Move right. 924.It Oo Ar count Oc Ns Ic h 925Move left. 926.It Oo Ar count Oc Ns Ic w 927Move to the start of the next word. 928.It Oo Ar count Oc Ns Ic W 929Move to the start of the next big word. 930.It Oo Ar count Oc Ns Ic e 931Move to the end of the current word, 932or the end of the next word if the cursor is currently 933at the end of a word. 934.It Oo Ar count Oc Ns Ic E 935Move to the end of the current bigword, 936or the end of the next bigword if the cursor is currently 937at the end of a bigword. 938.It Oo Ar count Oc Ns Ic b 939Move to the start of the current word, 940or the start of the next word if the cursor is currently 941at the start of a word. 942.It Oo Ar count Oc Ns Ic b 943Move to the start of the current bigword, 944or the start of the next bigword if the cursor is currently 945at the start of a bigword. 946.It Ic ^ 947Move to the first non-blank character. 948.It Ic $ 949Move to the end of the current line. 950.It Ic 0 951Move to the beginning of the current line. 952.It Oo Ar count Oc Ns Ic |\& 953Move to the beginning of the current line 954or the character position specified by 955.Ar count . 956.It Oo Ar count Oc Ns Ic f Ns Ar c 957Move to the next instance of the 958character 959.Ar c . 960.It Oo Ar count Oc Ns Ic F Ns Ar c 961Move to the last instance of the 962character 963.Ar c . 964.It Oo Ar count Oc Ns Ic t Ns Ar c 965Move to the character before the next instance of the 966character 967.Ar c . 968.It Oo Ar count Oc Ns Ic T Ns Ar c 969Move to the character after the last instance of the 970character 971.Ar c . 972.It Oo Ar count Oc Ns Ic ;\& 973Repeat the last 974.Ic f , F , t , 975or 976.Ic T 977command. 978Ignore any 979.Ar count 980specified with the last command. 981.It Oo Ar count Oc Ns Ic ,\& 982Repeat the last 983.Ic f , F , t , 984or 985.Ic T 986command, 987but in the opposite direction. 988Ignore any 989.Ar count 990specified with the last command. 991.It Ic a 992Enter insert mode after the current cursor position. 993.It Ic A 994Enter insert mode after the end of the current line. 995.It Ic i 996Enter insert mode at the current cursor position. 997.It Ic I 998Enter insert mode at the beginning of the current line. 999.It Ic R 1000Enter insert mode at the current cursor position, 1001replacing any characters thereafter. 1002.It Oo Ar count Oc Ns Ic c Ns Ar motion 1003Delete the characters between the cursor and the motion command specified, 1004then enter insert mode. 1005A special motion command, 1006.Ic c , 1007may be used to delete the entire line. 1008The 1009.Ar count 1010argument is ignored for the commands 1011.Ic 0 , ^ , $ , 1012and 1013.Ic c . 1014If the motion moves towards the beginning of the line 1015the character under the cursor is not deleted; 1016if it moves towards the end of the line 1017it is deleted. 1018.It Ic C 1019Delete the characters between the cursor and the line end, 1020then enter insert mode. 1021.It Ic S 1022Clear the entire line, 1023then enter insert mode. 1024.It Oo Ar count Oc Ns Ic r 1025Replace the character under the cursor with the next typed character. 1026With a 1027.Ar count , 1028replace the current character 1029and the corresponding number of following characters. 1030.It Oo Ar count Oc Ns Ic _ 1031After the cursor, 1032append a 1033.Aq space 1034and the 1035.Ar count Ns th 1036bigword (by default the last entered) 1037from the previous input line, 1038then enter insert mode. 1039.It Oo Ar count Oc Ns Ic x 1040Delete the character under the cursor, 1041placing it in the save buffer. 1042.It Oo Ar count Oc Ns Ic X 1043Delete the character before the cursor, 1044placing it in the save buffer. 1045.It Oo Ar count Oc Ns Ic d Ns Ar motion 1046Delete the characters between the cursor and the motion command specified, 1047placing them in the save buffer. 1048A special motion command, 1049.Ic d , 1050may be used to delete the entire line. 1051If the motion moves towards the beginning of the line 1052the character under the cursor is not deleted. 1053.It Oo Ar count Oc Ns Ic D 1054Delete the characters between the cursor and the line end, 1055placing them in the save buffer. 1056.It Oo Ar count Oc Ns Ic y Ns Ar motion 1057Yank (copy) the characters between the cursor and the motion command specified, 1058placing them in the save buffer. 1059A special motion command, 1060.Ic y , 1061may be used to yank the entire line. 1062If the motion moves towards the beginning of the line 1063the character under the cursor is not yanked. 1064.It Oo Ar count Oc Ns Ic Y 1065Yank (copy) the characters between the cursor and the line end, 1066placing them in the save buffer. 1067.It Oo Ar count Oc Ns Ic p 1068Paste the contents of the save buffer after the cursor. 1069.It Oo Ar count Oc Ns Ic P 1070Paste the contents of the save buffer before the cursor. 1071.It Oo Ar count Oc Ns Ic u 1072Undo the last change to the edit line. 1073.It Oo Ar count Oc Ns Ic U 1074Undo all changes to the edit line. 1075.It Xo 1076.Oo Ar count Oc Ns Ic k , 1077.Oo Ar count Oc Ns Ic -\& 1078.Xc 1079Replace the current command line with the previous entry in history. 1080.It Xo 1081.Oo Ar count Oc Ns Ic j , 1082.Oo Ar count Oc Ns Ic +\& 1083.Xc 1084Replace the current command line with the next entry in history. 1085.It Oo Ar n Oc Ns Ic G 1086Replace the current command line with command number 1087.Ar n 1088in command history, 1089or the oldest command if none given. 1090.It / Ns Ar pattern 1091Moving backwards through history, 1092replace the current command line with the first that matches 1093.Ar pattern . 1094A 1095.Sq ^ 1096at the beginning of the pattern searches only for entries beginning with 1097.Ar pattern . 1098An empty pattern matches the last search. 1099.It ? Ns Ar pattern 1100As above, 1101but searching forwards. 1102.It Ic n 1103Repeat the most recent pattern search. 1104.It Ic N 1105Repeat the most recent pattern search, 1106but in the opposite direction. 1107.El 1108.Sh SHELL GRAMMAR 1109The shell reads its input as described above. 1110After that it follows a fairly simple chain of operations 1111to parse that input: 1112.Bl -dash 1113.It 1114The shell breaks the input into 1115.Em words 1116and 1117.Em operators . 1118Words are the command text the user wishes run; 1119operators are special characters which describe 1120how the shell should interact with the commands. 1121.It 1122The shell 1123.Em expands 1124the command text according to the rules of expansion. 1125.It 1126Words are subject to 1127.Em field splitting , 1128where the command text is separated into commands 1129and arguments to commands. 1130.It 1131The shell performs any 1132.Em redirection . 1133.It 1134The shell runs the commands. 1135Argument names are assigned to 1136.Em positional parameters , 1137with the command name itself assigned parameter 0. 1138.It 1139If the command is not being run in the background, 1140the shell waits for it to complete 1141and collects its exit status. 1142.El 1143.Ss Quoting 1144Some characters have special meaning to the shell and need 1145.Em quoting 1146if the user wants to indicate to the shell not to interpret them as such. 1147The following characters need quoting if their literal meaning is desired: 1148.Bd -literal -offset indent 1149| & ; < > ( ) $ \` \e " \(aq <space> <tab> <newline> 1150* ? [ # ~ = % 1151.Ed 1152.Pp 1153A backslash 1154.Pq \e 1155can be used to quote any character except a newline. 1156If a newline follows a backslash the shell removes them both, 1157effectively making the following line part of the current one. 1158.Pp 1159A group of characters can be enclosed within single quotes 1160.Pq \(aq 1161to quote every character within the quotes. 1162.Pp 1163A group of characters can be enclosed within double quotes 1164.Pq \&" 1165to quote every character within the quotes 1166except a backquote 1167.Pq \` 1168or a dollar sign 1169.Pq $ , 1170both of which retain their special meaning. 1171A backslash 1172.Pq \e 1173within double quotes retains its special meaning, 1174but only when followed by a backquote, dollar sign, 1175double quote, or another backslash. 1176An at sign 1177.Pq @ 1178within double quotes has a special meaning 1179(see 1180.Sx SPECIAL PARAMETERS , 1181below). 1182.Pp 1183Similarly command words need to be quoted 1184if they are not to be interpreted as such. 1185.Ss Expansion 1186Shell 1187.Em variables 1188are arbitrary names assigned values using the 1189.Sq = 1190operator; 1191the values can be retrieved using the syntax 1192.No $ Ns Ar variable . 1193Shell 1194.Em parameters 1195are variable names, 1196numbers, 1197or any of the characters listed in 1198.Sx SPECIAL PARAMETERS . 1199.Pp 1200The shell is able to 1201.Em expand 1202certain elements of its syntax, 1203allowing for a more concise notation 1204and providing a convenience to the user. 1205.Pp 1206Firstly, tilde expansion occurs on words beginning with the 1207.Sq ~ 1208character. 1209Any characters following the tilde, 1210up to the next colon, slash, or blank, 1211are taken as a login name 1212and substituted with that user's home directory, 1213as defined in 1214.Xr passwd 5 . 1215A tilde by itself is expanded to the contents of the variable 1216.Ev HOME . 1217This notation can be used in variable assignments, 1218in the assignment half, 1219immediately after the equals sign or a colon, 1220up to the next slash or colon, if any. 1221.Pp 1222.Dl PATH=~alice:~bob/jobs 1223.Pp 1224Parameter expansion happens after tildes have been expanded, 1225with the value of the parameter being substituted. 1226The basic format is: 1227.Pp 1228.D1 $ Ns Brq Ar parameter 1229.Pp 1230The braces are optional 1231except for positional parameters 10 and higher, 1232or where the parameter name is followed by other characters 1233that would prevent it from being expanded. 1234If parameter expansion occurs within double quotes, 1235neither pathname expansion nor field splitting happens afterwards. 1236.Pp 1237Some special forms of parameter expansion are available. 1238In the formats below, 1239.Ar word 1240itself is subject to expansion, 1241and, if omitted, 1242the empty string is used. 1243If the colon is omitted, 1244.Ar word 1245is substituted only if 1246.Ar parameter 1247is unset (not if it is empty). 1248.Bl -tag -width Ds 1249.It $ Ns Brq Ar parameter Ns :- Ns Op Ar word 1250Substitute 1251.Ar parameter . 1252If 1253.Ar parameter 1254is unset or empty, 1255substitute 1256.Ar word . 1257.It $ Ns Brq Ar parameter Ns := Ns Op Ar word 1258Substitute 1259.Ar parameter . 1260If 1261.Ar parameter 1262is unset or empty, 1263first assign the value of 1264.Ar word 1265to 1266.Ar parameter . 1267.It $ Ns Brq Ar parameter Ns :? Ns Op Ar word 1268Substitute 1269.Ar parameter . 1270If 1271.Ar parameter 1272is unset or empty, 1273the result of the expansion of 1274.Ar word 1275is written to standard error 1276and the shell exits with a non-zero exit status. 1277If 1278.Ar word 1279is omitted, 1280the string 1281.Qq parameter null or not set 1282is used. 1283.It $ Ns Brq Ar parameter Ns :+ Ns Op Ar word 1284Substitute 1285.Ar word . 1286If 1287.Ar parameter 1288is unset or empty, 1289substitute the empty string. 1290.It $ Ns Brq # Ns Ar parameter 1291The length, in characters, of 1292.Ar parameter . 1293.It $ Ns Brq Ar parameter Ns % Ns Op Ar word 1294Substitute 1295.Ar parameter , 1296deleting the smallest possible suffix matching 1297.Ar word . 1298.It $ Ns Brq Ar parameter Ns %% Ns Op Ar word 1299Substitute 1300.Ar parameter , 1301deleting the largest possible suffix matching 1302.Ar word . 1303.It $ Ns Brq Ar parameter Ns # Ns Op Ar word 1304Substitute 1305.Ar parameter , 1306deleting the smallest possible prefix matching 1307.Ar word . 1308.It $ Ns Brq Ar parameter Ns ## Ns Op Ar word 1309Substitute 1310.Ar parameter , 1311deleting the largest possible prefix matching 1312.Ar word . 1313.El 1314.Pp 1315Command expansion has a command executed in a subshell 1316and the results output in its place. 1317The basic format is: 1318.Pp 1319.D1 $ Ns Pq Ar command 1320or 1321.D1 \` Ns Ar command Ns \` 1322.Pp 1323The results are subject to field splitting and pathname expansion; 1324no other form of expansion happens. 1325If 1326.Ar command 1327is contained within double quotes, 1328field splitting does not happen either. 1329Within backquotes, 1330a backslash is treated literally unless it follows 1331a dollar sign, backquote, or another backslash. 1332Commands can be nested, 1333though the backquoted version requires backslashes before the backquotes. 1334If 1335.Ar command 1336is run in a subshell in the bracketed version, 1337the syntax is identical to that of arithmetic expansion. 1338In that case the shell attempts arithmetic expansion first, 1339then attempts command substitution if that fails. 1340Or a non-ambiguous version can be used: 1341.Pp 1342.D1 "$( (" Ns Ar command Ns ") )" 1343.Pp 1344Arithmetic expansion works similarly, 1345with an arithmetic expression being evaluated and substituted. 1346The format is: 1347.Pp 1348.D1 $ Ns Pq Pq Ar expression 1349.Pp 1350Where 1351.Ar expression 1352is an integer, parameter name, or array reference, 1353optionally combined with any of the operators described below, 1354listed and grouped according to precedence: 1355.Bl -tag -width Ds 1356.It ()\& 1357Operators within brackets have highest precedence. 1358Compare 3+2*4, which is 11, 1359since multiplication has higher precedence than addition, 1360and (3+2)*4, which is 20. 1361.It + - ~ !\& 1362Unary plus 1363(indicates a positive value; integers are positive by default), 1364unary minus (indicates a negative value), 1365bitwise NOT, 1366and logical NOT 1367(the result is 1 if the argument is zero, or 0 otherwise), respectively. 1368.It * / % 1369Multiplication, division, and modulus (remainder), respectively. 1370.It + - 1371Addition and subtraction, respectively. 1372.It << >> 1373Shift left or right, respectively. 1374.It < <= > >= 1375Less than, less than or equal to, 1376greater than, and greater than or equal to, respectively. 1377The result is 1 if true, or 0 otherwise. 1378.It == != 1379Equal (the result is 1 if both arguments are equal, and 0 otherwise) 1380and not equal (the result is 1 if both arguments are non-zero, and 0 otherwise), 1381respectively. 1382.It & 1383Bitwise AND. 1384.It ^ 1385Bitwise exclusive OR. 1386.It | 1387Bitwise inclusive OR. 1388.It && 1389Logical AND. 1390The result is 1 if both arguments are non-zero, or 0 otherwise. 1391.It || 1392Logical OR. 1393The result is 1 if either argument is non-zero, or 0 otherwise. 1394.It Ar expression ? Ns Ar expr1 : Ns Ar expr2 1395The result is 1396.Ar expr1 1397if 1398.Ar expression 1399is non-zero, 1400or 1401.Ar expr2 1402otherwise. 1403.It = *= /= %= += -= <<= >>= &= ^= |= 1404Assignment. 1405The notation 1406.Ar var Ns *= Ns Ar expression 1407is equivalent to 1408.Ar var Ns = Ns Ar var Ns * Ns Ar expression . 1409.El 1410.Pp 1411After the various types of expansion listed above have been carried out, 1412the shell subjects everything that did not occur in double quotes to 1413.Em field splitting , 1414where words are broken up according to the value of the 1415.Ev IFS 1416variable. 1417Each character of 1418.Ev IFS 1419is used to split fields; 1420any 1421.Ev IFS 1422characters at the beginning and end of input are ignored. 1423If 1424.Ev IFS 1425is unset, the default value consisting of 1426.Aq space , 1427.Aq tab 1428and 1429.Aq newline 1430is used; if the value of 1431.Ev IFS 1432is empty, no field splitting is performed. 1433.Pp 1434After field splitting, 1435the shell matches filename patterns. 1436.Bl -tag -width Ds 1437.It ? 1438A question mark matches any single character. 1439.It * 1440An asterisk matches multiple characters. 1441.It [..] 1442Matches any character enclosed in the brackets. 1443The sense is negated if the first character is 1444.Sq !\& . 1445A closing bracket can be included in the list of characters to match 1446by listing it as the first character after the opening bracket 1447or by quoting it. 1448Similarly a 1449.Sq - 1450should be specified last or quoted so that the shell does not think 1451it is a character range (see below). 1452.It [[: Ns Ar class Ns :]] 1453Matches any character in the following character classes: 1454.Bd -literal -offset indent 1455alnum alpha blank cntrl 1456digit graph lower print 1457punct space upper xdigit 1458.Ed 1459.It Bq Ar x Ns - Ns Ar y 1460Matches any character in the range between 1461.Ar x 1462and 1463.Ar y , 1464inclusive. 1465.El 1466.Pp 1467Slashes and full stops do not match the patterns above 1468because of their use as path and filename characters. 1469.Ss Redirection 1470Redirection is used to open, close, or otherwise manipulate files, 1471using redirection operators in combination with numerical 1472.Em file descriptors . 1473A minimum of ten (0\-9) descriptors are supported; 1474by convention 1475standard input is file descriptor 0, 1476standard output file descriptor 1, 1477and standard error file descriptor 2. 1478In the examples given below, 1479.Ar n 1480represents a numerical file descriptor. 1481The target for redirection is 1482.Ar file 1483and it is subject to all forms of expansion as listed above, 1484except pathname expansion. 1485If any part of the file descriptor or redirection operator is quoted, 1486they are not recognised. 1487.Bl -tag -width Ds 1488.It Oo Ar n Oc Ns < Ns Ar file 1489Open 1490.Ar file 1491for reading on file descriptor 1492.Ar n , 1493by default standard input. 1494.It Oo Ar n Oc Ns > Ns Ar file 1495Write to 1496.Ar file 1497with file descriptor 1498.Ar n , 1499by default standard output. 1500If 1501.Ar file 1502does not exist, 1503create it; 1504if it does exist, 1505truncate it to be empty before beginning to write to it. 1506.It Oo Ar n Oc Ns >| Ns Ar file 1507As above, but forces clobbering 1508(see the 1509.Fl C 1510option). 1511.It Oo Ar n Oc Ns >> Ns Ar file 1512Append to 1513.Ar file 1514with file descriptor 1515.Ar n , 1516by default standard output. 1517If 1518.Ar file 1519does not exist, 1520create it. 1521.It Oo Ar n Oc Ns << 1522This form of redirection, 1523called a 1524.Em here document , 1525is used to copy a block of lines 1526to a temporary file until a line matching 1527.Ar delimiter 1528is read. 1529When the command is executed, standard input is redirected from the 1530temporary file to file descriptor 1531.Ar n , 1532or standard input by default. 1533The basic format is: 1534.Bd -unfilled -offset indent 1535.Oo Ar n Oc Ns << Ns Ar delimiter 1536text 1537text 1538\&... 1539.Ar delimiter 1540.Ed 1541.Pp 1542Provided 1543.Ar delimiter 1544doesn't contain any quoted characters, 1545parameter, command, and arithmetic expansions are performed on 1546the text block, 1547and backslashes escape the special meaning of 1548.Sq $ , 1549.Sq \` , 1550and 1551.Sq \e . 1552If multiple here documents are used on the same command line, 1553they are saved and processed in order. 1554.It Oo Ar n Oc Ns <<- 1555Same as 1556.Ic << , 1557except leading tabs are stripped from lines in 1558.Ar block . 1559.It Oo Ar n Oc Ns <& Ns Ar file 1560Make file descriptor 1561.Ar n , 1562by default standard input, 1563a copy of the file descriptor denoted by 1564.Ar file . 1565If 1566.Ar file 1567is 1568.Sq - , 1569close file descriptor 1570.Ar n 1571or standard input. 1572.It Oo Ar n Oc Ns >& Ns Ar file 1573Make file descriptor 1574.Ar n , 1575by default standard output, 1576a copy of the file descriptor denoted by 1577.Ar file . 1578If 1579.Ar file 1580is 1581.Sq - , 1582close file descriptor 1583.Ar n 1584or standard output. 1585.It Oo Ar n Oc Ns <> Ns Ar file 1586Open 1587.Ar file 1588for reading and writing on file descriptor 1589.Ar n , 1590by default standard input. 1591If 1592.Ar file 1593does not exist, 1594create it. 1595.El 1596.Sh COMMANDS 1597The shell first expands 1598any words that are not variable assignments or redirections, 1599with the first field being the command name 1600and any successive fields arguments to that command. 1601It sets up redirections, if any, 1602and then expands variable assignments, if any. 1603It then attempts to run the command. 1604.Pp 1605Firstly, it determines whether the command name contains any slashes. 1606If it does not, and the shell implements the command as a special built-in, 1607it then invokes the built-in. 1608If not, but it is a non POSIX standard command, 1609implemented as a shell function, 1610it then invokes that. 1611If not, but it is one of the commands 1612.Ic alias , bg , cd , command , 1613.Ic false , fc , fg , getopts , 1614.Ic jobs , kill , newgrp , pwd , 1615.Ic read , true , umask , unalias , 1616or 1617.Ic wait , 1618it then invokes that. 1619.Pp 1620Failing that, the value of 1621.Ev PATH 1622is used to search for the command. 1623If it finds a match, 1624and it is a POSIX standard command, 1625implemented as a built-in or function, 1626it then invokes it. 1627Otherwise 1628it attempts to execute the command in an environment separate from the shell. 1629If it is unable to execute the command, 1630it tries to run it as a shell script. 1631.Pp 1632Finally, if the command name does contain a slash, 1633and it finds a match in 1634.Ev PATH , 1635it attempts to execute the command in an environment separate from the shell. 1636If it is unable to execute the command, 1637it tries to run it as a shell script. 1638.Pp 1639A series of one or more commands separated by 1640.Sq ;\& 1641constitute a 1642.Em sequential list , 1643where commands are executed in the order given. 1644The exit status of a sequential list is that of the last command executed. 1645The format for a sequential list is: 1646.Pp 1647.D1 Ar command\ \& ; Op Ar command ... 1648.Pp 1649A series of one or more commands separated by 1650.Sq & 1651constitute an 1652.Em asynchronous list , 1653where the shell executes the command in a subshell 1654and runs the next command without waiting for the previous one to finish. 1655The exit status of an asynchronous list is always zero. 1656The format for an asynchronous list is: 1657.Pp 1658.D1 Ar command No & Op Ar command ... 1659.Pp 1660A series of commands separated by 1661.Sq | 1662constitute a 1663.Em pipeline , 1664where the output of one command 1665is used as input for the next command. 1666The exit status of a pipeline is that of the last command; 1667if a pipeline begins 1668.Sq !\& 1669the exit status is inverted. 1670The format for a pipeline is: 1671.Pp 1672.D1 Oo !\& Oc Ar command | command Op | Ar ... 1673.Pp 1674A series of commands separated by 1675.Sq && 1676constitute an 1677.Em AND list , 1678where a command is only executed if the exit status of the previous command was 1679zero. 1680The exit status of an AND list is that of the last command. 1681The format for an AND list is: 1682.Pp 1683.D1 Ar command No && Ar command Op && Ar ... 1684.Pp 1685A series of commands separated by 1686.Sq || 1687constitute an 1688.Em OR list , 1689where a command is only executed if the exit status of the previous command was 1690non-zero. 1691The exit status of an OR list is that of the last command. 1692The format for an OR list is: 1693.Pp 1694.D1 Ar command No || Ar command Op || Ar ... 1695.Pp 1696A series of commands separated by 1697.Sq && 1698and 1699.Sq || 1700constitute an 1701.Em AND-OR list , 1702where 1703.Sq && 1704and 1705.Sq || 1706have equal precedence and are evaluated in the order they are given. 1707The AND-OR list can be terminated with 1708.Sq ;\& 1709or 1710.Sq & 1711to have them execute sequentially or asynchronously, respectively. 1712.Pp 1713Command lists, 1714as described above, 1715can be enclosed within 1716.Sq () 1717to have them executed in a subshell, 1718or within 1719.Sq {} 1720to have them executed in the current environment: 1721.Pp 1722.D1 Pq Ar command ... 1723.D1 Brq Ar \ \&command ... Ns ;\& 1724.Pp 1725Any redirections specified after the closing bracket apply to all commands 1726within the brackets. 1727An operator such as 1728.Sq ;\& 1729or a newline are needed to terminate a command list within curly braces. 1730.Pp 1731The shell has grammatical constructs 1732which allow it to work its way (loop) through lists 1733or evaluate things conditionally. 1734.Pp 1735A 1736.Em for loop 1737executes a series of commands for each item in a list. 1738Its format is: 1739.Bd -unfilled -offset indent 1740.No for Ar name Op in Ar word ... 1741do 1742.No " " Ar command 1743.No " " Ar ... 1744done 1745.Ed 1746.Pp 1747Firstly 1748.Ar word ... 1749is expanded to generate a list of items. 1750The variable 1751.Ar name 1752is set to each item, in turn, 1753and the commands are executed for each item. 1754The construct 1755.Qq in word ... 1756can be omitted, 1757which is equivalent to: in \&"$@\&". 1758The exit status is zero if there are no items 1759or otherwise the exit status of the last command executed. 1760.Pp 1761A 1762.Em while loop 1763continuously executes a set of commands 1764as long as the command or command list being tested in 1765.Ar condition 1766has a zero exit status. 1767Its format is: 1768.Bd -unfilled -offset indent 1769.No while Ar condition 1770do 1771.No " " Ar command 1772.No " " Ar ... 1773done 1774.Ed 1775.Pp 1776Multiple commands may be given by grouping them in lists, 1777as described above, 1778or by separating them with newlines. 1779The exit status is zero if the commands after 1780.Qq do 1781were never executed 1782or otherwise the exit status of the last command executed. 1783.Pp 1784An 1785.Em until loop 1786continuously executes a set of commands 1787as long as the command or command list being tested in 1788.Ar condition 1789has a non-zero exit status. 1790Its format is: 1791.Bd -unfilled -offset indent 1792.No until Ar condition 1793do 1794.No " " Ar command 1795.No " " Ar ... 1796done 1797.Ed 1798.Pp 1799Multiple commands may be given by grouping them in lists, 1800as described above, 1801or by separating them with newlines. 1802The exit status is zero if the commands after 1803.Qq do 1804were never executed 1805or otherwise the exit status is that of the last command executed. 1806.Pp 1807A 1808.Em case conditional 1809is used to run commands whenever a pattern is matched. 1810Its format is: 1811.Bd -unfilled -offset indent 1812.No case Ar word No in 1813.No " " Po Ar pattern Oo | Ar pattern ... Oc Pc Ar command Ns ;; 1814.No " " Ar ... 1815esac 1816.Ed 1817.Pp 1818In this case 1819.Ar pattern 1820is matched against the string resulting from the expansion of 1821.Ar word . 1822Multiple commands may be given by grouping them in lists, 1823as described above, 1824or by separating them with newlines. 1825The initial 1826.Sq (\& 1827is optional, 1828as is the terminating 1829.Sq ;; 1830for the final command. 1831The exit status is zero if no patterns are matched 1832or otherwise the exit status of the last command executed. 1833.Pp 1834An 1835.Em if conditional 1836is used to execute commands depending on the exit status of the command or 1837command list being tested. 1838Its format is: 1839.Bd -unfilled -offset indent 1840.No if Ar conditional 1841then 1842.No " " Ar command 1843.No " " Ar ... 1844.No elif Ar conditional 1845then 1846.No " " Ar command 1847.No " " Ar ... 1848.No else 1849.No " " Ar command 1850.No " " Ar ... 1851fi 1852.Ed 1853.Pp 1854Firstly the command(s) following 1855.Qq if 1856is executed; 1857if its exit status is zero, 1858the commands in the 1859.Qq then 1860block are executed and the conditional completes. 1861Otherwise the commands in the 1862.Qq elif 1863block are executed; 1864if the exit status is zero, 1865the commands in the 1866.Qq then 1867block are executed and the conditional completes. 1868Otherwise the next 1869.Qq elif 1870block, if any, is tried. 1871If nothing from an 1872.Qq if 1873or 1874.Qq elif 1875block returns zero, 1876the commands in the 1877.Qq else 1878block are run and the conditional completes. 1879The 1880.Qq elif 1881and 1882.Qq else 1883blocks are optional. 1884.Pp 1885Multiple commands may be given by grouping them in lists, 1886as described above, 1887or by separating them with newlines. 1888The exit status is zero if nothing is executed from an 1889.Qq if 1890or 1891.Qq elif 1892block 1893or otherwise the exit status of the last command executed. 1894.Pp 1895Functions allow the user to define a group of commands, 1896executed whenever the function is invoked. 1897Its format is: 1898.Bd -unfilled -offset indent 1899.Ar function Ns () Ar command-list 1900.Ed 1901.Pp 1902The above simply defines a function; 1903nothing is executed until the function is invoked. 1904Commands may specify redirections 1905and positional parameters are changed, 1906for the duration of the function, 1907to those passed to it. 1908The special parameter 1909.Sq # 1910is temporarily changed too, 1911though 1912.Sq 0 1913is not. 1914After the function finishes, 1915the positional parameters and 1916.Sq # 1917are restored to their original values. 1918The exit status of a function definition is 0 if successful 1919or >0 otherwise. 1920The exit status of a function is that of the last command 1921executed by the function. 1922.Sh SPECIAL PARAMETERS 1923Some parameters have special meaning to the shell 1924and are listed below. 1925.Bl -tag -width Ds 1926.It 0 1927The name of the shell or shell script. 1928.It 1 ... n 1929The 1930.Em positional parameters . 1931These parameters are set when a shell, shell script, 1932or shell function is invoked. 1933Each argument passed to a shell or shell script 1934is assigned a positional parameter, 1935starting at 1, 1936and assigned sequentially. 1937When a shell function is invoked, 1938any arguments passed to it are temporarily reassigned to the 1939positional parameters; 1940when the function completes, 1941the values are restored. 1942Positional parameters 10 and above should be enclosed in {}. 1943Positional parameters can be reassigned using the 1944.Ic set 1945command. 1946.It @ 1947All positional parameters. 1948Within double quotes, 1949each parameter is output as a separate field. 1950The resulting list completely matches what was passed to the shell. 1951So "1 2" "3" is output as two parameters, "1 2" and "3". 1952.It * 1953All positional parameters. 1954Within double quotes, 1955all parameters are output as one field, 1956separated by the first character of 1957.Ev IFS 1958(by default a space). 1959The resulting list of words is amalgamated, 1960losing the sense of how they were passed to the shell. 1961So "1 2" "3" is output as one parameter, "1 2 3". 1962.It # 1963The number of positional parameters. 1964.It ? 1965The exit status of the most recent command. 1966.It - 1967The current shell options. 1968.It $ 1969The process ID of the current shell. 1970Subshells have the same PID as the current shell. 1971.It ! 1972The process ID of the most recent background command. 1973.El 1974.Sh ENVIRONMENT 1975The following environment variables affect the execution of 1976.Nm : 1977.Bl -tag -width "POSIXLY_CORRECT" 1978.It Ev CDPATH 1979Colon separated list of directories used by the 1980.Ic cd 1981command. 1982.It Ev ENV 1983Pathname to a file containing commands to be executed 1984when an interactive shell is started. 1985.It Ev FCEDIT 1986Editor for the 1987.Ic fc 1988builtin. 1989The default is 1990.Xr ed 1 . 1991.It Ev HISTFILE 1992Pathname to a file to be used to record command history. 1993The default is to not write command history to a file. 1994.It Ev HISTSIZE 1995The maximum number of commands stored in history. 1996The default is 500. 1997.It Ev HOME 1998Pathname to a user's home directory. 1999.It Ev IFS 2000A list of characters to be used for field splitting. 2001.It Ev LINENO 2002The current line number in a script or function, 2003starting at 1. 2004This variable should not be set by users. 2005.It Ev MAIL 2006Pathname to a user's mailbox file. 2007If set, 2008.Nm 2009reports the arrival of new mail 2010(ascertained by checking a file's modification time) 2011every 2012.Ev MAILCHECK 2013seconds. 2014.Ev MAIL 2015is overridden by 2016.Ev MAILPATH . 2017.It Ev MAILCHECK 2018How often, 2019in seconds, 2020to check for new mail in either 2021.Ev MAIL 2022or 2023.Ev MAILPATH . 2024The default is 600 (10 minutes). 2025If set to 0, 2026check before issuing each prompt. 2027.It Ev MAILPATH 2028Pathname to a colon separated list of mailboxes. 2029If set, 2030.Nm 2031reports the arrival of new mail 2032(ascertained by checking a file's modification time) 2033every 2034.Ev MAILCHECK 2035seconds. 2036The default notification message 2037.Pq Qq you have mail in $_ 2038can be changed per mailbox by appending 2039.No % Ns Ar message 2040to a pathname. 2041.Ev MAILPATH 2042overrides 2043.Ev MAIL . 2044.It Ev OLDPWD 2045Pathname to the previous working directory. 2046.It Ev OPTARG 2047An option argument for the 2048.Ic getopts 2049command. 2050.It Ev OPTIND 2051An index to the next option for the 2052.Ic getopts 2053command. 2054.It Ev PATH 2055Pathname to a colon separated list of directories 2056used to search for the location of executable files. 2057A pathname of 2058.Sq .\& 2059represents the current working directory. 2060The default value of 2061.Ev PATH 2062on 2063.Ox 2064is: 2065.Bd -literal -offset 2n 2066/usr/bin:/bin:/usr/sbin:/sbin:/usr/X11R6/bin:/usr/local/bin 2067.Ed 2068.It Ev POSIXLY_CORRECT 2069Enable POSIX mode 2070(see 2071.Sx STANDARDS ) . 2072.It Ev PPID 2073The shell's parent process ID. 2074Subshells have the same 2075.Ev PPID 2076as the parent of the current shell. 2077.It Ev PS1 2078User prompt displayed every time an interactive shell 2079is ready to read a command. 2080A 2081.Sq !\& 2082in the prompt is expanded to the number of the next command in history 2083to be typed. 2084The default value is 2085.Sq $\ \& 2086for normal users and 2087.Sq #\ \& 2088for root. 2089.It Ev PS2 2090Newline prompt displayed in an interactive shell 2091when a newline has been entered 2092before the command line completes. 2093The default value is 2094.Sq >\ \& . 2095.It Ev PS4 2096Trace prompt displayed in an interactive shell 2097before each command is traced 2098(see the 2099.Fl x 2100option). 2101The default is 2102.Sq +\ \& . 2103.It PWD 2104The absolute pathname to the current working directory. 2105Assignments to this variable are ignored. 2106.El 2107.Sh ASYNCHRONOUS EVENTS 2108The following signals affect the execution of 2109.Nm : 2110.Bl -tag -width "SIGQUITXXX" 2111.It Dv SIGINT 2112If a shell is interactive 2113and in command line editing mode, 2114editing is terminated on the current line 2115and the command being edited is not entered into command history. 2116Otherwise the signal is caught 2117but no action is taken. 2118.It Dv SIGQUIT 2119Ignored if a shell is interactive. 2120.It Dv SIGTERM 2121Ignored if a shell is interactive. 2122.It Dv SIGTSTP 2123Ignored if a shell is interactive 2124and the 2125.Ic monitor 2126option 2127.Pq Fl m 2128is set. 2129.It Dv SIGTTIN 2130Ignored if a shell is interactive 2131and the 2132.Ic monitor 2133option 2134.Pq Fl m 2135is set. 2136.It Dv SIGTTOU 2137Ignored if a shell is interactive 2138and the 2139.Ic monitor 2140option 2141.Pq Fl m 2142is set. 2143.El 2144.Sh EXIT STATUS 2145The 2146.Nm 2147utility exits with one of: 2148.Bl -tag -width "1-125" 2149.It 0 2150The script being executed contained only blank lines or comments. 2151.It 1\(en125 2152A non-interactive shell detected an error other than 2153.Ar file 2154not found. 2155.It 126 2156A command was found but was not executable. 2157.It 127 2158A non-interactive shell returned 2159.Ar file 2160not found. 2161.El 2162.Pp 2163Otherwise 2164.Nm 2165returns the exit status of the last command it invoked. 2166.Sh SEE ALSO 2167.Xr csh 1 , 2168.Xr ed 1 , 2169.Xr ksh 1 , 2170.Xr vi 1 , 2171.Xr script 7 2172.Sh STANDARDS 2173The 2174.Nm 2175utility is compliant with the 2176.St -p1003.1-2008 2177specification, 2178except where noted below: 2179.Bl -dash 2180.It 2181The flag 2182.Op Fl h 2183is documented by POSIX as hashing 2184.Qq utilities invoked by functions as those functions are defined ; 2185this implementation hashes utilities after first invocation 2186(and functions be damned). 2187.It 2188POSIX says mail notifications via 2189.Ev MAIL 2190and 2191.Ev MAILPATH 2192should happen if a file is created, 2193as well as if its modification time changes. 2194This implementation of 2195.Nm 2196does not provide notification when these files are created. 2197.It 2198Command substitution occurring within double quotes 2199is subject to pathname expansion but should not be. 2200.It 2201The built-in 2202.Ic newgrp 2203is unsupported. 2204.It 2205The 2206.Ic break 2207and 2208.Ic continue 2209built-ins should exit/return from the outermost loop if the argument 2210.Ar n 2211is greater than the level of loops. 2212.El 2213.Pp 2214Enabling POSIX mode changes some behaviour to make 2215.Nm 2216adhere more strictly to the 2217.St -p1003.1-2008 2218specification. 2219