1.\" $NetBSD: sh.1,v 1.270 2024/11/11 22:57:42 kre Exp $ 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. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)sh.1 8.6 (Berkeley) 5/4/95 33.\" 34.Dd November 11, 2024 35.Dt SH 1 36.\" everything except c o and s (keep them ordered) 37.ds flags abCEeFfhIiLlmnpqruVvXx 38.Os 39.Sh NAME 40.Nm sh 41.Nd command interpreter (shell) 42.Sh SYNOPSIS 43.Nm 44.Bk -words 45.Op Fl \*[flags] 46.Op Cm +\*[flags] 47.Ek 48.Bk -words 49.Op Fl o Ar option_name 50.Op Cm +o Ar option_name 51.Ek 52.Bk -words 53.Op Ar command_file Op Ar argument ... 54.Ek 55.Nm 56.Fl c 57.Bk -words 58.Op Fl s 59.Op Fl \*[flags] 60.Op Cm +\*[flags] 61.Ek 62.Bk -words 63.Op Fl o Ar option_name 64.Op Cm +o Ar option_name 65.Ek 66.Bk -words 67.Ar command_string 68.Op Ar command_name Op Ar argument ... 69.Ek 70.Nm 71.Fl s 72.Bk -words 73.Op Fl \*[flags] 74.Op Cm +\*[flags] 75.Ek 76.Bk -words 77.Op Fl o Ar option_name 78.Op Cm +o Ar option_name 79.Ek 80.Bk -words 81.Op Ar argument ... 82.Ek 83.Sh DESCRIPTION 84.Nm 85is the standard command interpreter for the system. 86It is a re-implementation and extension of the Bourne shell. 87This version has many 88features which make it appear similar in some respects to the Korn shell, 89but it is not a Korn shell clone (see 90.Xr ksh 1 ) . 91This man page is not intended 92to be a tutorial or a complete specification of the shell. 93.Ss Overview 94The shell is a command that reads lines from either a file or the 95terminal, interprets them, and generally executes other commands. 96A shell is the program that is running when a user logs into the system. 97(Users can select which shell is executed for them at login with the 98.Xr chsh 1 99command). 100The shell implements a language that has flow control 101constructs, a macro facility that provides a variety of features in 102addition to data storage, along with built in history and line editing 103capabilities. 104It incorporates many features to aid interactive use and 105has the advantage that the interpretative language is common to both 106interactive and non-interactive use (shell scripts). 107That is, commands 108can be typed directly to the running shell or can be put into a file and 109the file can be executed directly by the shell. 110.Ss Invocation 111If the 112.Fl r 113option is present on the command line, 114alone, or following other (valid) options, 115the 116.Nm 117immediately prints its version information to standard output 118and exits. 119This allows invocations like 120.Dl Nm Fl version 121as the (preceding) 122.Fl v 123and 124.Fl e 125are valid options, then when the 126.Fl r 127is encountered, the version information is printed, and 128no more processing is attempted. 129Whether the remaining (apparent) options after the 130.Fl r 131would have been valid or not is immaterial. 132.Pp 133If no arguments are present and if the standard input, 134and standard error output, of the shell 135are connected to a terminal (or terminals, or if the 136.Fl i 137flag is set), 138and the 139.Fl c 140option is not present, the shell is considered an interactive shell. 141An interactive shell generally prompts before each command and handles 142programming and command errors differently (as described below). 143When first starting, 144if neither the 145.Fl l 146nor 147.Cm \&+l 148options were given on the command line, 149the shell inspects argument 0, and if it begins with a dash 150.Sq \- , 151or if the 152.Fl l 153option was given, 154the shell is also considered 155a login shell. 156Beginning argument 0 with a dash is normally done 157automatically by the system 158when the user first logs in. 159A login shell first reads commands 160(as if by using the 161.Ql \&. 162command) 163from the files 164.Pa /etc/profile 165and 166.Pa .profile 167in the user's home directory 168.Pq Li \&$HOME , 169if they exist. 170If the environment variable 171.Ev ENV 172is set on entry to a shell, 173or is set in the 174.Pa .profile 175of a login shell, 176and either the shell is interactive, or the 177.Cm posix 178option is not set, 179the shell then performs parameter and arithmetic 180expansion on the value of 181.Ev ENV , 182(these are described later) 183and if no errors occurred, 184then reads commands from the file name that results. 185Note that no error messages result from these 186expansions, to verify that 187.Ev ENV 188is correct, as desired, use: 189.Dl eval printf '%s\e\en' \*q${ENV}\*q 190Otherwise if 191.Ev ENV 192appears to contain a command substitution, 193which is never performed here, 194or if there were no expansions to expand, the value of 195.Ev ENV 196is used as the file name. 197.Pp 198Therefore, a user should place commands that are to be executed only at 199login time in the 200.Pa .profile 201file, and commands that are executed for every shell inside the 202.Ev ENV 203file. 204To set the 205.Ev ENV 206variable to some file, place the following line in your 207.Pa .profile 208of your home directory 209.Pp 210.Dl ENV=$HOME/.shinit; export ENV 211.Pp 212substituting for 213.Pa .shinit 214any filename you wish. 215Since the 216.Ev ENV 217file can be read for every invocation of the shell, including shell scripts 218and non-interactive shells, the following paradigm is useful for 219restricting commands in the 220.Ev ENV 221file to interactive invocations. 222Place commands within the 223.Dq Ic case 224and 225.Dq Ic esac 226below (these commands are described later): 227.Bd -literal -offset indent 228case $- in *i*) 229 # commands for interactive use only 230 ... 231esac 232.Ed 233.Pp 234If command line arguments besides the options have been specified, and 235neither 236.Fl c 237nor 238.Fl s 239was given, then the shell treats the first argument 240as the name of a file from which to read commands (a shell script). 241This also becomes 242.Li $0 243and the remaining arguments are set as the 244positional parameters of the shell 245.Li ( $1 , $2 , 246etc). 247Otherwise, if 248.Fl c 249was given, then the first argument, which must exist, 250is taken to be a string of 251.Nm 252commands to execute. 253Then if any additional arguments follow the command string, 254those arguments become 255.Li $0 , $1 , 256\&... 257Otherwise, if additional arguments were given 258(which implies that 259.Fl s 260was set) 261those arguments become 262.Li $1 , $2 , 263\&... 264If 265.Li $0 266has not been set by the preceding processing, it 267will be set to 268.Va argv\^ Ns [ 0 ] 269as passed to the shell, which will 270usually be the name of the shell itself. 271If 272.Fl s 273was given, or if neither 274.Fl c 275nor any additional (non-option) arguments were present, 276the shell reads commands from its standard input. 277.\" 278.\" 279.Ss Argument List Processing 280.\" 281Currently, all of the single letter options that can meaningfully 282be set using the 283.Ic set 284built-in, have a corresponding name 285that can be used as an argument to the 286.Fl o 287option. 288The 289.Ic set Fl o 290name is provided next to the single letter option in 291the description below. 292Some options have only a long name, and are used with 293.Fl o 294or 295.Cm +o 296only, either on the command line, or with the 297.Ic set 298built-in command. 299Those are listed in the table below after the options 300with a one letter, flag, equivalent. 301.Pp 302Other options described are for the command line only. 303Specifying using a dash (or minus) 304.Dq Cm \- 305turns the option on, while using a plus 306.Dq Cm + 307disables the option. 308This may seem counter-intuitive, but is in line with the 309common practice where 310.Ic cmd Fl x 311runs 312.Ic cmd 313with the 314.Sq x 315option set. 316.Pp 317The following options can be set from the command line and, 318unless otherwise stated, with the 319.Ic set 320built-in (described later). 321.\" 322.\" strlen("quietprofile") == strlen("local_lineno"): pick the latter 323.\" to give the indent as the _ in local_lineno, and the fi ligature in 324.\" quietprofile combine to make "local_lineno' slightly wider when printed 325.\" (in italics) in a variable width font. 326.Bl -tag -width ".Fl L Em local_lineno" -offset indent 327.\" 328.It Fl a Em allexport 329Automatically export any variable to which a value is assigned 330while this flag is set, unless the variable has been marked as 331not for export. 332.It Fl b Em notify 333Enable asynchronous notification of background job completion. 334(Not implemented.) 335.It Fl C Em noclobber 336Don't overwrite existing files with 337.Dq > . 338.It Fl c 339Read commands from the 340.Ar command_string 341operand instead of, or in addition to, from the standard input. 342Special parameter 343.Dv 0 \" $0 (comments like this for searching sources only) 344will be set from the 345.Ar command_name 346operand if given, and the positional parameters 347.Dv ( 1 , 2 , 348etc.) 349set from the remaining argument operands, if any. 350.Fl c 351is only available at invocation, it cannot be 352.Ic set , 353and there is no form using 354.Dq Cm \&+ . 355.It Fl E Em emacs 356Enable the built-in emacs style 357command line editor (disables 358.Fl V 359if it had been set). 360(See the 361.Sx Command Line Editing 362section below.) 363.It Fl e Em errexit 364If not interactive, exit immediately if any untested command fails. 365If interactive, and an untested command fails, 366cease all processing of the current command and return to 367prompt for a new command. 368The exit status of a command is considered to be 369explicitly tested if the command is used to control an 370.Ic if , 371.Ic elif , 372.Ic while , 373or 374.Ic until , 375or if the command is the left hand operand of an 376.Dq && 377or 378.Dq || 379operator, 380or if it is a pipeline (or simple command) preceded by the 381.Dq \&! 382operator. 383With pipelines, only the status of the entire pipeline 384(usually generated by the last command it contains) 385is tested when 386.Fl e 387is set to determine if the shell should exit. 388.It Fl F Em fork 389Cause the shell to always use 390.Xr fork 2 391instead of attempting 392.Xr vfork 2 393when it needs to create a new process. 394This should normally have no visible effect, 395but can slow execution. 396The 397.Nm 398can be compiled to always use 399.Xr fork 2 400in which case altering the 401.Fl F 402flag has no effect. 403.It Fl f Em noglob 404Disable pathname expansion. 405.It Fl h Em trackall 406Functions defined while this option is set will have paths bound to 407commands to be executed by the function at the time of the definition. 408When off when a function is defined, 409the file system is searched for commands each time the function is invoked. 410(Obsolete and not implemented.) 411.It Fl I Em ignoreeof 412Ignore EOFs from input when interactive. 413(After a large number of consecutive EOFs the shell will exit anyway.) 414.It Fl i Em interactive 415Force the shell to behave interactively. 416If not set on the command line, 417this option is set automatically at shell startup if 418the shell is reading from standard input (no 419.Fl c , 420or 421.Ar command_file 422given at invocation of 423.Nm ) , 424and standard input and standard error refer to 425terminal type devices. 426.It Fl L Em local_lineno 427When set, before a function is defined, 428causes the variable 429.Dv LINENO 430when used within the function, 431to refer to the line number defined such that 432first line of the function is line 1. 433When reset, 434.Dv LINENO 435in a function refers to the line number within the file 436within which the definition of the function occurs. 437This option defaults to 438.Dq on 439in this shell. 440For more details see the section 441.Sx Using Dv LINENO 442below. 443.It Fl l Em login 444When set on the command line, the shell will be considered 445a login shell. 446When reset on the command line 447.Po Cm \&+l 448or 449.Cm \&+o Em login Pc , 450the shell will not be 451considered a login shell, even if the command name parameter 452.Po Va argv[0] Pc 453begins with a dash 454.Pq Sq \- . 455See 456.Sx Invocation 457for the effects of this. 458Changing the value of this option while the shell is 459running has no effect. 460.It Fl m Em monitor 461Turn on job control (set automatically at shell startup, 462if not mentioned on the command line, when interactive). 463.It Fl n Em noexec 464Read and parse commands, but do not execute them. 465This is useful for checking the syntax of shell scripts. 466If 467.Fl n 468becomes set in an interactive shell, it will automatically be 469cleared just before the next time the command line prompt 470.Pq Ev PS1 471is written. 472.It Fl p Em nopriv 473Do not attempt to reset effective UID if it does not match UID. 474The same applies to effective and real GIDs. 475This is not set by default to help avoid incorrect usage by setuid 476root programs via 477.Xr system 3 478or 479.Xr popen 3 . 480This option is effective only when set on the command line, 481but can be reset to drop privileges, once, at any time. 482If 483.Fl p 484is cleared, those privileges can never be regained, 485however much the 486.Fl p 487option is manipulated. 488.It Fl q Em quietprofile 489If the 490.Fl v 491or 492.Fl x 493options have been set, 494temporarily disable them before reading initialization files, 495these being 496.Pa /etc/profile , 497.Pa .profile , 498and the file specified by the 499.Ev ENV 500environment variable. 501.It Fl r 502Print 503.Nm 504version information and exit. 505It is immaterial whether the option follows 506.Fl 507or 508.Cm + . 509See 510.Sx Invocation 511above. 512This option is valid only on the command line. 513.It Fl s Em stdin 514Read commands from standard input (set automatically if 515neither 516.Fl c 517nor file arguments are present). 518If after processing a command_string with the 519.Fl c 520option, the shell has not exited, and the 521.Fl s 522option is set, it will continue reading more commands from standard input. 523This option has no effect when set or reset after the shell has 524already started reading from the command_file, or from standard input. 525Note that the 526.Fl s 527flag being set does not, of itself, cause the shell to be interactive. 528.It Fl u Em nounset 529Write a message to standard error when attempting to obtain a 530value from a variable that is not set, 531and if the shell is not interactive, exit immediately. 532For interactive shells, instead return immediately to the command prompt 533and read the next command. 534Note that expansions (described later, see 535.Sx Word Expansions 536below) using the 537.Sq \&+ , 538.Sq \&\- , 539.Sq \&= , 540or 541.Sq \&? 542operators test if the variable is set, before attempting to 543obtain its value, and hence are unaffected by 544.Fl u . 545.It Fl V Em vi 546Enable the built-in 547.Xr vi 1 548command line editor (disables 549.Fl E 550if it had been set). 551(See the 552.Sx Command Line Editing 553section below.) 554.It Fl v Em verbose 555The shell writes its input to standard error as it is read. 556Perhaps occasionally useful for some debugging. 557.It Fl X Em xlock 558Cause output from the 559.Ic xtrace 560.Pq Fl x 561option to be sent to standard error as it exists when the 562.Fl X 563option is enabled (regardless of its previous state.) 564For example: 565.Bd -literal -compact 566 set -X 2>/tmp/trace-file 567.Ed 568will arrange for tracing output to be sent to the file named, 569instead of wherever it was previously being sent, 570until the X option is set again, or cleared. 571.Pp 572Each change (set or clear) to 573.Fl X 574is also performed upon 575.Fl x , 576but not the converse. 577.It Fl x Em xtrace 578Write each command to standard error (preceded by the expanded value of 579.Li $PS4 ) 580before it is executed. 581Unless 582.Fl X 583is set, 584.Dq "standard error" 585means that which existed immediately before any redirections to 586be applied to the command are performed. 587Useful for debugging. 588.El 589.Pp 590The following options have no one letter variant, 591and are used only in conjunction with 592.Fl o 593or 594.Cm +o , 595either on the command line, or via the 596.Ic set 597built-in command. 598.Bl -tag -width ".Fl L Em local_lineno" -offset indent 599.It "\ \ " Em cdprint 600Make an interactive shell always print the new directory name when 601changed by the 602.Ic cd 603command. 604If the 605.Em posix 606option is set, this option also applies to non-interactive shells. 607However, 608.Em cdprint 609is an extension to POSIX, so these two options should 610rarely be set at the same time. 611.It "\ \ " Em nolog 612Prevent the entry of function definitions into the command history (see 613.Ic fc 614in the 615.Sx Built-ins 616section.) 617(Not implemented.) 618.It "\ \ " Em pipefail 619If set when a pipeline is created, 620the way the exit status of the pipeline is determined 621is altered. 622See 623.Sx Pipelines 624below for the details. 625.It "\ \ " Em posix 626Enables closer adherence to the POSIX shell standard. 627This option will default set at shell startup if the 628environment variable 629.Ev POSIXLY_CORRECT 630is present. 631That can be overridden (set or reset) by the 632.Fl o 633option on the command line. 634Currently this option controls whether (!posix) or not (posix) 635the file given by the 636.Ev ENV 637variable is read at startup by a non-interactive shell. 638It also controls whether file descriptors greater than 2 639opened using the 640.Ic exec 641built-in command are passed on to utilities executed 642.Dq ( yes 643in posix mode, though the POSIX standard does not actually require this), 644whether a colon (:) terminates the user name in tilde (~) expansions 645other than in assignment statements 646.Dq ( no 647in posix mode), 648the format of the output of the 649.Ic kill Fl l 650command, where posix mode causes the names of the signals 651be separated by either a single space or newline, and where otherwise 652sufficient spaces are inserted to generate nice looking columns, 653and whether the shell treats 654an empty brace-list compound statement as a syntax error 655(expected by POSIX) or permits it. 656Such statements 657.Dq "{\ }" 658can be useful when defining dummy functions. 659Lastly, in posix mode, only one 660.Dq \&! 661is permitted before a pipeline. 662.It "\ \ " Em promptcmds 663Allows command substitutions (as well as parameter 664and arithmetic expansions, which are always performed) 665upon the prompt strings 666.Ev PS1 , 667.Ev PS2 , 668and 669.Ev PS4 670each time, before they are output. 671This option should not be set until after the prompts 672have been set (or verified) to avoid accidentally importing 673unwanted command substitutions from the environment. 674.It "\ \ " Em tabcomplete 675Enables filename completion in the command line editor. 676Typing a tab character will extend the current input word to match a 677filename. 678If more than one filename matches it is only extended to be the common prefix. 679Typing a second tab character will list all the matching names. 680One of the editing modes, either 681.Fl E 682or 683.Fl V , 684must be enabled for this to work. 685.El 686.Ss Lexical Structure 687The shell reads input in terms of lines from a file 688(or its standard input, or an argument string), 689removes comments, 690and then breaks it up into words at whitespace (blanks and tabs), and at 691certain sequences of characters that are special to the shell called 692.Dq operators . 693Unquoted whitespace is removed as part of this, after serving to 694separate words or operators. 695There are two types of operators: control operators and redirection 696operators (their meaning is discussed later). 697The following is a list of operators: 698.Bl -ohang -offset indent 699.It "Control operators:" 700.Dl & && \&( \&) \&; ;; ;& \&| || <newline> 701.It "Redirection operators:" 702.Dl < > >| << >> <& >& <<- <> 703.El 704.Pp 705The shell will detect an operator, which must be entirely unquoted, 706at any point in the input line (other than in comments, which have 707already been removed), 708and sometimes other than immediately after an unquoted dollar 709.Pq Sq \&$ 710character, see 711.Sx Word Expansions 712below for defined sequences starting with 713.Pq Sq \&$ 714which always form (part of) a word, even if some of the 715following characters would otherwise appear to be operators. 716.Pp 717For future proofing, it is advisable to precede and 718follow all operators with either line endings or whitespace. 719When recognizing an operator the longest sequence of characters 720present which form a valid operator are detected as that operator 721rather than shorter alternative sequences, so, for example, 722the sequence 723.Dl >& 724is always recognized as the two character redirection operator 725.Dq Li \&>& 726rather than the 727.Dq Li \&> 728redirection operator followed by control operator 729.Dq Li \&& . 730So while currently the sequence 731.Dl ;) 732is recognized as the two control operators 733.Dq Li \&; 734followed by 735.Dq Li \&) , 736a future extension could create a new operator 737.Dq Li \&;) 738in which case that would be detected instead. 739Writing the sequence as 740.Dl ;\ ) 741(note the space between the semicolon and parenthesis) 742guarantees that it will be recognized as two operators. 743Note that this does happen, the 744.Dq Li ;& 745control operator shown above is relatively new (by shell standards) 746and would once have been parsed as two operators. 747.Pp 748Also note that any of the redirection operators listed above may be 749immediately preceded by a digit sequence, with no intervening 750whitespace. 751Those digits form part of the redirection operator. 752See 753.Sx Redirections 754below for more details. 755.Ss Comments 756A shell comment begins with a 757.Sq Li \&# 758character at the beginning of a word, that is, at the beginning of 759the line, or after unquoted whitespace or an operator. 760All characters, without interpretation, from (and including) the 761.Sq Li \&# , 762until the end of the current line (or EOF), but excluding the line ending 763.Sq Li \en , 764are removed from the input. 765Note that it is not possible to continue a line containing a comment. 766Also note that a 767.Sq Li \&# 768character at any other place within a word is simply a character, 769and is sometimes required to implement specific shell operations. 770.Ss Quoting 771Quoting is used to remove the special meaning of certain characters or 772words to the shell, such as operators, whitespace, or keywords. 773Beginning or ending a quoted sequence does not end a shell word. 774There are four types of quoting: 775matched single quotes, 776matched double quotes, 777backslash, 778and 779dollar preceding matched single quotes (enhanced C style strings.) 780.Ss Backslash 781An unquoted backslash quotes, and so preserves the literal meaning of, 782the following character, with the exception of 783.Aq newline . 784That is, the quoted character just means itself, and is not considered 785as an operator, or whitespace, or the beginning of a comment, or any 786other special meaning it may otherwise have had. 787It may be joined with adjacent characters (along with the quoting 788backslash, which is removed much later) to form part of a word. 789An unquoted backslash preceding a 790.Aq newline 791is treated as a line continuation, the two characters are simply removed. 792.Ss Single Quotes 793Enclosing characters in a pair of single quotes preserves the literal meaning of all 794the characters between them (except single quotes, making it impossible to put 795single quotes in a single-quoted string). 796.Ss Double Quotes 797Enclosing characters within double quotes preserves the literal 798meaning of all characters except dollar sign 799.Pq Li \&$ , 800backquote 801.Pq Li \&` , 802backslash 803.Pq Li \e , 804and itself 805.Pq Li \*q . 806The backslash inside double quotes is historically weird, and serves to 807quote only the following characters (and these not in all contexts): 808.Dl $ ` \*q \e <newline> , 809where a backslash newline is a line continuation as above. 810Otherwise it remains literal. 811The dollar sign and backquote characters, inside a double quoted 812string, if not escaped by a backslash, retain the meaning they would 813have if unquoted, however the results of any expansion(s) they eventually 814generate are treated as quoted in this case. 815.\" 816.\" 817.Ss Dollar Single Quotes ( Li \&$'...' ) 818Enclosing characters in a matched pair of single quotes, with the 819first immediately preceded by an unquoted dollar sign 820.Pq Li \&$ 821provides a quoting mechanism similar to single quotes, except 822that within the sequence of characters, any backslash 823.Pq Li \e , 824is an escape character, which causes the following character to 825be treated specially. 826Only a subset of the characters that can occur in the string 827are defined after a backslash, others are reserved for future 828definition, and currently generate a syntax error if used. 829The escape sequences are modeled after the similar sequences 830in strings in the C programming language, with some extensions. 831.Pp 832The following characters are treated literally when following 833the escape character (backslash): 834.Dl \e \&' \(dq 835The sequence 836.Dq Li \e\e 837allows the escape character (backslash) to appear in the string literally. 838.Dq Li \e' 839allows a single quote character into the string, such an 840escaped single quote does not terminate the quoted string. 841.Dq Li \e\(dq 842is for compatibility with C strings, the double quote has 843no special meaning in a shell C-style string, 844and does not need to be escaped, but may be. 845.Pp 846A newline following the escape character is treated as a line continuation, 847like the same sequence in a double quoted string, 848or when not quoted \(en 849the two characters, the backslash escape and the newline, 850are removed from the input string. 851.Pp 852The following characters, when escaped, are converted in a 853manner similar to the way they would be in a string in the C language: 854.Dl a b e f n r t v 855An escaped 856.Sq a 857generates an alert (or 858.Sq BEL ) 859character, that is, control-G, or 0x07. 860In a similar way, 861.Sq b 862is backspace (0x08), 863.Sq e 864(an extension to C) is escape (0x1B), 865.Sq f 866is form feed (0x0C), 867.Sq n 868is newline (or line feed, 0x0A), 869.Sq r 870is return (0x0D), 871.Sq t 872is horizontal tab (0x09), 873and 874.Sq v 875is vertical tab (0x13). 876.Pp 877In addition to those there are 5 forms that need additional 878data, which is obtained from the subsequent characters. 879An escape 880.Pq Li \e 881followed by one, two or three, octal digits 882.Po So 0 Sc Ns \&.. Ns So 7 Sc Ns Pc 883is processed to form an 8 bit character value. 884If only one or two digits are present, the following 885character must be something other than an octal digit. 886It is safest to always use all 3 digits, with leading 887zeros if needed. 888If all three digits are present, the first must be one of 889.So 0 Sc Ns \&.. Ns So 3 Sc . 890.Pp 891An escape followed by 892.Sq x 893(lower case only) can be followed by one or two 894hexadecimal digits 895.Po So 0 Sc Ns \&.. Ns So 9 Sc , So A Sc Ns \&.. Ns So F Sc , or So a Sc Ns \&.. Ns So f Sc . Pc 896As with octal, if only one hex digit is present, the following 897character must be something other than a hex digit, 898so always giving 2 hex digits is best. 899However, unlike octal, it is unspecified in the standard 900how many hex digits can be consumed. 901This 902.Nm 903takes at most two, but other shells will continue consuming 904characters as long as they remain valid hex digits. 905Consequently, users should ensure that the character 906following the hex escape sequence is something other than 907a hex digit. 908One way to achieve this is to end the 909.Li $'...' 910string immediately 911after the final hex digit, and then, immediately start 912another, so 913.Dl \&$'\ex33'$'4...' 914always gives the character with value 0x33 915.Pq Sq 3 , 916followed by the character 917.Sq 4 , 918whereas 919.Dl \&$'\ex334' 920in some other shells would be the hex value 0x334 (10, or more, bits). 921.Pp 922There are two escape sequences beginning with 923.Sq Li \eu 924or 925.Sq Li \eU . 926The former is followed by from 1 to 4 hex digits, the latter by 927from 1 to 8 hex digits. 928Leading zeros can be used to pad the sequences to the maximum 929permitted length, to avoid any possible ambiguity problem with 930the following character, and because there are some shells that 931insist on exactly 4 (or 8) hex digits. 932These sequences are evaluated to form the value of a Unicode code 933point, which is then encoded into UTF-8 form, and entered into the 934string. 935(The code point should be converted to the appropriate 936code point value for the corresponding character in the character 937set given by the current locale, or perhaps the locale in use 938when the shell was started, but is not... currently.) 939Not all values that are possible to write are valid, values that 940specify (known) invalid Unicode code points will be rejected, or 941simply produce 942.Sq \&? . 943.Pp 944Lastly, as another addition to what is available in C, the escape 945character (backslash), followed by 946.Sq c 947(lower case only) followed by one additional character, which must 948be an alphabetic character (a letter), or one of the following: 949.Dl \&@ \&[ \&\e \&] \&^ \&_ \&? 950Other than 951.Sq Li \ec? 952the value obtained is the least significant 5 bits of the 953ASCII value of the character following the 954.Sq Li \ec 955escape sequence. 956That is what is commonly known as the 957.Dq control 958character obtained from the given character. 959The escape sequence 960.Sq Li \ec? 961yields the ASCII DEL character (0x7F). 962Note that to obtain the ASCII FS character (0x1C) this way, 963.Pq "that is control-\e" 964the trailing 965.Sq Li \e 966must be escaped itself, and so for this one case, the full 967escape sequence is 968.Dq Li \ec\e\e . 969The sequence 970.Dq Li \ec\e Ns Ar X\^ 971where 972.Sq Ar X\^ 973is some character other than 974.Sq Li \e 975is reserved for future use, its meaning is unspecified. 976In this 977.Nm 978an error is generated. 979.Pp 980If any of the preceding escape sequences generate the value 981.Sq \e0 982(a NUL character) that character, and all that follow in the same 983.Li $'...' 984string, are omitted from the resulting word. 985.Pp 986After the 987.Li $'...' 988string has had any included escape sequences 989converted, it is treated as if it had been a single quoted string. 990.\" 991.\" 992.Ss Reserved Words 993.\" 994Reserved words are words that have special meaning to the 995shell and are recognized, 996if completely unquoted, 997at the beginning of a line, 998after a control operator, 999and where the syntax of a command specifically requires a reserved word. 1000The following are reserved words: 1001.Bl -column while while while while -offset indent 1002.It Ic \&! Ta Ic \&{ Ta Ic \&} Ta Ic case 1003.It Ic do Ta Ic done Ta Ic elif Ta Ic else 1004.It Ic esac Ta Ic fi Ta Ic for Ta Ic if 1005.It Ic in Ta Ic then Ta Ic until Ta Ic while 1006.El 1007.Pp 1008Their meanings are discussed later. 1009.\" 1010.\" 1011.Ss Aliases 1012.\" 1013An alias is a name and corresponding value set using the 1014.Ic alias 1015built-in command. 1016Whenever a reserved word (see above) may occur, 1017and after checking for reserved words, the shell 1018checks the word to see if it matches an alias. 1019If it does, the alias word is replaced by its value in the input stream, 1020as if the value had been entered instead. 1021For example, if there is an alias called 1022.Dq lf 1023with the value 1024.Dq "ls -F" , 1025then the input: 1026.Pp 1027.Dl lf foobar Aq return 1028.Pp 1029would become 1030.Pp 1031.Dl ls -F foobar Aq return 1032.Pp 1033Aliases provide a convenient way for naive users to create shorthands for 1034commands without having to learn how to create functions with arguments. 1035They can also be used to create lexically obscure code. 1036This use is strongly discouraged. 1037.\" 1038.Ss Commands 1039.\" 1040The shell interprets the words it reads according to a language, the 1041specification of which is outside the scope of this man page (refer to the 1042BNF in the POSIX 1003.2 document). 1043Essentially though, a line is read and if the first 1044word of the line (or after a control operator) is not a reserved word, 1045then the shell has recognized a simple command. 1046Otherwise, a complex 1047command or some other special construct may have been recognized. 1048.\" 1049.\" 1050.Ss Simple Commands 1051.\" 1052If a simple command has been recognized, the shell performs 1053the following actions: 1054.Bl -enum -offset indent 1055.It 1056Leading words of the form 1057.Dq Ar name Ns Li = Ns Ar value 1058are stripped off, the value is expanded, as described below, 1059and the results are assigned to the environment of the simple command. 1060Redirection operators and their arguments (as described below) are 1061stripped off and saved for processing in step 3 below. 1062.It 1063The remaining words are expanded as described in the 1064.Sx Word Expansions 1065section below. 1066The first remaining word is considered the command name and the 1067command is located. 1068Any remaining words are considered the arguments of the command. 1069If no command name resulted, then the 1070.Dq Ar name Ns Li = Ns Ar value 1071variable assignments recognized in item 1 affect the current shell, 1072but are not automatically added to the environment (are not exported). 1073.It 1074Redirections are performed, from first to last, in the order given, 1075as described in the next section. 1076.El 1077.\" 1078.\" 1079.Ss Redirections 1080.\" 1081Redirections are used to change where a command reads its input or sends 1082its output. 1083In general, redirections open, close, or duplicate an 1084existing reference to a file. 1085The overall format used for redirection is: 1086.Pp 1087.Dl Oo Ar n Oc Ns Va redir-op Ar file 1088.Pp 1089where 1090.Va redir-op 1091is one of the redirection operators mentioned previously. 1092A list of the possible redirections, and their meanings, follows. 1093.Pp 1094The 1095.Op Ar n 1096is an optional number, as in 1097.Sq Li 3 1098(not 1099.Sq Li [3] ) , 1100that refers to a file descriptor. 1101If present it must occur unquoted, immediately before the redirection 1102operator, with no intervening white space, and becomes a 1103part of that operator. 1104If not explicitly present, 1105.Ar n 1106will be 0 (standard input) 1107or 1 (standard output) 1108depending upon the redirection operator used. 1109If file descriptor 1110.Ar n 1111was open prior to the redirection, its previous use is closed. 1112.Pp 1113All redirections have a single word 1114.Ar file 1115argument following the operator 1116(white space is allowed between the redirection operator and 1117.Ar file ) , 1118though it is sometimes expressed as 1119.Ar n2 . 1120That argument is expanded 1121(see 1122.Sx "Word Expansions" 1123below) using tilde expansion, parameter expansion, 1124arithmetic expansion, command substitution and quote removal 1125to produce the path name (or file descriptor) to be used. 1126No field splitting or pathname expansion takes place. 1127In the list below, where the 1128.Ar file 1129is given as 1130.Ar n2 1131the result of the expansions must be a number which 1132refers to a suitable open file descriptor. 1133.Bl -tag -width aaabsfiles -offset indent 1134.It Oo Ar n Oc Ns Ic > Ar file 1135Redirect standard output (or 1136.Ar n ) 1137to 1138.Ar file . 1139.It Oo Ar n Oc Ns Ic >| Ar file 1140The same, but override the 1141.Fl C 1142option. 1143.It Oo Ar n Oc Ns Ic >> Ar file 1144Append standard output (or 1145.Ar n ) 1146to 1147.Ar file . 1148.It Oo Ar n Oc Ns Ic < Ar file 1149Redirect standard input (or 1150.Ar n ) 1151from 1152.Ar file . 1153.It Oo Ar n1 Oc Ns Ic <& Ar n2 1154Redirect standard input (or 1155.Ar n1 ) 1156from a duplicate of file descriptor 1157.Ar n2 . 1158.It Oo Ar n Oc Ns Ic <& \(mi 1159Close standard input (or 1160.Ar n ) . 1161Note that the 1162.Sq \&\(mi 1163is minus sign (or hyphen) given literally or resulting 1164from the expansion of 1165.Ar file 1166(or 1167.Ar n2 ) 1168for this format. 1169When given literally there is usually no space between 1170the redirection operator and the 1171.Sq \&\(mi , 1172though that is just a convention. 1173.It Oo Ar n1 Oc Ns Ic >& Ar n2 1174Redirect standard output (or 1175.Ar n1 ) 1176to be a duplicate of 1177.Ar n2 . 1178.It Oo Ar n Oc Ns Ic >& \(mi 1179Close standard output (or 1180.Ar n ) . 1181.It Oo Ar n Oc Ns Ic <> Ar file 1182Open 1183.Ar file 1184for reading and writing on standard input (or 1185.Ar n ) . 1186.El 1187.Pp 1188The following redirection is often called a 1189.Dq here-document . 1190.Bd -unfilled -offset indent 1191.Oo Ar n Oc Ns Ic << Ar delimiter 1192.Li \&... here-doc-text ... 1193.Ar delimiter 1194.Ed 1195.Pp 1196The 1197.Dq here-doc-text 1198starts immediately after the next unquoted newline character following 1199the here-document redirection operator. 1200If there is more than one here-document redirection on the same 1201line, then the text for the first (from left to right) is read 1202first, and subsequent here-doc-text for later here-document redirections 1203follows immediately after, until all such redirections have been 1204processed. 1205.Pp 1206All the text on successive lines up to the delimiter, 1207which must appear on a line by itself, with nothing other 1208than an immediately following newline, is 1209saved away and made available to the command on standard input, or file 1210descriptor n if it is specified. 1211If the delimiter as specified on the initial line is 1212quoted, then the here-doc-text is treated literally; otherwise, the text is 1213treated much like a double quoted string, except that 1214.Sq Li \(dq 1215characters have no special meaning, and are not escaped by 1216.Sq Li \&\e , 1217and is subjected to parameter expansion, command substitution, and arithmetic 1218expansion as described in the 1219.Sx Word Expansions 1220section below. 1221If the operator is 1222.Ic <<- 1223instead of 1224.Ic << , 1225then leading tabs in all lines in the here-doc-text, including before the 1226end delimiter, are stripped. 1227If the delimiter is not quoted, lines in here-doc-text that end with 1228an unquoted 1229.Li \e 1230are joined to the following line, the 1231.Li \e 1232and following 1233newline are simply removed while reading the here-document, 1234which thus guarantees 1235that neither of those lines can be the end delimiter. 1236.Pp 1237It is a syntax error for the end of the input file (or string) to be 1238reached before the delimiter is encountered. 1239.\" 1240.\" 1241.Ss Search and Execution 1242.\" 1243There are three types of commands: shell functions, built-in commands, and 1244normal programs \(em and the command is searched for (by name) in that order. 1245A command that contains a slash 1246.Sq \&/ 1247in its name is always a normal program. 1248They each are executed in a different way. 1249.Pp 1250When a shell function is executed, all of the shell positional parameters 1251(note: excluding 1252.Li 0 , \" $0 1253which is a special, not positional, parameter, and remains unchanged) 1254are set to the arguments of the shell function. 1255The variables which are explicitly placed in the environment of 1256the command (by placing assignments to them before the function name) are 1257made local to the function and are set to the values given, 1258and exported for the benefit of programs executed within the function. 1259Then the command given in the function definition is executed. 1260The positional parameters, and local variables, are restored to 1261their original values when the command completes. 1262This all occurs within the current shell, and the function 1263can alter variables, or other settings, of the shell, but 1264not the positional parameters nor their related special parameters. 1265.Pp 1266Shell built-ins are executed internally to the shell, without spawning a 1267new process. 1268.Pp 1269Otherwise, if the command name doesn't match a function or built-in, the 1270command is searched for as a normal program in the file system (as 1271described in the next section). 1272When a normal program is executed, the shell runs the program, 1273passing the arguments and the environment to the program. 1274If the program is not a normal executable file, and if it does 1275not begin with the 1276.Dq magic number 1277whose ASCII representation is 1278.Dq Li "#!" , 1279so 1280.Xr execve 2 1281returns 1282.Er ENOEXEC 1283then) the shell will interpret the program in a sub-shell. 1284The child shell will reinitialize itself in this case, 1285so that the effect will be as if a 1286new shell had been invoked to handle the ad-hoc shell script, except that 1287the location of hashed commands located in the parent shell will be 1288remembered by the child. 1289.Pp 1290Note that previous versions of this document and the source code itself 1291misleadingly and sporadically refer to a shell script without a magic 1292number as a 1293.Dq shell procedure . 1294.\" 1295.\" 1296.Ss Path Search 1297.\" 1298When locating a command, 1299command names containing a slash 1300.Pq Sq \&/ 1301are simply executed without performing any searches. 1302.Pp 1303If there is no slash in the name, 1304the shell first looks to see if it is a special built-in command, 1305if not it looks to see if there is a shell function by that name. 1306If that fails it looks for an ordinary built-in command. 1307If a none of these searches located the command 1308the shell searches each entry in 1309.Ev PATH 1310in turn for the command. 1311The value of the 1312.Ev PATH 1313variable should be a series of entries separated by colons. 1314Each entry consists of a directory name. 1315The current directory may be indicated 1316implicitly by an empty directory name, or explicitly by a single period. 1317If a directory searched contains an executable file with the same 1318name as the command given, 1319the search terminates, and that program is executed. 1320.Ss Command Exit Status 1321Each command has an exit status that can influence the behavior 1322of other shell commands. 1323The paradigm is that a command exits 1324with zero in normal cases, or to indicate success, 1325and non-zero for failure, 1326error, or a false indication. 1327The man page for each command 1328should indicate the various exit codes and what they mean. 1329Additionally, the built-in commands return exit codes, as does 1330an executed shell function. 1331.Pp 1332If a command consists entirely of variable assignments then the 1333exit status of the command is that of the last command substitution 1334if any, otherwise 0. 1335.Pp 1336If redirections are present, and any fail to be correctly performed, 1337any command present is not executed, and an exit status of 2 1338is returned. 1339.Ss Complex Commands 1340Complex commands are combinations of simple commands with control 1341operators or reserved words, together creating a larger complex command. 1342Overall, a shell program is a: 1343.Bl -tag -width XpipelineX 1344.It list 1345Which is a sequence of one or more AND-OR lists. 1346.It "AND-OR list" 1347is a sequence of one or more pipelines. 1348.It pipeline 1349is a sequence of one or more commands. 1350.It command 1351is one of a simple command, a compound command, or a function definition. 1352.It "simple command" 1353has been explained above, and is the basic building block. 1354.It "compound command" 1355provides mechanisms to group lists to achieve different effects. 1356.It "function definition" 1357allows new simple commands to be created as groupings of existing commands. 1358.El 1359.Pp 1360Unless otherwise stated, the exit status of a list 1361is that of the last simple command executed by the list. 1362.\" 1363.\" 1364.Ss Pipelines 1365.\" 1366A pipeline is a sequence of one or more commands separated 1367by the control operator 1368.Sq Ic \(ba , 1369and optionally preceded by the 1370.Dq Ic \&! 1371reserved word. 1372Note that 1373.Sq Ic \(ba 1374is an operator, and so is recognized anywhere it appears unquoted, 1375it does not require surrounding white space or other syntax elements. 1376On the other hand 1377.Dq Ic \&! 1378being a reserved word, must be separated from adjacent words by 1379white space (or other operators, perhaps redirects) and is only 1380recognized as the reserved word when it appears in a command word 1381position (such as at the beginning of a pipeline.) 1382.Pp 1383The standard output of all but 1384the last command in the sequence is connected to the standard input 1385of the next command. 1386The standard output of the last 1387command is inherited from the shell, as usual, 1388as is the standard input of the first command. 1389.Pp 1390The format for a pipeline is: 1391.Pp 1392.Dl [!] command1 Op Li \&| command2 No ... 1393.Pp 1394The standard output of command1 is connected to the standard input of 1395command2. 1396The standard input, standard output, or both of each command is 1397considered to be assigned by the pipeline before any redirection specified 1398by redirection operators that are part of the command are performed. 1399.Pp 1400If the pipeline is not in the background (discussed later), the shell 1401waits for all commands to complete. 1402.Pp 1403The commands in a pipeline can either be simple commands, 1404or one of the compound commands described below. 1405The simplest case of a pipeline is a single simple command. 1406.Pp 1407If the 1408.Ic pipefail 1409option was set when a pipeline was started, 1410the pipeline status is the status of 1411the last (lexically last, i.e.: rightmost) command in the 1412pipeline to exit with non-zero exit status, or zero, if, 1413and only if, all commands in the pipeline exited with a status of zero. 1414If the 1415.Ic pipefail 1416option was not set, which is the default state, 1417the pipeline status is the exit 1418status of the last (rightmost) command in the pipeline, 1419and the exit status of any other commands in the pipeline is ignored. 1420.Pp 1421If the reserved word 1422.Dq Ic \&! 1423precedes the pipeline, the exit status 1424becomes the logical NOT of the pipeline status as determined above. 1425That is, if the pipeline status is zero, the exit status is 1; 1426if the pipeline status is other than zero, the exit status is zero. 1427If there is no 1428.Dq Ic \&! 1429reserved word, the pipeline status becomes the exit status. 1430.Pp 1431Because pipeline assignment of standard input or standard output or both 1432takes place before redirection, it can be modified by redirection. 1433For example: 1434.Pp 1435.Dl $ command1 2>&1 \&| command2 1436.Pp 1437sends both the standard output and standard error of command1 1438to the standard input of command2. 1439.Pp 1440Note that unlike some other shells, each process in the pipeline is a 1441child of the invoking shell, except in the case where the pipeline 1442is a single simple command (no 1443.Sq Ic \(ba 1444characters appear.) 1445.Pp 1446A pipeline is a simple case of an AND-OR-list (described below.) 1447A 1448.Li \&; 1449or 1450.Aq newline 1451terminator causes the preceding pipeline, or more generally, 1452the preceding AND-OR-list to be executed sequentially; 1453that is, the shell executes the commands, and waits for them 1454to finish before proceeding to following commands. 1455An 1456.Li \&& 1457terminator causes asynchronous (background) execution 1458of the preceding AND-OR-list (see the next paragraph below). 1459The exit status of an asynchronous AND-OR-list is zero. 1460The actual status of the commands, 1461after they have completed, 1462can be obtained using the 1463.Ic wait 1464built-in command described later. 1465.\" 1466.\" 1467.Ss Background Commands \(em Ic \&& 1468.\" 1469If a command, pipeline, or AND-OR-list 1470is terminated by the control operator ampersand 1471.Pq Li \&& , 1472the 1473shell executes the command asynchronously \(em that is, the shell does not 1474wait for the command to finish before executing the next command. 1475.Pp 1476The format for running a command in background is: 1477.Pp 1478.Dl command1 & Op Li command2 & No ... 1479.Pp 1480If the shell is not interactive, the standard input of an asynchronous 1481command is set to 1482.Pa /dev/null . 1483The process identifier of the most recent command started in the 1484background can be obtained from the value of the special parameter 1485.Dq Dv \&! \" $! 1486(see 1487.Sx Special Parameters ) 1488provided it is accessed before the next asynchronous command is started. 1489.\" 1490.\" 1491.Ss Lists \(em Generally Speaking 1492.\" 1493A list is a sequence of one or more commands separated by newlines, 1494semicolons, or ampersands, and optionally terminated by one of these three 1495characters. 1496A shell program, which includes the commands given to an 1497interactive shell, is a list. 1498Each command in such a list is executed when it is fully parsed. 1499Another use of a list is as a complete-command, 1500which is parsed in its entirety, and then later the commands in 1501the list are executed only if there were no parsing errors. 1502.Pp 1503The commands in a list are executed in the order they are written. 1504If command is followed by an ampersand, the shell starts the 1505command and immediately proceeds to the next command; otherwise it waits 1506for the command to terminate before proceeding to the next one. 1507A newline is equivalent to a 1508.Sq Li \&; 1509when no other operator is present, and the command being input 1510could syntactically correctly be terminated at the point where 1511the newline is encountered, otherwise it is just whitespace. 1512.\" 1513.\" 1514.Ss AND-OR Lists (Short-Circuit List Operators) 1515.\" 1516.Dq Li \&&& 1517and 1518.Dq Li \&|| 1519are AND-OR list operators. 1520After executing the commands that precede the 1521.Dq Li \&&& 1522the subsequent command is executed 1523if and only if the exit status of the preceding command(s) is zero. 1524.Dq Li \&|| 1525is similar, but executes the subsequent command if and only if the exit status 1526of the preceding command is nonzero. 1527If a command is not executed, the exit status remains unchanged 1528and the following AND-OR list operator (if any) uses that status. 1529.Dq Li \&&& 1530and 1531.Dq Li \&|| 1532both have the same priority. 1533Note that these operators are left-associative, so 1534.Dl true || echo bar && echo baz 1535writes 1536.Dq baz 1537and nothing else. 1538This is not the way it works in C. 1539.\" 1540.\" 1541.Ss Flow-Control Constructs \(em Ic if , while , until , for , case 1542.\" 1543These commands are instances of compound commands. 1544The syntax of the 1545.Ic if 1546command is 1547.Bd -unfilled -offset indent 1548.Ic if Ar list 1549.Ic then Ar list 1550.Oo Ic elif Ar list 1551.Ic then Ar list Oc No ... 1552.Op Ic else Ar list 1553.Ic fi 1554.Ed 1555.Pp 1556The first list is executed, and if the exit status of that list is zero, 1557the list following the 1558.Ic then 1559is executed. 1560Otherwise the list after an 1561.Ic elif 1562(if any) is executed and the process repeats. 1563When no more 1564.Ic elif 1565reserved words, and accompanying lists, appear, 1566the list after the 1567.Ic else 1568reserved word, if any, is executed. 1569.Pp 1570The syntax of the 1571.Ic while 1572command is 1573.Bd -unfilled -offset indent 1574.Ic while Ar list 1575.Ic do Ar list 1576.Ic done 1577.Ed 1578.Pp 1579The two lists are executed repeatedly while the exit status of the 1580first list is zero. 1581The 1582.Ic until 1583command is similar, but has the word 1584.Ic until 1585in place of 1586.Ic while , 1587which causes it to repeat until the exit status of the first list is zero. 1588.Pp 1589The syntax of the 1590.Ic for 1591command is 1592.Bd -unfilled -offset indent 1593.Ic for Ar variable Op Ic in Ar word No ... 1594.Ic do Ar list 1595.Ic done 1596.Ed 1597.Pp 1598The words are expanded, or 1599.Li \*q$@\*q 1600if 1601.Ic in 1602(and the following words) is not present, 1603and then the list is executed repeatedly with the 1604variable set to each word in turn. 1605If 1606.Ic in 1607appears after the variable, but no words are 1608present, the list is not executed, and the exit status is zero. 1609.Ic do 1610and 1611.Ic done 1612may be replaced with 1613.Sq Ic \&{ 1614and 1615.Sq Ic \&} , 1616but doing so is non-standard and not recommended. 1617.Pp 1618The syntax of the 1619.Ic break 1620and 1621.Ic continue 1622commands is 1623.Bd -unfilled -offset indent 1624.Ic break Op Ar num 1625.Ic continue Op Ar num 1626.Ed 1627.Pp 1628.Ic break 1629terminates the 1630.Ar num 1631innermost 1632.Ic for , while , 1633or 1634.Ic until 1635loops. 1636.Ic continue 1637breaks execution of the 1638.Ar num\^ Ns -1 1639innermost 1640.Ic for , while , 1641or 1642.Ic until 1643loops, and then continues with the next iteration of the enclosing loop. 1644These are implemented as special built-in commands. 1645The parameter 1646.Ar num , 1647if given, must be an unsigned positive integer (greater than zero). 1648If not given, 1 is used. 1649.Pp 1650The syntax of the 1651.Ic case 1652command is 1653.Bd -unfilled -offset indent 1654.Ic case Ar word Ic in 1655.Oo Ic \&( Oc Ar pattern Ns Ic \&) Oo Ar list Oc Ic \&;& 1656.Oo Ic \&( Oc Ar pattern Ns Ic \&) Oo Ar list Oc Ic \&;; 1657.No \&... 1658.Ic esac 1659.Ed 1660.Pp 1661The pattern can actually be one or more patterns (see 1662.Sx Shell Patterns 1663described later), separated by 1664.Dq \(or 1665characters. 1666.Pp 1667.Ar word 1668is expanded and matched against each 1669.Ar pattern 1670in turn, 1671from first to last, 1672with each pattern being expanded just before the match is attempted. 1673When a match is found, pattern comparisons cease, and the associated 1674.Ar list , 1675if given, 1676is evaluated. 1677If the list is terminated with 1678.Dq Ic \&;& 1679execution then falls through to the following list, if any, 1680without evaluating its pattern, or attempting a match. 1681When a list terminated with 1682.Dq Ic \&;; 1683has been executed, or when 1684.Ic esac 1685is reached, execution of the 1686.Ic case 1687statement is complete. 1688The exit status is that of the last command executed 1689from the last list evaluated, if any, or zero otherwise. 1690.\" 1691.\" 1692.Ss Grouping Commands Together 1693.\" 1694Commands may be grouped by writing either 1695.Dl Ic \&( Ns Ar list Ns Ic \&) 1696or 1697.Dl Ic \&{ Ar list Ns Ic \&; \&} 1698These also form compound commands. 1699.Pp 1700Note that while parentheses are operators, and do not require 1701any extra syntax, braces are reserved words, so the opening brace 1702must be followed by white space (or some other operator), and the 1703closing brace must occur in a position where a new command word might 1704otherwise appear. 1705.Pp 1706The first of these executes the commands in a sub-shell. 1707Built-in commands grouped into a 1708.Li \&( Ns Ar list Ns \&) 1709will not affect the current shell. 1710The second form does not fork another shell so is slightly more efficient, 1711and allows for commands which do affect the current shell. 1712Grouping commands together this way allows you to redirect 1713their output as though they were one program: 1714.Bd -literal -offset indent 1715{ echo -n \*qhello \*q ; echo \*qworld\*q ; } > greeting 1716.Ed 1717.Pp 1718Note that 1719.Dq Ic } 1720must follow a control operator (here, 1721.Dq Ic \&; ) 1722so that it is recognized as a reserved word and not as another command argument. 1723.\" 1724.\" 1725.Ss Functions 1726.\" 1727The syntax of a function definition is 1728.Pp 1729.Dl Ar name Ns Ic \&() Ar command Op Ar redirect No ... 1730.Pp 1731A function definition is an executable statement; when executed it 1732installs a function named 1733.Ar name 1734and returns an exit status of zero. 1735To be portable, and standards compliant, the name must use the same 1736syntax as a variable name, (see 1737.Sx "Variables and Parameters" 1738below). 1739As an extension, this shell allows almost all characters in 1740.Ar name 1741.Po 1742the exception is slash 1743.Pq Sq \&/ 1744as there is no way to invoke a function with a name containing 1745a slash 1746.Pc . 1747Including quoting, whitespace, and operator characters requires 1748that the word be quoted. 1749The 1750.Ar name 1751is subject to quote removal, but no other expansions. 1752Because of implementation issues, 1753unquoted dollar signs 1754.Pq Sq \&$ 1755and backquotes 1756.Pq Sq \&` 1757are prohibited, 1758but can be included in a function name by use of quoting. 1759.Pp 1760The command is normally a list enclosed between 1761.Dq { 1762and 1763.Dq } . 1764The standard syntax also allows the command to be any of the other 1765compound commands, including a sub-shell, all of which are supported. 1766As an extension, this shell also allows a simple command 1767(or even another function definition) to be 1768used, though users should be aware this is non-standard syntax. 1769This means that 1770.Dl l() ls \*q$@\*q 1771works to make 1772.Dq l 1773an alternative name for the 1774.Ic ls 1775command. 1776.Pp 1777If the optional redirect, (see 1778.Sx Redirections ) , 1779which may be of any of the normal forms, 1780is given, it is applied each time the 1781function is called. 1782This means that a simple 1783.Dq Hello World 1784function might be written (in the extended syntax) as: 1785.Bd -literal -offset indent 1786hello() cat <<EOF 1787Hello World! 1788EOF 1789.Ed 1790.Pp 1791To be correctly standards conforming this should be re-written as: 1792.Bd -literal -offset indent 1793hello() { cat; } <<EOF 1794Hello World! 1795EOF 1796.Ed 1797.Pp 1798Note the distinction between those forms, and 1799.Bd -literal -offset indent 1800hello() { cat <<EOF 1801Hello World! 1802EOF 1803\&} 1804.Ed 1805.Pp 1806which reads and processes the here-document 1807each time the shell executes the function, and which applies 1808that input only to the cat command, not to any other commands 1809that might appear in the function. 1810.Pp 1811Variables may be declared to be local to a function by using the 1812.Ic local 1813command. 1814This should usually appear as the first statement of a function, 1815though 1816.Ic local 1817is an executable command which can be used anywhere in a function. 1818See 1819.Sx Built-ins 1820below for its definition. 1821.Pp 1822The function completes after having executed 1823.Ar command 1824with exit status set to the status returned by 1825.Ar command . 1826If 1827.Ar command 1828is a compound-command 1829it can use the 1830.Ic return 1831command (see 1832.Sx Built-ins 1833below) 1834to finish before completing all of 1835.Ar command . 1836.Ss Variables and Parameters 1837The shell maintains a set of parameters. 1838A parameter denoted by a name is called a variable. 1839When starting up, the shell turns all the environment 1840variables into shell variables, and exports them. 1841New variables can be set using the form 1842.Pp 1843.Dl Ar name Ns Li = Ns Ar value 1844.Pp 1845Variables set by the user must have a name consisting solely of 1846alphabetics, numerics, and underscores \(em the first of which must not be 1847numeric. 1848A parameter can also be denoted by a number or a special 1849character as explained below. 1850.Ss Positional Parameters 1851A positional parameter is a parameter denoted by a number (n > 0). 1852The shell sets these initially to the values of its command line arguments 1853that follow the name of the shell script. 1854The 1855.Ic set 1856built-in can also be used to set or reset them, and 1857.Ic shift 1858can be used to manipulate the list. 1859.Pp 1860To refer to the 10th (and later) positional parameters, 1861the form 1862.Li \&${ Ns Ar n Ns Li \&} 1863must be used. 1864Without the braces, a digit following 1865.Dq $ 1866can only refer to one of the first 9 positional parameters, 1867or the special parameter 1868.Dv 0 . \" $0 1869The word 1870.Dq Li $10 1871is treated identically to 1872.Dq Li ${1}0 . 1873.\" 1874.\" 1875.Ss Special Parameters 1876.\" 1877A special parameter is a parameter denoted by one of the following special 1878characters. 1879The value of the parameter is listed next to its character. 1880.Bl -tag -width thinhyphena 1881.It Dv * 1882Expands to the positional parameters, starting from one. 1883When the 1884expansion occurs in a situation where field splitting is never 1885performed, such as within a double-quoted string, it expands to a single 1886field with the value of each parameter separated by the first character of 1887the 1888.Ev IFS 1889variable (possibly nothing if 1890.Ev IFS 1891has a null value), or by a 1892.Aq space 1893if 1894.Ev IFS 1895is unset. 1896.It Dv @ \" $@ 1897Expands to the positional parameters, starting from one. 1898When the expansion occurs within double quotes, each positional 1899parameter expands as a separate argument. 1900If the expansion happens in other situations where field splitting 1901is not performed, whether double quoted or not, the results are undefined. 1902In most shells, including this one, 1903.Dv \&$@ 1904is treated as 1905.Dv \&$* 1906in such a context, but this is not universally true. 1907If there are no positional parameters, the 1908expansion of @ generates zero arguments, even when 1909.Dv $@ 1910is double-quoted. 1911What this basically means, for example, is 1912if 1913.Li $1 1914is 1915.Dq abc 1916and 1917.Li $2 1918is 1919.Dq def\ ghi , 1920then 1921.Li \*q$@\*q 1922expands to 1923the two arguments: 1924.Pp 1925.Sm off 1926.Dl \*q abc \*q \ \*q def\ ghi \*q 1927.Sm on 1928.It Dv # 1929Expands to the number of positional parameters. 1930.It Dv \&? 1931Expands to the exit status of the most recent pipeline. 1932.It Dv \- No (dash, hyphen, or minus) 1933Expands to the current option flags (the single-letter 1934option names concatenated into a string) as specified on 1935invocation, by the set built-in command, or implicitly 1936by the shell. 1937.It Dv $ 1938Expands to the process ID of the invoked shell. 1939A sub-shell retains the same value of 1940.Dv $ 1941as its parent. 1942.It Dv \&! 1943Expands to the process ID of the most recent background 1944command executed from the current shell. 1945For a pipeline, the process ID is that of the last command in the pipeline. 1946If no background commands have yet been started by the shell, then 1947.Dq Dv \&! 1948will be unset. 1949Once set, the value of 1950.Dq Dv \&! 1951will be retained until another background command is started. 1952.It Dv 0 No (zero) \" $0 1953Expands to the name of the shell or shell script. 1954.El 1955.\" 1956.\" 1957.Ss Word Expansions 1958.\" 1959This section describes the various expansions that are performed on words. 1960Not all expansions are performed on every word, as explained later. 1961.Pp 1962Tilde expansions, parameter expansions, command substitutions, arithmetic 1963expansions, and quote removals that occur within a single word expand to a 1964single field. 1965It is only field splitting or pathname expansion that can 1966create multiple fields from a single word. 1967The single exception to this 1968rule is the expansion of the special parameter 1969.Dv @ \" $@ 1970within double quotes, as was described above. 1971.Pp 1972The order of word expansion is: 1973.Bl -enum 1974.It 1975Tilde Expansion, Parameter Expansion, Command Substitution, 1976Arithmetic Expansion (these all occur at the same time, and the 1977result of any of these expansions is not rescanned for further 1978instances of the expansion, or any of the others). 1979.It 1980Unless the 1981.Ev IFS 1982variable has an empty value, 1983Field Splitting is performed on the text resulting from 1984the expansions in step (1) except for Tilde Expansion. 1985.It 1986Pathname Expansion (unless set 1987.Fl f 1988is in effect). 1989.It 1990Quote Removal. 1991.El 1992.Pp 1993The $ character is used to introduce parameter expansion, command 1994substitution, or arithmetic evaluation. 1995.Ss Tilde Expansion (substituting a user's home directory) 1996A word beginning with an unquoted tilde character (~) is 1997subjected to tilde expansion. 1998Provided all of the subsequent characters in the word are unquoted 1999up to an unquoted slash (/) 2000or when in an assignment or not in posix mode, an unquoted colon (:), 2001or if neither of those appear, the end of the word, 2002they are treated as a user name 2003and are replaced with the pathname of the named user's home directory. 2004If the user name is missing (as in 2005.Pa ~/foobar ) , 2006the tilde is replaced with the value of the 2007.Dv HOME 2008variable (the current user's home directory). 2009.Pp 2010In variable assignments, 2011an unquoted tilde immediately after the assignment operator (=), and 2012each unquoted tilde immediately after an unquoted colon in the value 2013to be assigned is also subject to tilde expansion as just stated. 2014.\" 2015.\" 2016.Ss Parameter Expansion 2017.\" 2018The format for parameter expansion is as follows: 2019.Pp 2020.Dl ${ Ns Ar expression Ns Li } 2021.Pp 2022where 2023.Ar expression 2024consists of all characters until the matching 2025.Sq Li } . 2026Any 2027.Sq Li } 2028escaped by a backslash or within a quoted string, and characters in 2029embedded arithmetic expansions, command substitutions, and variable 2030expansions, are not examined in determining the matching 2031.Sq Li } . 2032.Pp 2033The simplest form for parameter expansion is: 2034.Pp 2035.Dl ${ Ns Ar parameter Ns Li } 2036.Pp 2037The value, if any, of 2038.Ar parameter 2039is substituted. 2040.Pp 2041The parameter name or symbol can be enclosed in braces, 2042which are optional in this simple case, 2043except for positional parameters with more than one digit or 2044when parameter is followed by a character that could be interpreted as 2045part of the name. 2046If a parameter expansion occurs inside double quotes: 2047.Bl -enum 2048.It 2049pathname expansion is not performed on the results of the expansion; 2050.It 2051field splitting is not performed on the results of the 2052expansion. 2053Note that the special rules for 2054.Dv @ \" $@ 2055can result in multiple fields being produced, but this is 2056not because of field-splitting. 2057If unquoted, each 2058field produced by 2059.Dv $@ \" $@ 2060is subject to field splitting. 2061.El 2062.Pp 2063In addition, a parameter expansion where braces are used, 2064can be modified by using one of the following formats. 2065If the 2066.Sq Ic \&: 2067is omitted in the following modifiers, then the test in the expansion 2068applies only to unset parameters, not null ones. 2069.Bl -tag -width aaparameterwordaaaaa 2070.It Li ${ Ns Ar parameter Ns Ic :- Ns Ar word Ns Li } 2071.Sy Use Default Values. 2072If 2073.Ar parameter 2074is unset or null, the expansion of 2075.Ar word 2076is substituted; otherwise, the value of 2077.Ar parameter 2078is substituted. 2079.It Li ${ Ns Ar parameter Ns Ic := Ns Ar word Ns Li } 2080.Sy Assign Default Values. 2081If 2082.Ar parameter 2083is unset or null, the expansion of 2084.Ar word 2085is assigned to 2086.Ar parameter . 2087In all cases, the final value of 2088.Ar parameter 2089is substituted. 2090Only variables, not positional parameters or special 2091parameters, can be assigned in this way. 2092.It Li ${ Ns Ar parameter Ns Ic :? Ns Oo Ar word\^ Oc Ns Li } 2093.Sy Indicate Error if Null or Unset. 2094If 2095.Ar parameter 2096is unset or null, the expansion of 2097.Ar word 2098(or a message indicating it is unset if 2099.Ar word 2100is omitted) 2101is written to standard error and a non-interactive shell exits with 2102a nonzero exit status. 2103An interactive shell will not exit, but any associated command(s) will 2104not be executed. 2105If the 2106.Ar parameter 2107is set, its value is substituted. 2108.It Li ${ Ns Ar parameter Ns Ic :+ Ns Ar word Ns Li } 2109.Sy Use Alternative Value. 2110If 2111.Ar parameter 2112is unset or null, null is substituted; 2113otherwise, the expansion of 2114.Ar word 2115is substituted. 2116The value of 2117.Ar parameter 2118.Em is not used 2119in this expansion. 2120.It Li ${ Ns Ic # Ns Ar parameter Ns Li } 2121.Sy String Length. 2122The length in characters of the value of 2123.Ar parameter . 2124.El 2125.Pp 2126The following four varieties of parameter expansion provide for substring 2127processing. 2128In each case, pattern matching notation (see 2129.Sx Shell Patterns ) , 2130rather than regular expression notation, is used to evaluate the patterns. 2131If parameter is 2132.Dv * 2133or 2134.Dv @ , \" $@ 2135the result of the expansion is unspecified. 2136Enclosing the full parameter expansion string in double quotes does not 2137cause the following four varieties of pattern characters to be quoted, 2138whereas quoting characters within the braces has this effect. 2139.Bl -tag -width aaparameterwordaaaaa 2140.It Li ${ Ns Ar parameter Ns Ic % Ns Ar word Ns Li } 2141.Sy Remove Smallest Suffix Pattern. 2142The 2143.Ar word 2144is expanded to produce a pattern. 2145The parameter expansion then results in 2146.Ar parameter , 2147with the 2148smallest portion of the suffix matched by the pattern deleted. 2149If the 2150.Ar word 2151is to start with a 2152.Sq Li \&% 2153character, it must be quoted. 2154.It Li ${ Ns Ar parameter Ns Ic %% Ns Ar word Ns Li } 2155.Sy Remove Largest Suffix Pattern. 2156The 2157.Ar word 2158is expanded to produce a pattern. 2159The parameter expansion then results in 2160.Ar parameter , 2161with the largest 2162portion of the suffix matched by the pattern deleted. 2163The 2164.Dq Ic %% 2165pattern operator only produces different results from the 2166.Dq Ic \&% 2167operator when the pattern contains at least one unquoted 2168.Sq Li \&* . 2169.It Li ${ Ns Ar parameter Ns Ic \&# Ns Ar word Ns Li } 2170.Sy Remove Smallest Prefix Pattern. 2171The 2172.Ar word 2173is expanded to produce a pattern. 2174The parameter expansion then results in 2175.Ar parameter , 2176with the 2177smallest portion of the prefix matched by the pattern deleted. 2178If the 2179.Ar word 2180is to start with a 2181.Sq Li \&# 2182character, it must be quoted. 2183.It Li ${ Ns Ar parameter Ns Ic \&## Ns Ar word Ns Li } 2184.Sy Remove Largest Prefix Pattern. 2185The 2186.Ar word 2187is expanded to produce a pattern. 2188The parameter expansion then results in 2189.Ar parameter , 2190with the largest 2191portion of the prefix matched by the pattern deleted. 2192This has the same relationship with the 2193.Dq Ic \&# 2194pattern operator as 2195.Dq Ic %% 2196has with 2197.Dq Ic \&% . 2198.El 2199.\" 2200.\" 2201.Ss Command Substitution 2202.\" 2203Command substitution allows the output of a command to be substituted in 2204place of the command (and surrounding syntax). 2205Command substitution occurs when a word contains 2206a command list enclosed as follows: 2207.Pp 2208.Dl Ic $( Ns Ar list Ns Ic \&) 2209.Pp 2210or the older 2211.Pq Dq backquoted 2212version, which is best avoided: 2213.Pp 2214.Dl Ic \&` Ns Ar list Ns Ns Ic \&` 2215.Pp 2216See the section 2217.Sx Complex Commands 2218above for the definition of 2219.Ic list . 2220.Pp 2221The shell expands the command substitution by executing the 2222.Ar list 2223in a sub-shell environment and replacing the command substitution with the 2224standard output of the 2225.Ar list 2226after removing any sequence of one or more 2227.Ao newline Ac Ns s 2228from the end of the substitution. 2229(Embedded 2230.Ao newline Ac Ns s 2231before 2232the end of the output are not removed; however, during field splitting, 2233they may be used to separate fields 2234.Pq "as spaces usually are" 2235depending on the value of 2236.Ev IFS 2237and any quoting that is in effect.) 2238.Pp 2239Note that if a command substitution includes commands 2240to be run in the background, 2241the sub-shell running those commands 2242will only wait for them to complete if an appropriate 2243.Ic wait 2244command is included in the command list. 2245However, the shell in which the result of the command substitution 2246will be used will wait for both the sub-shell to exit and for the 2247file descriptor that was initially standard output for the command 2248substitution sub-shell to be closed. 2249In some circumstances this might not happen until all processes 2250started by the command substitution have finished. 2251.\" While the exit of the sub-shell closes its standard output, 2252.\" any background process left running may still 2253.\" have that file descriptor open. 2254.\" This includes yet another sub-shell which might have been 2255.\" (almost invisibly) created to wait for some other command to complete, 2256.\" and even where the background command has had its 2257.\" standard output redirected or closed, 2258.\" the waiting sub-shell may still have it open. 2259.\" Thus there is no guarantee that the result of a command substitution 2260.\" will be available in the shell which is to use it before all of 2261.\" the commands started by the command substitution have completed, 2262.\" though careful coding can often avoid delays beyond the termination 2263.\" of the command substitution sub-shell. 2264.\" .Pp 2265.\" For example, assuming a script were to contain the following 2266.\" code (which could be done better other ways, attempting 2267.\" this kind of trickery is not recommended): 2268.\" .Bd -literal -offset indent 2269.\" if [ "$( printf "Ready? " >&2; read ans; printf "${ans}"; 2270.\" { sleep 120 >/dev/null && kill $$ >/dev/null 2>&1; }& )" = go ] 2271.\" then 2272.\" printf Working... 2273.\" # more code 2274.\" fi 2275.\" .Ed 2276.\" .Pp 2277.\" the 2278.\" .Dq Working... 2279.\" output will not be printed, and code that follows will never be executed. 2280.\" Nor will anything later in the script 2281.\" .Po 2282.\" unless 2283.\" .Dv SIGTERM 2284.\" is trapped or ignored 2285.\" .Pc . 2286.\" .Pp 2287.\" The intent is to prompt the user, wait for the user to 2288.\" answer, then if the answer was 2289.\" .Dq go 2290.\" do the appropriate work, but set a 2 minute time limit 2291.\" on completing that work. 2292.\" If the work is not done by then, kill the shell doing it. 2293.\" .Pp 2294.\" It will usually not work as written, as while the 2 minute 2295.\" .Sq sleep 2296.\" has its standard output redirected, as does the 2297.\" .Sq kill 2298.\" that follows (which also redirects standard error, 2299.\" so the user would not see an error if the work were 2300.\" completed and there was no parent process left to kill); 2301.\" the sub-shell waiting for the 2302.\" .Sq sleep 2303.\" to finish successfully, so it can start the 2304.\" .Sq kill , 2305.\" does not. 2306.\" It waits, with standard output still open, 2307.\" for the 2 minutes until the sleep is done, 2308.\" even though the kill is not going to need that file descriptor, 2309.\" and there is nothing else which could. 2310.\" The command substitution does not complete until after 2311.\" the kill has executed and the background sub-shell 2312.\" finishes \(en at which time the shell running it is 2313.\" presumably dead. 2314.\" .Pp 2315.\" Rewriting the background sub-shell part of that as 2316.\" .Dl "{ sleep 120 && kill $$ 2>&1; } >/dev/null &" 2317.\" would allow this 2318.\" .Nm 2319.\" to perform as expected, but that is not guaranteed, 2320.\" not all shells would behave as planned. 2321.\" It is advised to avoid starting background processes 2322.\" from within a command substitution. 2323.\" 2324.\" 2325.Ss Arithmetic Expansion 2326.\" 2327Arithmetic expansion provides a mechanism for evaluating an arithmetic 2328expression and substituting its value. 2329The format for arithmetic expansion is as follows: 2330.Pp 2331.Dl Ic $(( Ns Ar expression Ns Ic \&)) 2332.Pp 2333The expression in an arithmetic expansion is treated as if it were in 2334double quotes, except that a double quote character inside the expression 2335is just a normal character (it quotes nothing.) 2336The shell expands all tokens in the expression for parameter expansion, 2337command substitution, and quote removal (the only quoting character is 2338the backslash 2339.Sq \&\e , 2340and only when followed by another 2341.Sq \&\e , 2342a dollar sign 2343.Sq \&$ , 2344a backquote 2345.Sq \&` 2346or a newline.) 2347.Pp 2348Next, the shell evaluates the expanded result as an arithmetic expression 2349and substitutes the calculated value of that expression. 2350.Pp 2351Arithmetic expressions use a syntax similar to that 2352of the C language, and are evaluated using the 2353.Ql intmax_t 2354data type (this is an extension to POSIX, which requires only 2355.Ql long 2356arithmetic.) 2357Shell variables may be referenced by name inside an arithmetic 2358expression, without needing a 2359.Dq \&$ 2360sign. 2361Variables that are not set, or which have an empty (null string) value, 2362used this way evaluate as zero (that is, 2363.Dq x 2364in arithmetic, as an R-Value, is evaluated as 2365.Dq ${x:-0} ) 2366unless the 2367.Nm 2368.Fl u 2369flag is set, in which case a reference to an unset variable is an error. 2370Note that unset variables used in the ${var} form expand to a null 2371string, which might result in syntax errors. 2372Referencing the value of a variable which is not numeric is an error. 2373.Pp 2374All of the C expression operators applicable to integers are supported, 2375and operate as they would in a C expression. 2376Use white space, or parentheses, to disambiguate confusing syntax, 2377otherwise, as in C, the longest sequence of consecutive characters 2378which make a valid token (operator, variable name, or number) is taken 2379to be that token, even if the token designated cannot be used 2380and a different interpretation could produce a successful parse. 2381This means, as an example, that 2382.Dq a+++++b 2383is parsed as the gibberish sequence 2384.Dq "a ++ ++ + b" , 2385rather than as the valid alternative 2386.Dq "a ++ + ++ b" . 2387Similarly, separate the 2388.Sq \&, 2389operator from numbers with white space to avoid the possibility 2390of confusion with the decimal indicator in some locales (though 2391fractional, or floating-point, numbers are not supported in this 2392implementation.) 2393.Pp 2394It should not be necessary to state that the C operators which 2395operate on, or produce, pointer types, are not supported. 2396Those include unary 2397.Dq \&* 2398and 2399.Dq \&& 2400and the struct and array referencing binary operators: 2401.Dq \&. , 2402.Dq \&-> 2403and 2404.Dq \&[ . 2405.\" 2406.\" 2407.Ss Field Splitting 2408.\" 2409After parameter expansion, command substitution, and 2410arithmetic expansion the shell scans the results of 2411expansions and substitutions that did not occur in double quotes, 2412for field splitting and multiple fields can result. 2413.Pp 2414The shell treats each character of the 2415.Ev IFS 2416as a delimiter and uses the delimiters to split the results of parameter 2417expansion and command substitution into fields. 2418.Pp 2419Non-whitespace characters in 2420.Ev IFS 2421are treated strictly as parameter separators. 2422So adjacent non-whitespace 2423.Ev IFS 2424characters will produce empty parameters. 2425On the other hand, any sequence of whitespace 2426characters that occur in 2427.Ev IFS 2428(known as 2429.Ev IFS 2430whitespace) 2431can occur, leading and trailing 2432.Ev IFS 2433whitespace, and any 2434.Ev IFS 2435whitespace surrounding a non whitespace 2436.Ev IFS 2437delimiter, is removed. 2438Any sequence of 2439.Ev IFS 2440whitespace characters without a non-whitespace 2441.Ev IFS 2442delimiter acts as a single field separator. 2443.Pp 2444If 2445.Ev IFS 2446is unset it is assumed to contain space, tab, and newline, 2447all of which are 2448.Ev IFS 2449whitespace characters. 2450If 2451.Ev IFS 2452is set to a null string, there are no delimiters, 2453and no field splitting occurs. 2454.Ss Pathname Expansion (File Name Generation) 2455Unless the 2456.Fl f 2457flag is set, file name generation is performed after word splitting is 2458complete. 2459Each word is viewed as a series of patterns, separated by slashes. 2460The process of expansion replaces the word with the names of all 2461existing files whose names can be formed by replacing each pattern with a 2462string that matches the specified pattern. 2463There are two restrictions on 2464this: first, a pattern cannot match a string containing a slash, and 2465second, a pattern cannot match a string starting with a period unless the 2466first character of the pattern is a period. 2467The next section describes the 2468patterns used for both Pathname Expansion and the 2469.Ic case 2470command. 2471.Ss Shell Patterns 2472A pattern consists of normal characters, which match themselves, 2473and meta-characters. 2474The meta-characters are 2475.Dq \&! , 2476.Dq * , 2477.Dq \&? , 2478and 2479.Dq \&[ . 2480These characters lose their special meanings if they are quoted. 2481When command or variable substitution is performed 2482and the dollar sign or backquotes are not double-quoted, 2483the value of the variable or the output of 2484the command is scanned for these characters and they are turned into 2485meta-characters. 2486.Pp 2487An asterisk 2488.Pq Dq * 2489matches any string of characters. 2490A question mark 2491.Pq Dq \&? 2492matches any single character. 2493A left bracket 2494.Pq Dq \&[ 2495introduces a character class. 2496The end of the character class is indicated by a right bracket 2497.Pq Dq \&] ; 2498if this 2499.Dq \&] 2500is missing then the 2501.Dq \&[ 2502matches a 2503.Dq \&[ 2504rather than introducing a character class. 2505A character class matches any of the characters between the square brackets. 2506A named class of characters (see 2507.Xr wctype 3 ) 2508may be specified by surrounding the name with 2509.Pq Dq [: 2510and 2511.Pq Dq :] . 2512For example, 2513.Pq Dq [[:alpha:]] 2514is a shell pattern that matches a single letter. 2515A range of characters may be specified using a minus sign 2516.Pq Dq \(mi . 2517The character class may be complemented 2518by making an exclamation mark 2519.Pq Dq \&! 2520the first character of the character class. 2521.Pp 2522To include a 2523.Dq \&] 2524in a character class, make it the first character listed (after the 2525.Dq \&! , 2526if any). 2527To include a 2528.Dq \(mi , 2529make it the first (after !) or last character listed. 2530If both 2531.Dq \&] 2532and 2533.Dq \(mi 2534are to be included, the 2535.Dq \&] 2536must be first (after !) 2537and the 2538.Dq \(mi 2539last, in the character class. 2540.\" 2541.\" 2542.Ss Built-ins 2543.\" 2544This section lists the built-in commands which are built in because they 2545need to perform some operation that can't be performed by a separate 2546process. 2547Or just because they traditionally are. 2548In addition to these, there are several other commands that may 2549be built in for efficiency (e.g. 2550.Xr printf 1 , 2551.Xr echo 1 , 2552.Xr test 1 , 2553etc). 2554Most built-in commands will exit with status 2 if used incorrectly 2555(bad options, excess or insufficient number of arguments, etc). 2556Otherwise, unless stated differently, the built-in commands exit with status 0, 2557unless some error occurs, which would be reported to standard error. 2558.Bl -tag -width 5n -compact 2559.Pp 2560.It Ic \&: Op Ar arg ... 2561A null command that returns a 0 (true) exit value. 2562Any arguments or redirects are evaluated just as for any other command, 2563then ignored. 2564.\" 2565.Pp 2566.It Ic \&. Ar file 2567The dot command reads and executes the commands from the specified 2568.Ar file 2569in the current shell environment. 2570The file does not need to be executable and is looked up from the directories 2571listed in the 2572.Ev PATH 2573variable if its name does not contain a directory separator 2574.Pq Sq / . 2575The 2576.Ic return 2577command (see below) 2578can be used for a premature return from the sourced file. 2579.Pp 2580The POSIX standard has been unclear on how loop control keywords (break 2581and continue) behave across a dot command boundary. 2582This implementation allows them to control loops surrounding the dot command, 2583but obviously such behavior should not be relied on. 2584It is now permitted by the standard, but not required. 2585.\" 2586.Pp 2587.It Ic alias Op Ar name Ns Op Li = Ns Ar string ... 2588If 2589.Ar name Ns Li = Ns Ar string 2590is specified, the shell defines the alias 2591.Ar name 2592with value 2593.Ar string . 2594If just 2595.Ar name 2596is specified, the value of the alias 2597.Ar name 2598is printed. 2599With no arguments, the 2600.Ic alias 2601built-in prints the 2602names and values of all defined aliases (see 2603.Ic unalias ) . 2604.\" 2605.Pp 2606.It Ic bg Op Ar job ... 2607Continue the specified jobs (or the current job if no 2608jobs are given) in the background. 2609.\" 2610.Pp 2611.It Ic command Oo Fl pVv Oc Ar command Op Ar arg ... 2612Execute the specified command but ignore shell functions when searching 2613for it. 2614(This is useful when you 2615have a shell function with the same name as a command.) 2616.Bl -tag -width 5n 2617.It Fl p 2618search for command using a 2619.Ev PATH 2620that guarantees to find all the standard utilities, 2621but not necessarily any others. 2622.It Fl V 2623Do not execute the 2624.Ar command 2625but search for the 2626.Ar command 2627and print the resolution of the command search. 2628This is the same as the 2629.Ic type 2630built-in. 2631.It Fl v 2632Do not execute the 2633.Ar command 2634but search for the 2635.Ar command 2636and print the absolute pathname of utilities, 2637the name for built-ins or the expansion of aliases. 2638.El 2639.\" 2640.Pp 2641.It Ic cd Oo Fl Pe Oc Op Ar directory Op Ar replace 2642Switch to the specified directory (default 2643.Ev $HOME ) . 2644If 2645.Ar replace 2646is specified, then the new directory name is generated by replacing 2647the first occurrence of the string 2648.Ar directory 2649in the current working directory name with 2650.Ar replace . 2651Otherwise if 2652.Ar directory 2653is 2654.Sq Li - , 2655then the current working directory is changed to the previous current 2656working directory as set in 2657.Ev OLDPWD . 2658Otherwise if an entry for 2659.Ev CDPATH 2660appears in the environment of the 2661.Ic cd 2662command or the shell variable 2663.Ev CDPATH 2664is set and the 2665.Ar directory 2666name does not begin with a slash, 2667and its first (or only) component isn't dot or dot dot, 2668then the directories listed in 2669.Ev CDPATH 2670will be searched for the specified 2671.Ar directory . 2672The format of 2673.Ev CDPATH 2674is the same as that of 2675.Ev PATH . 2676.Pp 2677The 2678.Fl P 2679option 2680(which is the unalterable default in this 2681.Nm ) 2682instructs the shell to 2683change to the directory specified (or determined) 2684and if successful 2685update 2686.Ev PWD 2687with the new physical directory path. 2688That is the path name, not traversing any symbolic links, 2689of the altered working directory of the shell. 2690.Pp 2691The 2692.Fl e 2693option alters the interpretation of the exit status. 2694.Ic cd 2695will exit with status 0 if successful. 2696If the directory was successfully changed, but 2697.Ev PWD 2698was unable to be updated, 2699.Ic cd 2700will exit with status 1 if the 2701.Fl e 2702option was given, and status 0 otherwise. 2703Upon any other error, 2704including usage errors, 2705and failing to successfully change directory, 2706.Ic cd 2707will exit with status 2. 2708.Pp 2709When the directory changes, 2710and 2711.Ev PWD 2712is updated, the variable 2713.Ev OLDPWD 2714is set to the working directory 2715.Po \&$ Ns Ev PWD Ns Pc 2716as it was before the change. 2717.Pp 2718Some shells also support a 2719.Fl L 2720option, which instructs the shell to update 2721.Ev PWD 2722with the logical path using string manipulation, 2723and then to change the current directory accordingly. 2724This is not supported. 2725.Pp 2726In an interactive shell, or if the 2727.Cm posix 2728option is set, the 2729.Ic cd 2730command will print out the name of the 2731directory that it actually switched to; 2732.Po that is, the pathname passed to the successful 2733.Xr chdir 2 2734.No system call Pc 2735if this is different from the name 2736that the user gave, 2737or if the 2738.Cm cdprint 2739option is set. 2740The destination may be different because 2741a non-empty element of the 2742.Ev CDPATH 2743mechanism was used, 2744.\" or because a symbolic link was crossed. XXX Definitively not (not even -L) 2745or because the 2746.Ar replace 2747argument was used, 2748or because the 2749.Ar directory 2750parameter was specified as 2751.Dq \&\- . 2752.\" 2753.Pp 2754.It Ic eval Ar string ... 2755Concatenate all the 2756.Ar string 2757arguments with intervening spaces. 2758Then parse and execute the resulting command. 2759The exit status from 2760.Ic eval 2761is the exit status of the command executed, or 0 if there was none. 2762.\" 2763.Pp 2764.It Ic exec Op Ar command Op Ar arg ... 2765Unless 2766.Ar command 2767is omitted, the shell process is replaced with the 2768specified program (which must be a real program, not a shell built-in or 2769function). 2770Any redirections on the 2771.Ic exec 2772command are marked as permanent, so that they are not undone when the 2773.Ic exec 2774command finishes, which only happens if no 2775.Ar command 2776was given. 2777.Pp 2778When the 2779.Cm posix 2780option is not set, 2781file descriptors created via such redirections, 2782when no 2783.Ar command 2784is present, 2785are marked close-on-exec 2786(see 2787.Xr open 2 2788.Dv O_CLOEXEC 2789or 2790.Xr fcntl 2 2791.Dv F_SETFD / 2792.Dv FD_CLOEXEC ) , 2793unless the descriptors refer to the standard input, 2794output, or error (file descriptors 0, 1, 2). 2795Traditionally Bourne-like shells 2796(except 2797.Xr ksh 1 2798and its close relatives), 2799made those file descriptors available to exec'ed processes. 2800To be assured the close-on-exec setting is off, 2801redirect the descriptor to (or from) itself, 2802either when invoking a command for which the descriptor is wanted open, 2803or by using 2804.Ic exec 2805.Po perhaps the same 2806.Ic exec 2807.No as opened it, after the open Pc 2808to leave the descriptor open in the shell 2809and also pass it to all commands invoked subsequently. 2810Alternatively, see the 2811.Ic fdflags 2812built-in command below, which can set, or clear, this, and other, 2813file descriptor flags. 2814.Pp 2815If there is a usage, or redirection, error, 2816.Ic exec 2817will not exit from an interactive shell, 2818but will restore all modified file descriptors 2819to the state they had before the 2820.Ic exec 2821command was issued. 2822But note that side effects of any redirections that 2823succeeded, such as creating or truncating files, cannot 2824be reversed. 2825However if a 2826.Ar command 2827cannot be executed for any reason, even an 2828interactive shell will exit. 2829Non-interactive shells will exit on any error, 2830as 2831.Ic exec 2832is a special built-in utility. 2833.\" 2834.Pp 2835.It Ic exit Op Ar exitstatus 2836Terminate the shell process. 2837If 2838.Ar exitstatus 2839is given it is used as the exit status of the shell; otherwise the 2840exit status of the preceding command (the current value of $?) is used. 2841.\" 2842.Pp 2843.It Ic export Oo Fl nx Oc Ar name Ns Oo =value Oc ... 2844.It Ic export Oo Fl x Oc Oo Fl p Oo Ar name ... Oc Oc 2845.It Ic export Fl q Oo Fl x Oc Ar name ... 2846With no options, 2847but one or more names, 2848the specified names are exported so that they will appear in the 2849environment of subsequent commands. 2850With 2851.Fl n 2852the specified names are un-exported. 2853Variables can also be un-exported using the 2854.Ic unset 2855built in command. 2856With 2857.Fl x 2858.Pq exclude 2859the specified names are marked not to be exported, 2860and any that had been exported, will be un-exported. 2861Later attempts to export the variable will be refused. 2862Note this does not prevent explicitly exporting a variable 2863to a single command, script or function by preceding that 2864command invocation by a variable assignment to that variable, 2865provided the variable is not also read-only. 2866That is 2867.Bd -literal -offset indent 2868export -x FOO # FOO will now not be able to be exported 2869export FOO # this command will fail (non-fatally) 2870.Ed 2871But with 2872.Bd -literal -offset indent -compact 2873FOO=some_value my_command 2874.Ed 2875.Nm 2876still passes the value 2877.Pq Li FOO=some_value 2878to 2879.Li my_command 2880through the environment. 2881.Pp 2882The shell allows the value of a variable to be set at the 2883same time it is exported (or unexported, etc) by writing 2884.Pp 2885.Dl export [-nx] name=value 2886.Pp 2887Note that in such a usage, the 2888.Dq name=value 2889argument often needs to be quoted, 2890more often than is required of an assignment statement, 2891as, like with any other command, the command name and 2892arguments are all subject to the various expansions, 2893including filename expansion and field splitting, 2894before the 2895.Ic export 2896command is invoked. 2897With the default value for 2898.Dv IFS : 2899.Bd -unfilled -offset indent -compact 2900X='a b c' 2901export Y=$X 2902.Ed 2903the command invoked would be 2904.Dl "export Y=a b c" 2905exporting 2906.Dv Y , 2907with the value 2908.Dq a 2909and also exporting the variables named 2910.Dq b 2911and 2912.Dq c , 2913which is probably not as intended. 2914.Pp 2915With no arguments the export command lists the names of all 2916set exported variables, 2917or if 2918.Fl x 2919was given, all set variables marked not for export. 2920With the 2921.Fl p 2922option specified, the output will be formatted suitably for 2923non-interactive use, and unset variables are included. 2924When 2925.Fl p 2926is given, variable names, but not values, may also be 2927given, in which case output is limited to the variables named. 2928.Pp 2929With 2930.Fl q 2931and a list of variable names, the 2932.Ic export 2933command will exit with status 0 if all the named 2934variables have been marked for export, or 1 if 2935any are not so marked. 2936If 2937.Fl x 2938is also given, 2939the test is instead for variables marked not to be exported. 2940.Pp 2941Other than with 2942.Fl q , 2943the 2944.Ic export 2945built-in exits with status 0, 2946unless an attempt is made to export a variable which has 2947been marked as unavailable for export, 2948in which cases it exits with status 1. 2949In all cases if 2950an invalid option, or option combination, is given, 2951or an invalid variable name is present, 2952.Ic export 2953will write a message to the standard error output, 2954and exit with a non-zero status. 2955A non-interactive shell will terminate. 2956.Pp 2957Note that there is no restriction upon exporting, 2958or un-exporting, read-only variables. 2959The no-export flag can be reset by unsetting the variable 2960and creating it again \(en provided the variable is not also read-only. 2961.\" 2962.Pp 2963.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last 2964.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last 2965.It Ic fc Fl s Oo Ar old=new Oc Op Ar first 2966.It Ic fc Fl z 2967.Pp 2968The 2969.Ic fc 2970built-in lists, or edits and re-executes, commands previously entered 2971to an interactive shell. 2972.Bl -tag -width 5n 2973.It Fl e Ar editor 2974Use the editor named by 2975.Ar editor 2976to edit the commands. 2977The 2978.Ar editor 2979string is a command name, subject to search via the 2980.Ev PATH 2981variable. 2982The value in the 2983.Ev FCEDIT 2984variable is used as a default when 2985.Fl e 2986is not specified. 2987If 2988.Ev FCEDIT 2989is null or unset, the value of the 2990.Ev EDITOR 2991variable is used. 2992If 2993.Ev EDITOR 2994is null or unset, 2995.Xr ed 1 2996is used as the editor. 2997.It Fl l No (ell) 2998List the commands rather than invoking an editor on them. 2999The commands are written in the sequence indicated by 3000the first and last operands, as affected by 3001.Fl r , 3002with each command preceded by the command number. 3003.It Fl n 3004Suppress command numbers when listing with 3005.Fl l . 3006.It Fl r 3007Reverse the order of the commands listed (with 3008.Fl l ) 3009or edited (with neither 3010.Fl l 3011nor 3012.Fl s ) . 3013.It Fl s 3014Re-execute the command without invoking an editor. 3015.It Fl z 3016Clear the history buffer. 3017No other options or arguments are permitted. 3018.It Ar first 3019.It Ar last 3020Select the commands to list or edit. 3021The number of previous commands that 3022can be accessed are determined by the value of the 3023.Ev HISTSIZE 3024variable. 3025The value of 3026.Ar first 3027or 3028.Ar last 3029or both are one of the following: 3030.Bl -tag -width 5n 3031.It Oo Cm + Oc Ns Ar number 3032A positive number representing a command number; command numbers can be 3033displayed with the 3034.Fl l 3035option. 3036.It Cm \- Ns Ar number 3037A negative decimal number representing the command that was executed 3038number of commands previously. 3039For example, \-1 is the immediately previous command. 3040.El 3041.It Ar string 3042A string indicating the most recently entered command that begins with 3043that string. 3044If the 3045.Ar old Ns Li = Ns Ar new 3046operand is not also specified with 3047.Fl s , 3048the string form of the first operand cannot contain an embedded equal sign. 3049.El 3050.Pp 3051The following environment variables affect the execution of 3052.Ic fc : 3053.Bl -tag -width HISTSIZE 3054.It Ev FCEDIT 3055Name of the editor to use. 3056If 3057.Ev FCEDIT 3058is not set, 3059.Ev EDITOR 3060is used, if set. 3061If neither is used the 3062.Ic ed 3063utility is used. 3064.It Ev HISTSIZE 3065The number of previous commands that are accessible. 3066.El 3067.\" 3068.Pp 3069.It Ic fg Op Ar job 3070Move the specified job or the current job to the foreground. 3071A foreground job can interact with the user via standard input, 3072and receive signals from the terminal. 3073.\" 3074.Pp 3075.It Ic fdflags Oo Fl v Oc Op Ar fd ... 3076.It Ic fdflags Oo Fl v Oc Fl s Ar flags fd Op ... 3077Get or set file descriptor flags. 3078The 3079.Fl v 3080argument enables verbose printing, printing flags that are also off, and 3081the flags of the file descriptor being set after setting. 3082The 3083.Fl s 3084flag interprets the 3085.Ar flags 3086argument as a comma separated list of file descriptor flags, each preceded 3087with a 3088.Dq \(pl 3089or a 3090.Dq \(mi 3091indicating to set or clear the respective flag. 3092Valid flags are: 3093.Cm append , 3094.Cm async , 3095.Cm sync , 3096.Cm nonblock , 3097.Cm fsync , 3098.Cm dsync , 3099.Cm rsync , 3100.Cm direct , 3101.Cm nosigpipe , 3102and 3103.Cm cloexec . 3104Unique abbreviations of these names, of at least 2 characters, 3105may be used on input. 3106It is not permitted to set 3107.Cm cloexec 3108on file descriptors 0, 1, or 2 3109.Pq standard input , standard output , and standard error . 3110See 3111.Xr fcntl 2 3112and 3113.Xr open 2 3114for more information. 3115.\" 3116.Pp 3117.It Ic getopts Ar optstring var 3118The POSIX 3119.Ic getopts 3120command, not to be confused with the 3121Bell Labs\[en]derived 3122.Xr getopt 1 . 3123.Pp 3124The first argument should be a series of letters, each of which may be 3125optionally followed by a colon (:) to indicate that the option requires an 3126argument. 3127The variable specified is set to the parsed option. 3128.Pp 3129The 3130.Ic getopts 3131command deprecates the older 3132.Xr getopt 1 3133utility due to its handling of arguments containing whitespace. 3134.Pp 3135The 3136.Ic getopts 3137built-in may be used to obtain options and their arguments 3138from a list of parameters. 3139When invoked, 3140.Ic getopts 3141places the value of the next option from the option string in the list in 3142the shell variable specified by 3143.Ar var 3144and its index in the shell variable 3145.Ev OPTIND . 3146When the shell is invoked, 3147.Ev OPTIND 3148is initialized to 1. 3149For each option that requires an argument, the 3150.Ic getopts 3151built-in will place it in the shell variable 3152.Ev OPTARG . 3153If an option is not allowed for in the 3154.Ar optstring , 3155then 3156.Ev OPTARG 3157will be unset. 3158.Pp 3159.Ar optstring 3160is a string of recognized option letters (see 3161.Xr getopt 3 ) . 3162If a letter is followed by a colon (:), the option is expected to have an 3163argument which may or may not be separated from the option by whitespace. 3164If an option character is not found where expected, 3165.Ic getopts 3166will set the variable 3167.Ar var 3168to 3169.Sq Li \&? ; 3170.Ic getopts 3171will then unset 3172.Ev OPTARG 3173and write an error to standard error. 3174.Pp 3175By specifying a colon (:) as the first character of 3176.Ar optstring , 3177the error handling behavior changes: 3178no errors will be written to standard error; 3179unknown option characters will set 3180.Ar var 3181to 3182.Sq Li \&? 3183and set 3184.Ev OPTARG 3185to the unknown option character (instead of unset 3186.Ev OPTARG Ns ); 3187and missing option arguments will set 3188.Ar var 3189to 3190.Sq Li \&: 3191and set 3192.Ev OPTARG 3193to the option character with the missing argument. 3194.Pp 3195A nonzero value is returned when the last option is reached. 3196If there are no remaining arguments, 3197.Ic getopts 3198will set 3199.Ar var 3200to the special option, 3201.Dq Li \-\- , 3202otherwise, it will set 3203.Ar var 3204to 3205.Sq Li \&? . 3206.Pp 3207The following code fragment shows how one might process the arguments 3208for a command that can take the options 3209.Fl a 3210and 3211.Fl b , 3212and the option 3213.Fl c , 3214which requires an argument. 3215.Bd -literal -offset indent 3216while getopts abc: f 3217do 3218 case $f in 3219 a | b) flag=$f;; 3220 c) carg=$OPTARG;; 3221 \e?) echo $USAGE; exit 1;; 3222 esac 3223done 3224shift $((OPTIND - 1)) 3225.Ed 3226.Pp 3227This code will accept any of the following as equivalent: 3228.Bd -literal -offset indent 3229cmd \-acarg file file 3230cmd \-a \-c arg file file 3231cmd \-carg -a file file 3232cmd \-a \-carg \-\- file file 3233.Ed 3234.\" 3235.Pp 3236.It Ic hash Oo Fl befqrsuv Oc Op Ar command ... 3237The shell maintains a hash table which remembers the 3238locations and types of commands. 3239With the 3240.Fl r 3241option given, 3242the 3243.Ic hash 3244command begins by clearing all commands, 3245except special built-in commands and functions, 3246from this table. 3247Commands, other than functions, are added to the table as 3248described below, or as they are encountered 3249through normal execution, or for functions, 3250when they are defined. 3251Functions are removed with the 3252.Ic unset 3253built-in command. 3254Special built-in commands are added at shell startup, 3255and never removed. 3256Utilities can also be removed when 3257.Ev PATH 3258is altered. 3259.Pp 3260With no 3261.Ar command 3262arguments 3263the 3264.Ic hash 3265command then prints out the contents of this table. 3266Note that this is a hash table, the order of the 3267contents is unpredictable, and meaningless. 3268.Pp 3269The 3270.Fl b , 3271.Fl f , 3272.Fl s , 3273and 3274.Fl u 3275options control which entries are printed. 3276With 3277.Fl f 3278functions are printed; with 3279.Fl b 3280or 3281.Fl s 3282regular, or special, built-in commands are listed; 3283and with 3284.Fl u 3285normal utilities (those commands found in the filesystem 3286by searching 3287.Ev PATH ) 3288are printed. 3289For compatibility with some older versions of the 3290.Ic hash 3291command, 3292.Fl c 3293is accepted as an alternative of 3294.Fl u . 3295.Pp 3296Some normal command entries which have not been verified since the last 3297.Ic cd 3298command are marked with an asterisk; it is possible for these entries 3299to be invalid. 3300.Pp 3301The 3302.Fl v 3303option causes more verbose output to be included, indicating the 3304type of the command, rather than simply its name. 3305For functions, the body of the function is included. 3306.Pp 3307If none of the above options is given, the default is to 3308show normal commands only. 3309With 3310.Fl v 3311and no other options, the whole table (all types) will be shown. 3312.Pp 3313Unless there is an error writing the output, the 3314.Ic hash 3315command will exit with status 0 in this usage. 3316.Pp 3317With 3318.Ar command 3319arguments, the 3320.Ic hash 3321command removes the specified commands from the hash table (unless 3322they are functions or special built-in commands) and then locates 3323and reinstalls them. 3324With the 3325.Fl v 3326option, 3327.Ic hash 3328prints the locations of the commands as it finds them. 3329The 3330.Fl bfsu 3331options control which types of commands will be affected. 3332If any of those options is given, and a command found to 3333already be in the hash table is not one of the designated types, 3334that entry, and the 3335.Ar command 3336argument, will simply be silently skipped. 3337If none of those flags is given, any command type can be affected. 3338.Pp 3339If a 3340.Ar command 3341is not located, then unless 3342.Fl q 3343was given, a 3344.Dq not found 3345error message will be printed. 3346.Pp 3347The 3348.Fl e 3349option implies 3350.Fl q 3351if that option was not given, and also causes the exit status 3352of the 3353.Ic hash 3354command to ignore the unfound 3355.Ar command . 3356Otherwise if any 3357.Ar command 3358is not found, the 3359.Ic hash 3360command will exit with status 1. 3361.Pp 3362To allow a method to permit backwards compatibility with the way 3363that the 3364.Ic hash 3365command worked before 3366.Nx 10.0 , 3367if both the 3368.Fl e 3369and 3370.Fl q 3371options are given, then an error message will be printed about 3372.Ar command Ns s 3373unable to be found, but the exit status will remain 0. 3374This is not considered useful. 3375.\" 3376.Pp 3377.It Ic inputrc Ar file 3378Read the 3379.Ar file 3380to set key bindings as defined by 3381.Xr editrc 5 . 3382.\" 3383.Pp 3384.It Ic jobid Oo Fl g Ns \&| Ns Fl j Ns \&| Ns Fl p Oc Op Ar job 3385With no flags, print the process identifiers of the processes in the job. 3386If the 3387.Ar job 3388argument is omitted, the current job is used. 3389Any of the ways to select a job may be used for 3390.Ar job , 3391including the 3392.Sq Li \&% 3393forms, or the process id of the job leader 3394.Po 3395.Dq Li \&$! 3396if the job was created in the background. 3397.Pc 3398.Pp 3399If one of the flags is given, then instead of the list of 3400process identifiers, the 3401.Ic jobid 3402command prints: 3403.Bl -tag -width ".Fl g" 3404.It Fl g 3405the process group, if one was created for this job, 3406or nothing otherwise (the job is in the same process 3407group as the shell.) 3408.It Fl j 3409the job identifier (using 3410.Dq Li \&% Ns Ar n 3411notation, where 3412.Ar n 3413is a number) is printed. 3414.It Fl p 3415only the process id of the process group leader is printed. 3416.El 3417.Pp 3418These flags are mutually exclusive. 3419.Pp 3420.Ic jobid 3421exits with status 2 if there is an argument error, 3422status 1, if with 3423.Fl g 3424the job had no separate process group, 3425or with 3426.Fl p 3427there is no process group leader (should not happen), 3428and otherwise exits with status 0. 3429.\" 3430.Pp 3431.It Ic jobs Oo Fl l Ns \&| Ns Fl p Oc Op Ar job ... 3432.It Ic jobs Fl Z Op Ar title 3433Without 3434.Ar job 3435arguments, 3436this command lists out all the background processes 3437which are children of the current shell process. 3438With 3439.Ar job 3440arguments, the listed jobs are shown instead. 3441Without flags, the output contains the job 3442identifier (see 3443.Sx Job Control 3444below), an indicator character if the job is the current or previous job, 3445the current status of the job (running, suspended, or terminated successfully, 3446unsuccessfully, or by a signal) 3447and a (usually abbreviated) command string. 3448.Pp 3449With the 3450.Fl l 3451flag the output is in a longer form, with the process identifiers 3452of each process (run from the top level, as in a pipeline), and the 3453status of each process, rather than the job status. 3454.Pp 3455With the 3456.Fl p 3457flag, the output contains only the process identifier of the lead 3458process (which is also the process group identifier). 3459Note that this is not necessarily the same process identifier as 3460reported in the special parameter 3461.Dv \&! 3462when a background job is started. 3463.Pp 3464With the 3465.Fl Z 3466flag, the process command line is set using 3467.Xr setproctitle 3 . 3468If 3469.Ar title 3470is omitted or a null string, 3471.Xr setproctitle 3 3472is called with a 3473.Dv NULL 3474format. 3475.Pp 3476These options are mutually exclusive, the last specified is used. 3477.Pp 3478In an interactive shell, each job shown as completed in the output 3479from the jobs command is implicitly waited for, and is removed from 3480the jobs table, never to be seen again. 3481In an interactive shell, when a background job terminates, the 3482.Ic jobs 3483command (with that job as an argument) is implicitly run just 3484before outputting the next PS1 command prompt, after the job 3485terminated. 3486This indicates that the job finished, shows its status, 3487and cleans up the job table entry for that job. 3488Non-interactive shells need to execute 3489.Ic wait 3490commands to clean up terminated background jobs. 3491.\" 3492.Pp 3493.It Ic local Oo Fl INx Oc Oo Ar variable | \- Oc ... 3494Define local variables for a function. 3495Local variables have their attributes, and values, 3496as they were before the 3497.Ic local 3498declaration, restored when the function terminates. 3499.Pp 3500With the 3501.Fl N 3502flag, variables made local, are unset initially inside 3503the function. 3504Unless the 3505.Fl x 3506flag is also given, such variables are also unexported. 3507The 3508.Fl I 3509flag, which is the default in this shell, causes 3510the initial value and exported attribute 3511of local variables 3512to be inherited from the variable 3513with the same name in the surrounding 3514scope, if there is one. 3515If there is not, the variable is initially unset, 3516and not exported. 3517The 3518.Fl N 3519and 3520.Fl I 3521flags are mutually exclusive, if both are given, the last specified applies. 3522The read-only and unexportable attributes are always 3523inherited, if a variable with the same name already exists. 3524.Pp 3525The 3526.Fl x 3527flag (lower case) causes the local variable to be exported, 3528while the function runs, unless it has the unexportable attribute. 3529This can also be accomplished by using the 3530.Ic export 3531command, giving the same 3532.Ar variable 3533names, after the 3534.Ic local 3535command. 3536.Pp 3537Making an existing read-only variable local is possible, 3538but pointless. 3539If an attempt is made to assign an initial value to such 3540a variable, the 3541.Ic local 3542command fails, as does any later attempted assignment. 3543If the 3544.Ic readonly 3545command is applied to a variable that has been declared local, 3546the variable cannot be (further) modified within the function, 3547or any other functions it calls, however when the function returns, 3548the previous status (and value) of the variable is returned. 3549.Pp 3550Values may be given to local variables on the 3551.Ic local 3552command line in a similar fashion as used for 3553.Ic export 3554and 3555.Ic readonly . 3556These values are assigned immediately after the initialization 3557described above. 3558Note that any variable references on the command line will have 3559been expanded before 3560.Ic local 3561is executed, so expressions like 3562.Bd -unfilled -offset indent 3563local -N X="${X}" 3564.Ed 3565.Pp 3566are well defined, first $X is expanded, and then the command run is 3567.Dl "local -N X='old-value-of-X'" 3568See the description of the 3569.Ic export 3570built-in command for notes on why quoting the value is required. 3571.Pp 3572After arranging to preserve the old value and attributes, of 3573.Dv X 3574.Dq ( old-value-of X ) 3575.Ic local 3576unsets 3577.Dv X , 3578unexports it, and then assigns the 3579.Dq old-value-of-X 3580to 3581.Ev X . 3582.Pp 3583The shell uses dynamic scoping, so that if you make the variable 3584.Dv x 3585local to 3586function 3587.Dv f , 3588which then calls function 3589.Dv g , 3590references to the variable 3591.Dv x 3592made inside 3593.Dv g 3594will refer to the variable 3595.Dv x 3596declared inside 3597.Dv f , 3598not to the global variable named 3599.Dv x . 3600.Pp 3601Another way to view this, is as if the shell just has one flat, global, 3602namespace, in which all variables exist. 3603The 3604.Ic local 3605command conceptually copies the variable(s) named to unnamed temporary 3606variables, and when the function ends, copies them back again. 3607All references to the variables reference the same global variables, 3608but while the function is active, after the 3609.Ic local 3610command has run, the values and attributes of the variables might 3611be altered, and later, when the function completes, be restored. 3612.Pp 3613Note that the positional parameters 3614.Dv 1 , \" $1 3615.Dv 2 , \" $2 3616\&... (see 3617.Sx Positional Parameters ) , 3618and the special parameters 3619.Dv \&# , \" $# 3620.Dv \&* \" $* 3621and 3622.Dv \&@ \" $@ 3623(see 3624.Sx Special Parameters ) , 3625are always made local in all functions, and are reset inside the 3626function to represent the options and arguments passed to the function. 3627Note that 3628.Li $0 3629however retains the value it had outside the function, 3630as do all the other special parameters. 3631.Pp 3632The only special parameter that can optionally be made local is 3633.Dq Li \- . 3634Making 3635.Dq Li \- 3636local causes any shell options that are changed via the set command inside the 3637function to be restored to their original values when the function 3638returns. 3639If 3640.Fl X 3641option is altered after 3642.Dq Li \- 3643has been made local, then when the function returns, the previous 3644destination for 3645.Cm xtrace 3646output (as of the time of the 3647.Ic local 3648command) will also be restored. 3649If any of the shell's magic variables 3650(those which return a value which may vary without 3651the variable being explicitly altered, 3652e.g.: 3653.Dv SECONDS 3654or 3655.Dv HOSTNAME ) 3656are made local in a function, 3657they will lose their special properties when set 3658within the function, including by the 3659.Ic local 3660command itself 3661(if not to be set in the function, there is little point 3662in making a variable local) 3663but those properties will be restored when the function returns. 3664.Pp 3665It is an error to use 3666.Ic local 3667outside the scope of a function definition. 3668When used inside a function, it exits with status 0, 3669unless an undefined option is used, or an attempt is made to 3670assign a value to a read-only variable. 3671.Pp 3672Note that either 3673.Fl I 3674or 3675.Fl N 3676should always be used, or variables made local should always 3677be given a value, or explicitly unset, as the default behavior 3678(inheriting the earlier value, or starting unset after 3679.Ic local ) 3680differs amongst shell implementations. 3681Using 3682.Dq Li local \&\- 3683is an extension not implemented by most shells. 3684.Pp 3685See the section 3686.Sx Using Dv LINENO 3687below for details of the effects of making the variable 3688.Dv LINENO 3689local. 3690.\" 3691.Pp 3692.It Ic pwd Op Fl \&LP 3693Print the current directory. 3694If 3695.Fl L 3696is specified the cached value (initially set from 3697.Ev PWD ) 3698is checked to see if it refers to the current directory; if it does 3699the value is printed. 3700Otherwise the current directory name is found using 3701.Xr getcwd 3 . 3702.Pp 3703The default is 3704.Ic pwd 3705.Fl L , 3706but note that the built-in 3707.Ic cd 3708command doesn't support the 3709.Fl L 3710option and will cache (almost) the absolute path. 3711If 3712.Ic cd 3713is changed (as unlikely as that is), 3714.Ic pwd 3715may be changed to default to 3716.Ic pwd 3717.Fl P . 3718.Pp 3719If the current directory is renamed and replaced by a symlink to the 3720same directory, or the initial 3721.Ev PWD 3722value followed a symbolic link, then the cached value may not 3723be the absolute path. 3724.Pp 3725The built-in command may differ from the program of the same name because 3726the program will use 3727.Ev PWD 3728and the built-in uses a separately cached value. 3729.\" 3730.Pp 3731.It Ic read Oo Fl br Oc Oo Fl d Ar delim Oc Oo Fl n Ar max Oc Oo Fl p Ar prompt Oc Ar variable Op Ar ... 3732.Pp 3733The 3734.Ic read 3735command reads a record (by default one line) from its standard input, 3736splits that record as if by field splitting, and assigns the results 3737to the named 3738.Ar variable 3739arguments, as detailed below. 3740.Pp 3741The options are: 3742.Bl -tag -width ".Fl ppromptM" 3743.It Fl b 3744Do buffered reads, rather than reading one byte at a time. 3745This option is ignored if reading from a pipe. 3746Use of this option might result in reading more bytes from 3747standard input than the 3748.Ic read 3749utility actually processes, 3750causing some data from standard input to be unavailable 3751to any subsequent utility that expects to obtain them, 3752though this will be avoided wherever possible. 3753.It Fl d Ar delim 3754End the read when the first byte of 3755.Ar delim 3756is obtained from standard input. 3757The default end delimiter is 3758.Aq newline 3759.Pq Sq \en . 3760Specifying 3761.Qq 3762as 3763.Ar delim 3764causes the nul character 3765.Pq Sq \e0 3766to be the end delimiter. 3767If the delimiter is set to 3768.Aq backslash 3769.Pq Sq \&\e 3770then neither line continuation nor escaping are available. 3771The input will end when the first 3772.Aq backslash 3773is read. 3774.It Fl n Ar max 3775.Ic read 3776will read no more than 3777.Ar max 3778bytes from standard input. 3779The default is unlimited. 3780If the end 3781.Ar delim 3782has not been encountered within 3783.Ar max 3784bytes, and EOF has not been reached, 3785.Ic read 3786will act as if the delimiter immediately followed 3787the 3788.Ar max Ns 'th 3789byte, without attempting to obtain it. 3790However, even if the 3791.Fl r 3792option is not given and the final byte actually read 3793were the escape character (not itself escaped), 3794no more bytes will be read, and that escape 3795character would simply be removed as described below. 3796.It Fl p Ar prompt 3797If the standard input is a terminal, then 3798.Ar prompt 3799is written to standard error before the read commences. 3800If more lines of data are required in that case, the 3801normal 3802.Ev PS2 3803prompt is written as each subsequent line is to be obtained. 3804.It Fl r 3805Reduced processing of the input. 3806No escape characters are recognised, 3807and line continuation is not performed. 3808See below. 3809.El 3810.Pp 3811If the read is from a terminal device, 3812and the 3813.Fl p 3814option was given, 3815.Ar prompt 3816is printed on standard error. 3817Then a record, terminated by the first character of 3818.Ar delim 3819if the 3820.Fl d 3821option was given, or a 3822.Aq newline 3823.Pq Sq \en 3824character otherwise, 3825but no longer than 3826.Ar max 3827bytes if the 3828.Fl n 3829option was given, 3830is read from the standard input. 3831If the 3832.Fl b 3833option is not given, no data from standard 3834input beyond the end delimiter, or the 3835.Ar max 3836bytes that may be read, 3837whichever occurs first, 3838are obtained. 3839Any nul characters 3840.Pq Sq \e0 3841encountered in the input stream, 3842other than when being the delimiter if 3843.Fl d Qq 3844was used, 3845are simply ignored, even if escaped (in which case the 3846preceding 3847.Sq \e 3848is also ignored) though these ignored characters are 3849included in the byte count for the purposes of the 3850.Fl n 3851option. 3852.Pp 3853If the 3854.Fl r 3855option was not given, 3856and the two character sequence 3857.Sq \&\e 3858.Sq \en 3859is encountered, 3860those two characters are simply deleted, 3861and provided that 3862.Ar max 3863bytes have not yet been obtained, 3864and the end delimiter has yet to be encountered, 3865more input is obtained, 3866with the first character of the following line 3867placed in the input where the deleted 3868.Sq \e 3869had been. 3870This allows logical lines longer than the maximum line 3871length permitted for text files to be processed. 3872The two removed characters are still counted 3873for the purposes of the 3874.Ar max 3875input limit. 3876.Pp 3877If the 3878.Fl r 3879flag was not given, the 3880.Aq backslash 3881character 3882.Pq Sq \e 3883character is then treated as an escape character, 3884the character following it, if not 3885.Sq \e0 , 3886is always treated as a normal, 3887insignificant, data character, 3888and is never treated as the end delimiter nor as 3889an IFS character for field splitting. 3890.Pp 3891After field splitting has completed, 3892but before data has been 3893assigned to any variables, 3894all escape characters are removed. 3895Note that the two character sequence 3896.Sq \&\e 3897.Sq \&\e 3898can be used to enter the escape character as data, 3899the first acts as the escape character, the second 3900becomes just a normal data character. 3901.Pp 3902The ending delimiter, if encountered, and not escaped, 3903is deleted from the record which is then split as described 3904in the field splitting section of the 3905.Sx Word Expansions 3906section above. 3907The pieces (fields) are assigned to the 3908.Ar variable Ns s 3909in order. 3910If there are more pieces than variables, 3911the remaining pieces 3912(along with the characters in 3913.Ev IFS 3914that separated them) are all assigned to the last 3915.Ar variable . 3916If there are more variables than pieces, 3917the remaining variables are assigned the null string. 3918.Pp 3919The 3920.Ic read 3921built-in utility will indicate success (exit status 0) 3922unless EOF, or a read error, 3923is encountered on input, before encountering the delimiter, 3924or having read 3925.Ar max 3926bytes. 3927In this case any data previously read will be assigned to 3928the variables, as if the delimiter had been located at that 3929point, and 3930.Ic read 3931will exit with status 1. 3932If there is a usage error (unknown option, etc) 3933no variables will be altered, 3934.Ic read 3935will issue a diagnostic to standard error, 3936and exit with a status greater than 1. 3937.Pp 3938The 3939.Fl b 3940and 3941.Fl n 3942options are not available in SMALL shells. 3943.\" 3944.Pp 3945.It Ic readonly Ar name Ns Oo =value Oc ... 3946.It Ic readonly Oo Fl p Oo Ar name ... Oc Oc 3947.It Ic readonly Fl q Ar name ... 3948With no options, 3949the specified names are marked as read only, so that they cannot be 3950subsequently modified or unset. 3951The shell allows the value of a variable 3952to be set at the same time it is marked read only by writing 3953.Pp 3954.Dl readonly name=value 3955.Pp 3956where the value often needs to be quoted, as explained for the 3957.Ic export 3958command. 3959.Pp 3960With no arguments the 3961.Ic readonly 3962command lists the names of all set read only variables. 3963With the 3964.Fl p 3965option specified, 3966the output will be formatted suitably for non-interactive use, 3967and unset variables are included. 3968When the 3969.Fl p 3970option is given, 3971a list of variable names (without values) may also be specified, 3972in which case output is limited to the named variables. 3973.Pp 3974With the 3975.Fl q 3976option, the 3977.Ic readonly 3978command tests the read-only status of the variables listed 3979and exits with status 0 if all named variables are read-only, 3980or with status 1 if any are not read-only. 3981.Pp 3982Other than as specified for 3983.Fl q 3984the 3985.Ic readonly 3986command normally exits with status 0. 3987In all cases, if an unknown option, or an invalid option combination, 3988or an invalid variable name, is given; 3989or a variable which was already read-only is attempted to be set; 3990the exit status will not be zero, a diagnostic 3991message will be written to the standard error output, 3992and a non-interactive shell will terminate. 3993.\" 3994.Pp 3995.It Ic return Op Ar n 3996Stop executing the current function or a dot command with return value of 3997.Ar n 3998or the value of the last executed command, if not specified. 3999For portability, 4000.Ar n 4001should be in the range from 0 to 255. 4002.Pp 4003The POSIX standard says that the results of 4004.Ic return 4005outside a function or a dot command are unspecified. 4006This implementation treats such a return as a no-op with a return value of 0 4007(success, true). 4008Use the 4009.Ic exit 4010command instead, if you want to return from a script or exit 4011your shell. 4012.\" 4013.Pp 4014.It Ic set 4015.It Ic set No { Fl o | Cm +o No } 4016.It Ic set No { Fl options | Cm +options | Fl o Ar opt | Cm +o Ar opt } ... Oo Cm \-\|\- Oc Oo Ar arg ... Oc 4017.It Ic set \-\|\- Oo Ar arg ... Oc 4018.Pp 4019The 4020.Ic set 4021command performs four different functions. 4022.Pp 4023With no arguments, 4024.Ic set 4025lists the names and values of all set shell variables. 4026.Pp 4027With a single option of either 4028.Dq Fl o 4029or 4030.Dq Cm +o 4031.Ic set 4032outputs the current values of the options. 4033In the 4034.Fl o 4035form, all options are listed, with their current values. 4036In the 4037.Cm +o 4038form, the shell outputs a string that can later be used 4039as a command to reset all options to their current values. 4040.Pp 4041If options are given, 4042.Nm 4043sets the specified option flags, 4044or clears them as described in the 4045.Sx Argument List Processing 4046section. 4047Note that not all options available on the command 4048line are available to the 4049.Ic set 4050built-in command. 4051However, in addition to the options listed there, 4052when the 4053.Dq "option name" 4054.Pq Ar opt 4055given to 4056.Ic set Fl o 4057is 4058.Cm default 4059all of the options are reset to the values they had immediately 4060after 4061.Nm 4062initialization, before any startup scripts, or other input, had been processed. 4063While this may be of use to users or scripts, its primary purpose 4064is for use in the output of 4065.Dq Ic set Cm +o , 4066to avoid that command needing to list every available option. 4067There is no 4068.Cm +o default . 4069.Pp 4070The fourth use of the 4071.Ic set 4072command is to set the values of the shell's 4073positional parameters to the specified arguments. 4074To change the positional 4075parameters with no possibility of changing any options, use 4076.Dq \-\|\- 4077as the first argument to 4078.Ic set . 4079If no following 4080.Ar arg Ns s 4081are present, the 4082.Ic set 4083command 4084will clear all the positional parameters (equivalent to executing 4085.Dq Li shift $# . ) 4086Otherwise the following 4087.Ar arg Ns s 4088become 4089.Li \&$1 , 4090.Li \&$2 , 4091\&..., 4092and 4093.Li \&$# 4094is set to the number of 4095.Ar arg Ns s 4096present. 4097The third and fourth forms may be combined, to set options, 4098and the positional parameters, in one operation. 4099Note that if it is possible that no 4100.Ar arg Ns uments 4101might be present, 4102or if the first 4103.Ar arg 4104might begin with a minus 4105.Pq Sq \&\- 4106then the 4107.Dq \-\|\- 4108is required to distinguish this case from the first 4109and third variants of this command, and an 4110.Ar arg 4111beginning with 4112.Sq \&\- 4113from being an attempt to set options. 4114.\" 4115.Pp 4116.It Ic setvar Ar variable Ar value 4117Assigns 4118.Ar value 4119to 4120.Ar variable . 4121(In general it is better to write 4122.Li variable=value 4123rather than using 4124.Ic setvar . 4125.Ic setvar 4126is intended to be used in 4127functions that assign values to variables whose names are passed as 4128parameters.) 4129.\" 4130.Pp 4131.It Ic shift Op Ar n 4132If 4133.Ar n , 4134which must be a decimal integer, 4135is omitted, 1 is assumed. 4136.Pp 4137If 4138.Ar n 4139is unsigned 4140.Pq or omitted 4141shift the positional parameters 4142.Ar n 4143times. 4144Each 4145.Ic shift 4146sets the value of 4147.Li $1 4148to the previous value of 4149.Li $2 , 4150the value of 4151.Li $2 4152to the previous value of 4153.Li $3 , 4154and so on, decreasing 4155the value of 4156.Li $# 4157by one. 4158The shift count 4159.Pq Ar n 4160must be less than or equal to the number of 4161positional parameters 4162.Pq Dq Li $# 4163before the shift. 4164A shift of 4165.Li $# 4166positions is equivalent to 4167.Dq Li set\ Ns Fl Fl 4168and results in unsetting all of the positional parameters 4169and setting 4170.Li $# 4171to zero. 4172The command 4173.Dq Li shift\ 0 4174does not alter 4175.Li $# 4176or any of the positional parameters. 4177.Pp 4178If 4179.Ar n 4180is negative, then the 4181.Ic shift 4182becomes a clockwise rotation, 4183.Ar \&\-n 4184times. 4185The absolute value of 4186.Ar n 4187must be less than or equal to 4188.Li $# 4189.Pq the number of set positional parameters . 4190Each rotation sets the value of 4191.Li $1 4192to the previous value of 4193.Li ${$#} 4194(if that were valid syntax) \(en the previous last positional parameter, 4195sets 4196.Li $2 4197to the previous value of 4198.Li $1 , 4199the value of 4200.Li $3 4201to the previous value of 4202.Li $2 , 4203and so on, with the new last positional parameter becoming 4204what was previously the penultimate positional parameter. 4205The value of 4206.Li $# 4207is not altered. 4208Shifts of 4209.Li \&\-0 4210and 4211.Li \&\-$# 4212are no-ops. 4213The command sequence: 4214.Dl shift\ \-n;\ shift\ n 4215unsets the final 4216.Ar n 4217positional parameters. 4218.Pp 4219An anti-clockwise rotation of 4220.Ar n 4221places 4222.Pq 0\ <=\ Ns Ar n Ns \ <=\ $# 4223can be achieved using 4224.Dq Li shift\ \-$(($#\ \-\ n)) . 4225The command 4226.Dq Li shift\ \-$(($#\ \-\ 1)) 4227is equivalent to, but much faster than: 4228.Dl set Fl Fl \&\ Ns Do $@ Dc Do $1 Dc ; shift 1 4229.\" 4230.Pp 4231The exit status is 0 if no error occurs, otherwise greater than 0. 4232.Pp 4233.It Ic specialvar Ar variable ... 4234For each 4235.Ar variable 4236name given, 4237if the variable named is one which, 4238in this 4239.Nm , 4240could be treated as a special variable, 4241then cause that 4242.Ar variable 4243to be made special, undoing any effects of an earlier 4244.Ic unset 4245or assignment to the variable. 4246If all 4247.Ar variable Ns s 4248given are recognized special variables in this 4249.Nm 4250the 4251.Ic specialvar 4252command will exit with status 0, otherwise 1. 4253Invalid usage will result in an exit status of 2. 4254.Pp 4255Note that all variables capable of being special are created 4256that way, this command is not required to cause that to happen. 4257However should such a variable be imported from the environment, 4258that will cause (for those special variables so designated) 4259the special effects for that variable to be lost. 4260Consequently, as the contents of the environment cannot be controlled, 4261any script which desires to make use of the properties 4262of most of the special variables should use this command, 4263naming the variables required, 4264to ensure that their special properties are available. 4265.\" 4266.Pp 4267.It Ic suspend Oo Fl fg Oc Oo Fl s Ar sig Oc Oo Ar pid Ns \&| Ns Ar job ... Oc 4268Causes the processes or jobs indicated to be suspended, if possible. 4269If no 4270.Ar pid 4271or 4272.Ar job 4273arguments are given, or if a 4274.Ar pid 4275argument refers to the shell itself, and if the 4276.Ic suspend 4277command is issued in a shell that is not a login shell, 4278has job control enabled, 4279and is not executing in a subshell environment, 4280then the shell will suspend itself. 4281The 4282.Fl f 4283(force) option causes those checks to be ignored, 4284the shell, when instructed to suspend itself with force, 4285will always attempt to do so, which may result in a subshell 4286environment becoming suspended. 4287.Pp 4288The 4289.Fl g 4290option indicates that each 4291.Ar pid 4292argument is to be treated as a process group identifier, 4293or if no targets are given, the current process group of the shell, 4294and that process group will be suspended, instead of just 4295the process identified. 4296This option is implied, for the one agument only, by use of a 4297.Ar job 4298specifier. 4299Note that, unlike other built-in commands, use of a 4300.Ar pid 4301argument causes only that process to be suspended, 4302even if that 4303.Ar pid 4304happens to be the process leader of a job, or another 4305process in a job. 4306.Pp 4307The 4308.Fl s Ar sig 4309option cause the signal 4310.Ar sig 4311to be used to suspend the process, or process group. 4312Only the signals that, by default, cause processes to be 4313suspended 4314.Pq Dv STOP Dv TSTP Dv TTIN No and Dv TTOU 4315are permitted. 4316The default is 4317.Dv SIGTSTP . 4318Note that except when 4319.Dv SIGSTOP 4320is sent, the target process can arrange to catch or 4321ignore the signal, and perhaps not become suspended, 4322if it so desires. 4323Interactive processes that suport job control 4324(eg: shells) 4325generally ignore those signals. 4326.Pp 4327The 4328.Ic suspend 4329command exits with status 0, except if an error occurs, 4330in which case it exits with a status greater than 0. 4331Possible errors include usage errors; 4332attempting to suspend the shell itself, when not 4333permitted and without the 4334.Fl f 4335option; 4336a target process or job not existing; 4337insufficient prvileges to signal the target process or job; 4338and more. 4339It is not an error if the target process decides not to comply 4340with a request to suspend itself. 4341.Pp 4342.It Ic times 4343Prints two lines to standard output. 4344Each line contains two accumulated time values, expressed 4345in minutes and seconds (including fractions of a second.) 4346The first value gives the user time consumed, the second the system time. 4347.Pp 4348The first output line gives the CPU and system times consumed by the 4349shell itself. 4350The second line gives the accumulated times for children of this 4351shell (and their descendants) which have exited, and then been 4352successfully waited for by the relevant parent. 4353See 4354.Xr times 3 4355for more information. 4356.Pp 4357.Ic times 4358has no parameters, and exits with an exit status of 0 unless 4359an attempt is made to give it an option. 4360.\" 4361.Pp 4362.It Ic trap Ar action signal ... 4363.It Ic trap \- 4364.It Ic trap Op Fl l 4365.It Ic trap Fl p Oo Ar signal ... Oc 4366.It Ic trap Fl P Ar signal ... 4367.It Ic trap Ar N signal ... 4368.Pp 4369Cause the shell to parse and execute action when any of the specified 4370signals are received. 4371The signals are specified by signal number or as the name of the signal. 4372If 4373.Ar signal 4374is 4375.Li 0 \" $0 4376or its equivalent, 4377.Li EXIT , 4378the action is executed when the shell exits. 4379The 4380.Ar action 4381may be a null (empty) string, 4382which causes the specified signals to be ignored. 4383With 4384.Ar action 4385set to 4386.Sq Li - 4387the specified signals are set to their default actions. 4388If the first 4389.Ar signal 4390is specified in its numeric form, then 4391.Ar action 4392can be omitted to achieve the same effect. 4393This archaic, 4394but still standard, 4395form should not be relied upon, use the explicit 4396.Sq Li - 4397action. 4398If no signals are specified with an action of 4399.Sq Li - , 4400all signals are reset. 4401.Pp 4402When the shell forks off a sub-shell, it resets trapped (but not ignored) 4403signals to the default action. 4404On non-interactive shells, the 4405.Ic trap 4406command has no effect on signals that were 4407ignored on entry to the shell. 4408On interactive shells, the 4409.Ic trap 4410command will catch or reset signals ignored on entry. 4411.Pp 4412Issuing 4413.Ic trap 4414with option 4415.Fl l 4416will print a list of valid signal names. 4417.Ic trap 4418without any arguments causes it to write a list of signals and their 4419associated non-default actions to the standard output in a format 4420that is suitable as an input to the shell that achieves the same 4421trapping results. 4422With the 4423.Fl p 4424flag, trap prints the same information for the signals specified, 4425or if none are given, for all signals, including those where the 4426action is the default. 4427The 4428.Fl P 4429flag is similar, but prints only the action(s) associated with the 4430named signals, at least (and usually only) one of which must be given. 4431Nothing is printed if the action is the default, 4432an empty line is printed for ignored signals. 4433These variants of the trap command may be executed in a sub-shell 4434.Pq "such as in a command substitution" , 4435provided they appear as the initial sequence of commands in that sub-shell, 4436in which case the state of traps from the parent of that 4437sub-shell is reported. 4438.Pp 4439Examples: 4440.Pp 4441.Dl trap 4442.Pp 4443List trapped signals and their corresponding actions. 4444.Pp 4445.Dl trap -l 4446.Pp 4447Print a list of valid signals. 4448.Pp 4449.Dl trap '' INT QUIT tstp 30 4450.Pp 4451Ignore signals INT QUIT TSTP USR1. 4452.Pp 4453.Dl trap date INT 4454.Pp 4455Run the 4456.Dq date 4457command (print the date) upon receiving signal INT. 4458.Pp 4459.Dl trap HUP INT 4460.Pp 4461Run the 4462.Dq HUP 4463command, or function, upon receiving signal INT. 4464.Pp 4465.Dl Ic eval Qo \&$( trap -P QUIT \&) Qc 4466.Pp 4467Parse and execute the action that would be invoked were a 4468.Dv SIGQUIT 4469received. 4470.Pp 4471.Dl trap 1 2 4472.Pp 4473Reset the actions for signals 1 (HUP) and 2 (INT) to their defaults. 4474.Bd -literal -offset indent 4475traps=$(trap -p) 4476 # more commands ... 4477trap 'action' SIG 4478 # more commands ... 4479eval "$traps" 4480.Ed 4481.Pp 4482Save the trap status, execute commands, changing some traps, 4483and then reset all traps to their values at the start of the sequence. 4484The 4485.Fl p 4486option is required in the first command here, 4487or any signals that were previously 4488untrapped (in their default states) 4489and which were altered during the intermediate code, 4490would not be reset by the final 4491.Ic eval . 4492.\" 4493.Pp 4494.It Ic type Op Ar name ... 4495Interpret each 4496.Ar name 4497as a command and print the resolution of the command search. 4498Possible resolutions are: 4499shell keyword, alias, shell built-in, 4500command, tracked alias and not found. 4501For aliases the alias expansion is 4502printed; for commands and tracked aliases the complete pathname of the 4503command is printed. 4504.\" 4505.Pp 4506.It Ic ulimit Oo Fl H Ns \*(Ba Ns Fl S Oc Op Fl a \*(Ba Fl btfdscmlrpnv Op Ar value 4507Inquire about or set the hard or soft limits on processes or set new 4508limits. 4509The choice between hard limit (which no process is allowed to 4510violate, and which may not be raised once it has been lowered) and soft 4511limit (which causes processes to be signaled but not necessarily killed, 4512and which may be raised) is made with these flags: 4513.Bl -tag -width Fl 4514.It Fl H 4515set or inquire about hard limits 4516.It Fl S 4517set or inquire about soft limits. 4518.El 4519.Pp 4520If neither 4521.Fl H 4522nor 4523.Fl S 4524is specified, the soft limit is displayed or both limits are set. 4525If both are specified, 4526then with 4527.Fl a 4528both are displayed, the soft followed by the hard limit, 4529otherwise for setting, both limits are set, 4530and for interrogating the soft limit is displayed. 4531.Pp 4532The limit to be interrogated or set, then, is chosen by specifying 4533any one of these flags: 4534.Bl -tag -width Fl 4535.It Fl a 4536show all the current limits (it is an error to 4537attempt to set the limits by giving a 4538.Ar value ) 4539.It Fl b 4540the socket buffer size of a process (bytes) 4541.It Fl c 4542the largest core dump size that can be produced 4543(512-byte blocks) 4544.It Fl d 4545the data segment size of a process (kilobytes) 4546.It Fl f 4547the largest file that can be created 4548(512-byte blocks) 4549.It Fl l 4550how much memory a process can lock with 4551.Xr mlock 2 4552(kilobytes) 4553.It Fl m 4554the total physical memory that can be 4555in use by a process (kilobytes) 4556.It Fl n 4557the number of files a process can have open at once 4558.It Fl p 4559the number of processes this user can 4560have at one time 4561.It Fl r 4562the number of threads this user can 4563have at one time 4564.It Fl s 4565the stack size of a process (kilobytes) 4566.It Fl t 4567CPU time (seconds) 4568.It Fl v 4569how large a process address space can be 4570.El 4571.Pp 4572If none of these is specified, it is the limit on file size that is shown 4573or set. 4574If value is specified, the limit is set to that number; otherwise 4575the current limit is displayed. 4576.Pp 4577Limits of an arbitrary process can be displayed or set using the 4578.Xr sysctl 8 4579utility. 4580.\" 4581.Pp 4582.It Ic umask Oo Fl S Oc Op Ar mask 4583Set the value of umask (see 4584.Xr umask 2 ) 4585to the specified octal value. 4586If the argument is omitted, the umask value is printed. 4587With 4588.Fl S 4589a symbolic form is used instead of an octal number. 4590.\" 4591.Pp 4592.It Ic unalias Oo Fl a Oc Op Ar name 4593If 4594.Ar name 4595is specified, the shell removes that alias. 4596If 4597.Fl a 4598is specified, all aliases are removed. 4599.\" 4600.Pp 4601.It Ic unset Oo Fl efvx Oc Ar name ... 4602If 4603.Fl v 4604is specified, the specified variables are unset and unexported. 4605Readonly variables cannot be unset. 4606If 4607.Fl f 4608is specified, the specified functions are undefined. 4609If 4610.Fl e 4611is given, the specified variables are unexported, but otherwise unchanged, 4612alternatively, if 4613.Fl x 4614is given, the exported status of the variable will be retained, 4615even after it is unset. 4616.Pp 4617If no flags are provided 4618.Fl v 4619is assumed. 4620If 4621.Fl f 4622is given with one of the other flags, 4623then the named variables will be unset, or unexported, and functions 4624of the same names will be undefined. 4625The 4626.Fl e 4627and 4628.Fl x 4629flags both imply 4630.Fl v . 4631If 4632.Fl e 4633is given, the 4634.Fl x 4635flag is ignored. 4636.Pp 4637The exit status is 0, unless an attempt was made to unset 4638a readonly variable, in which case the exit status is 1. 4639It is not an error to unset (or undefine) a variable (or function) 4640that is not currently set (or defined.) 4641.\" 4642.Pp 4643.It Ic wait Oo Fl n Oc Oo Fl p Ar var Oc Op Ar job ... 4644Wait for the specified jobs to complete 4645and return the exit status of the last job in the parameter list, 4646or 127 if that job is not a current child of the shell. 4647.Pp 4648If no 4649.Ar job 4650arguments are given, wait for all jobs to 4651complete and then return an exit status of zero 4652(including when there were no jobs, and so nothing exited.) 4653.Pp 4654With the 4655.Fl n 4656option, wait instead for any one of the given 4657.Ar job Ns s, 4658or if none are given, any job, to complete, and 4659return the exit status of that job. 4660If none of the given 4661.Ar job 4662arguments is a current child of the shell, 4663or if no 4664.Ar job 4665arguments are given and the shell has no unwaited for children, 4666then the exit status will be 127. 4667.Pp 4668The 4669.Fl p Ar var 4670option allows the process (or job) identifier of the 4671job for which the exit status is returned to be obtained. 4672The variable named (which must not be readonly) will be 4673unset initially, then if a job has exited and its status is 4674being returned, set to the identifier from the 4675arg list (if given) of that job, 4676or the lead process identifier of the job to exit when used with 4677.Fl n 4678and no job arguments. 4679Note that 4680.Fl p 4681with neither 4682.Fl n 4683nor 4684.Ar job 4685arguments is useless, as in that case no job status is 4686returned, the variable named is simply unset. 4687.Pp 4688If the wait is interrupted by a signal, 4689its exit status will be greater than 128, 4690and 4691.Ar var , 4692if given, will remain unset. 4693.Pp 4694Once waited upon, by specific process number or job-id, 4695or by a 4696.Ic wait 4697with no arguments, 4698knowledge of the child is removed from the system, 4699and it cannot be waited upon again. 4700.Pp 4701Note than when a list of jobs are given, more that 4702one argument might refer to the same job. 4703In that case, if the final argument represents a job 4704that is also given earlier in the list, it is not 4705defined whether the status returned will be the 4706exit status of the job, or 127 indicating that 4707the child no longer existed when the wait command 4708reached the later argument in the list. 4709In this 4710.Nm 4711the exit status will be that from the job. 4712.Nm 4713waits for each job exactly once, regardless of 4714how many times (or how many different ways) it 4715is listed in the arguments to 4716.Ic wait . 4717That is 4718.Bd -literal -offset indent -compact 4719wait 100 100 100 4720.Ed 4721is identical to 4722.Bd -literal -offset indent -compact 4723wait 100 4724.Ed 4725.El 4726.\" 4727.\" 4728.Ss Job Control 4729.\" 4730Each process (or set of processes) started by 4731.Nm 4732is created as a 4733.Dq job 4734and added to the jobs table. 4735When enabled by the 4736.Fl m 4737option 4738.Pq aka Fl o Cm monitor 4739when the job is created, 4740.Nm 4741places each job (if run from the top level shell) 4742into a process group of its own, which allows control 4743of the process(es), and its/their descendants, as a unit. 4744When the 4745.Fl m 4746option is off, or when started from a sub-shell environment, 4747jobs share the same process group as the parent shell. 4748The 4749.Fl m 4750option is enabled by default in interactive shells with 4751a terminal as standard input and standard error. 4752.Pp 4753Jobs with separate process groups may be stopped, and then later 4754resumed in the foreground (with access to the terminal) 4755or in the background (where attempting to read from the 4756terminal will result in the job stopping.) 4757A list of current jobs can be obtained using the 4758.Ic jobs 4759built-in command. 4760Jobs are identified using either the process identifier 4761of the lead process of the job (the value available in 4762the special parameter 4763.Dq Dv \&! 4764if the job is started in the background), or using percent 4765notation. 4766Each job is given a 4767.Dq job number 4768which is a small integer, starting from 1, and can be 4769referenced as 4770.Dq Li \&% Ns Ar n 4771where 4772.Ar n 4773is that number. 4774Note that this applies to jobs both with and without their own process groups. 4775Job numbers are shown in the output from the 4776.Ic jobs 4777command enclosed in brackets 4778.Po 4779.Sq Li \&[ 4780and 4781.Sq Li \&] 4782.Pc . 4783Whenever the job table becomes empty, the numbers begin at one again. 4784In addition, there is the concept of a current, and a previous job, 4785identified by 4786.Dq Li \&%+ 4787.Po 4788or 4789.Dq Li \&%% 4790or even just 4791.Dq Li \&% 4792.Pc , 4793and a previous job, identified by 4794.Dq Li \&%\- . 4795Whenever a background job is started, 4796or a job is resumed in the background, 4797it becomes the current job. 4798The job that was the current job 4799(prepare for a big surprise here, drum roll..., wait for it...\&) 4800becomes the previous job. 4801When the current job terminates, the previous job is 4802promoted to be the current job. 4803In addition the form 4804.Dq Li \&% Ns Ar string\^ 4805finds the job for which the command starts with 4806.Ar string 4807and the form 4808.Dq Li \&%? Ns Ar string\^ 4809finds the job which contains the 4810.Ar string 4811in its command somewhere. 4812Both forms require the result to be unambiguous. 4813For this purpose the 4814.Dq command 4815is that shown in the output from the 4816.Ic jobs 4817command, not the original command line. 4818.Pp 4819The 4820.Ic bg , 4821.Ic fg , 4822.Ic jobid , 4823.Ic jobs , 4824.Ic kill , 4825.Ic suspend , 4826and 4827.Ic wait 4828commands all accept job identifiers as arguments, in addition to 4829process identifiers (larger integers). 4830See the 4831.Sx Built-ins 4832section above, and 4833.Xr kill 1 , 4834for more details of those commands. 4835In addition, a job identifier 4836(using one of the 4837.Dq \&% forms ) 4838issued as a command, without arguments, is interpreted as 4839if it had been given as the argument to the 4840.Ic fg 4841command. 4842.Pp 4843To cause a foreground process to stop, enter the terminal's 4844.Ic stop 4845character (usually control-Z). 4846To cause a background process to stop, 4847use the 4848.Ic suspend 4849built in command, or 4850send it a 4851.Dv STOP 4852signal, using the kill command. 4853A useful function to define is 4854.Bd -literal -offset indent 4855stop() { kill -s STOP "${@:-%%}"; } 4856.Ed 4857.Pp 4858The 4859.Ic fg 4860command resumes a stopped job, placing it in the foreground, 4861and 4862.Ic bg 4863resumes a stopped job in the background. 4864The 4865.Ic jobid 4866command provides information about process identifiers, job identifiers, 4867and the process group identifier, for a job. 4868.Pp 4869Whenever a sub-shell is created, the jobs table becomes invalid 4870(the sub-shell has no children.) 4871However, to enable uses like 4872.Bd -literal -offset indent 4873PID=$(jobid -p %1) 4874.Ed 4875.Pp 4876the table is only actually cleared in a sub-shell when needed to 4877create the first job there (built-in commands run in the foreground 4878do not create jobs.) 4879Note that in this environment, there is no useful current job 4880.Dq ( Li \&%% 4881actually refers to the sub-shell itself, but is not accessible) 4882but the job which is the current job in the parent can be accessed as 4883.Dq Li \&%\- . 4884.\" 4885.\" 4886.Ss Command Line Editing 4887.\" 4888When 4889.Nm 4890is being used interactively from a terminal, the current command 4891and the command history (see 4892.Ic fc 4893in the 4894.Sx Built-ins 4895section) 4896can be edited using emacs-mode or vi-mode command-line editing. 4897The command 4898.Ql set -o emacs 4899(or 4900.Fl E 4901option) 4902enables emacs-mode editing. 4903The command 4904.Ql set -o vi 4905(or 4906.Fl V 4907option) 4908enables vi-mode editing and places the current shell process into 4909vi insert mode. 4910(See the 4911.Sx Argument List Processing 4912section above.) 4913.Pp 4914The vi-mode uses commands similar to a subset of those described in the 4915.Xr vi 1 4916man page. 4917With vi-mode 4918enabled, 4919.Nm sh 4920can be switched between insert mode and command mode. 4921It's similar to 4922.Ic vi : 4923pressing the 4924.Aq ESC 4925key will throw you into vi command mode. 4926Insert mode is re-entered in any of the usual vi ways, 4927using the append (a) insert (i) substitute (s) (etc) commands. 4928Pressing the 4929.Aq return 4930key in either mode will pass the line to the shell. 4931.Pp 4932The emacs-mode uses commands similar to a subset available in the 4933.Ic emacs 4934editor. 4935With emacs-mode enabled, special keys can be used to modify the text 4936in the buffer using the control key. 4937.Pp 4938.Nm 4939uses the 4940.Xr editline 3 4941library. 4942See 4943.Xr editline 7 4944for a list of the possible command bindings, 4945and the default settings in emacs and vi modes. 4946Also see 4947.Xr editrc 5 4948for the commands that can be given to configure 4949.Xr editline 7 4950in the file named by the 4951.Ev EDITRC 4952parameter, 4953or a file used with the 4954.Ic inputrc 4955built-in command, 4956or using 4957.Xr editline 7 Ap s 4958configuration command line. 4959.Pp 4960When command line editing is enabled, the 4961.Xr editline 7 4962functions control printing of the 4963.Ev PS1 4964and 4965.Ev PS2 4966prompts when required. 4967As, in this mode, the command line editor needs to 4968keep track of what characters are in what position on 4969the command line, care needs to be taken when setting 4970the prompts. 4971Normal printing characters are handled automatically, 4972however mode setting sequences, which do not actually display 4973on the terminal, need to be identified to 4974.Xr editline 7 . 4975This is done, when needed, by choosing a character that 4976is not needed anywhere in the prompt, including in the mode 4977setting sequences, any single character is acceptable, 4978and assigning it to the shell parameter 4979.Dv PSlit . 4980Then that character should be used, in pairs, in the 4981prompt string. 4982Between each pair of 4983.Dv PSlit 4984characters are mode setting sequences, which affect the printing 4985attributes of the following (normal) characters of the prompt, 4986but do not themselves appear visibly, nor change the terminal's 4987cursor position. 4988.Pp 4989Each such sequence, that is 4990.Dv PSlit 4991character, mode setting character sequence, and another 4992.Dv PSlit 4993character, must currently be followed by at least one following 4994normal prompt character, or it will be ignored. 4995That is, a 4996.Dv PSlit 4997character cannot be the final character of 4998.Ev PS1 4999or 5000.Ev PS2 , 5001nor may two 5002.Dv PSlit 5003delimited sequences appear adjacent to each other. 5004Each sequence can contain as many mode altering sequences as are 5005required however. 5006Only the first character from 5007.Dv PSlit 5008will be used. 5009When set 5010.Dv PSlit 5011should usually be set to a string containing just one 5012character, then it can simply be embedded in 5013.Ev PS1 5014(or 5015.Ev PS2 ) 5016as in 5017.Pp 5018.D1 Li PS1=\*q${PSlit} Ns Ar mset\^ Ns Li ${PSlit}XYZ${PSlit} Ns Ar mclr\^ Ns Li ${PSlit}ABC\*q 5019.Pp 5020The prompt visible will be 5021.Dq XYZABC 5022with the 5023.Dq XYZ 5024part shown according as defined by the mode setting characters 5025.Ar mset , 5026and then cleared again by 5027.Ar mclr . 5028See 5029.Xr tput 1 5030for one method to generate appropriate mode sequences. 5031Note that both parts, XYZ and ABC, must each contain at least one 5032character. 5033.Pp 5034If 5035.Dv PSlit 5036is unset, which is its initial state, or set to a null string, 5037no literal character will be defined, 5038and all characters of the prompt strings will be assumed 5039to be visible characters (which includes spaces etc.) 5040To allow smooth use of prompts, without needing redefinition, when 5041.Xr editline 7 5042is disabled, the character chosen should be one which will be 5043ignored by the terminal if received, as when 5044.Xr editline 7 5045is not in use, the prompt strings are simply written to the terminal. 5046For example, setting: 5047.\" XXX: PS1 line is too long for -offset indent 5048.Bd -literal -offset left 5049 PSlit="$(printf\ '\e1')" 5050 PS1="${PSlit}$(tput\ bold\ blink)${PSlit}\e$${PSlit}$(tput\ sgr0)${PSlit}\ " 5051.Ed 5052.Pp 5053will arrange for the primary prompt to be a bold blinking dollar sign, 5054if supported by the current terminal, followed by an (ordinary) space, 5055and, as the SOH (control-A) character 5056.Pq Sq \e1 5057will not normally affect 5058a terminal, this same prompt will usually work with 5059.Xr editline 7 5060enabled or disabled. 5061.Sh ENVIRONMENT 5062.Bl -tag -width MAILCHECK 5063.It Ev CDPATH 5064The search path used with the 5065.Ic cd 5066built-in. 5067.It Ev EDITRC 5068Gives the name of the file containing commands for 5069.Xr editline 7 . 5070See 5071.Xr editrc 5 5072for possible content and format. 5073The file is processed, when in interactive mode with 5074command line editing enabled, whenever 5075.Ev EDITRC 5076is set (even with no actual value change,) 5077and if command line editing changes from disabled to enabled, 5078or the editor style used is changed. 5079(See the 5080.Fl E 5081and 5082.Fl V 5083options of the 5084.Ic set 5085built-in command, described in 5086.Sx Built-ins 5087above, which are documented further above in 5088.Sx Argument List Processing . ) 5089If unset 5090.Dq $HOME/.editrc 5091is used. 5092.It Ev ENV 5093Names the file sourced at startup by the shell. 5094Unused by this shell after initialization, 5095but is usually passed through the environment to 5096descendant shells. 5097See the 5098.Sx Invocation 5099section above for details of how 5100.Ev ENV 5101is processed and used. 5102.It Ev EUSER 5103Set to the login name of the effective user id running the shell, 5104as returned by 5105.Bd -literal -offset indent -compact 5106getpwuid(geteuid())->pw_name 5107.Ed 5108.Po 5109See 5110.Xr getpwuid 3 5111and 5112.Xr geteuid 2 5113for more details. 5114.Pc 5115This is obtained each time 5116.Ev EUSER 5117is expanded, so changes to the shell's execution identity 5118cause updates without further action. 5119If unset, it returns nothing. 5120If set it loses its special properties, and is simply a variable. 5121See the 5122.Ic specialvar 5123built-in command for remedial action. 5124.It Ev HISTAPPEND 5125If set to one of 5126.Ql true , 5127.Ql yes , 5128.Ql on , 5129or an integral value greater than zero, 5130and if 5131.Ev HISTFILE 5132is also set, and is a valid history file, 5133then as commands are read and added to the 5134history buffer, they are also written to the 5135.Ev HISTFILE 5136named. 5137.It Ev HISTFILE 5138When assigned to in an interactive shell 5139the contents of the file named by expanding 5140the new value of 5141.Ev HISTFILE 5142will, if it exists, 5143can be opened for reading, 5144and is a suitable 5145.Nm 5146history file (one previously written by 5147.Nm ) , 5148be read into the history buffer, 5149appending its contents to any existing history entries. 5150If 5151.Ev HISTFILE 5152is set when 5153.Nm 5154exits, 5155after any EXIT trap has been evaluated, 5156and if 5157.Ev HISTAPPEND 5158is not enabled, 5159or if 5160.Ev HISTFILE 5161is assigned when HISTAPPEND is enabled, 5162or if 5163.Ev HISTAPPEND 5164is enabled when 5165.Ev HISTFILE 5166is set, 5167the contents of the history buffer will be written 5168to the file named after expanding this variable. 5169If the file named did not previously exist, it will be created. 5170If it did exist, it must be writable. 5171The file will be truncated, and then if owned by the current user, 5172the current history buffer will be written to it. 5173.Pp 5174When used for reading or writing history entries, 5175variable and arithmetic expansions are performed, 5176upon its value to produce a file name, and if the 5177.Ev HISTFILE 5178variable was set by this shell, 5179rather than obtained from the environment, 5180command substitutions will also be performed. 5181No file will be used if an expansion error occurs, 5182or if there is a command substitution in a value obtained 5183from the environment. 5184.It Ev HISTSIZE 5185The number of lines in the history buffer for the shell. 5186If unset, or set to an empty string, 100 lines will be used. 5187Attempts to set HISTSIZE to anything other than a string of 5188digits will generate an error. 5189An invalid value found in the environment will be ignored. 5190.It Ev HOME 5191Set automatically by 5192.Xr login 1 5193from the user's login directory in the password file 5194.Pq Xr passwd 5 . 5195This environment variable also functions as the default argument for the 5196.Ic cd 5197built-in, and as the value of a tilde expansion without a user name. 5198.It Ev HOSTNAME 5199Set to the current hostname of the system, as returned by 5200.Xr gethostname 3 . 5201This is obtained each time 5202.Ev HOSTNAME 5203is expanded, so changes to the system's name are reflected 5204without further action. 5205If unset, it returns nothing. 5206If set it loses its special properties, and is simply a variable. 5207See the 5208.Ic specialvar 5209built-in command for remedial action. 5210.It Ev IFS 5211Input Field Separators. 5212This is normally set to 5213.Aq space , 5214.Aq tab , 5215and 5216.Aq newline . 5217See the 5218.Sx Field Splitting 5219section for more details. 5220.It Ev LANG 5221The string used to specify localization information that allows users 5222to work with different culture-specific and language conventions. 5223See 5224.Xr nls 7 . 5225.It Dv LINENO 5226The current line number in the script or function. 5227See the section 5228.Sx Using Dv LINENO 5229below for more details. 5230.It Ev MAIL 5231The name of a mail file, that will be checked for the arrival of new mail. 5232Overridden by 5233.Ev MAILPATH . 5234The check occurs just before 5235.Ev PS1 5236is written, immediately after reporting jobs which have changed status, 5237in interactive shells only. 5238New mail is considered to have arrived if the monitored file 5239has increased in size since the last check. 5240.\" .It Ev MAILCHECK 5241.\" The frequency in seconds that the shell checks for the arrival of mail 5242.\" in the files specified by the 5243.\" .Ev MAILPATH 5244.\" or the 5245.\" .Ev MAIL 5246.\" file. 5247.\" If set to 0, the check will occur at each prompt. 5248.It Ev MAILPATH 5249A colon 5250.Dq \&: 5251separated list of file names, for the shell to check for incoming mail. 5252This environment setting overrides the 5253.Ev MAIL 5254setting. 5255There is a maximum of 10 mailboxes that can be monitored at once. 5256.It Ev NBSH_INVOCATION 5257When 5258.Nm 5259starts, after it has processed its arguments, 5260and imported variables from the environment, 5261this variable is set to a string of one or more 5262characters which indicate the way the command line 5263was processed. 5264This is intended to be used in the startup 5265scripts 5266.Pq see Sx Invocation 5267to allow them to determine what actions are 5268appropriate to take. 5269.Ev NBSH_INVOCATION 5270is marked 5271.Dq not to be exported . 5272Apart from the way it is initialized, 5273and that it overrides any value that may 5274have been set in the environment, 5275there is nothing special about it. 5276It can be unset, or altered, 5277with no ramifications, 5278other than whatever effect this might have 5279on its use in the startup scripts. 5280.Pp 5281When the value of this variable remains as set at startup by 5282.Nm 5283the following characters may appear in the value, 5284in the circumstances described. 5285Any present will always appear in ASCII lexical 5286order, as they appear below (to make testing the value easier to code). 5287.Pp 5288.Bl -tag -width M__ -offset indent -compact 5289.It \&! 5290Always present when set by 5291.Nm , 5292and is always first. 5293No specific meaning is attributed to this character. 5294.It \&\- 5295Set when the first character of 5296.Va argv[0] 5297as set when the shell was invoked was a dash 5298.Pq Sq \&\- . 5299.It \&0 5300Set when at startup, the special parameter 5301.Dv \&$# 5302has the value 0. 5303That is, no arguments were given to the script 5304in the case that there is a script. 5305.It \&c 5306The 5307.Fl c 5308option was given on the command line. 5309.It \&f 5310Neither the 5311.Fl c 5312nor 5313.Fl s 5314options were present on the command line, 5315but there is at least one non-option argument, 5316which will then be interpreted as the name of the 5317.Ar command_file 5318to process. 5319.It \&i 5320The shell is interactive. 5321At startup this indicates that 5322.Sq i 5323will appear in the value of the 5324special parameter 5325.Va \&$\- . 5326However, the special parameter will 5327alter as the 5328.Fl i 5329option is manipulated by the 5330.Ic set 5331built-in command, but 5332.Ev NBSH_INVOCATION 5333is never subsequently altered by the shell itself 5334(unless manipulated by a regular variable operations). 5335.It \&l 5336The shell is a login shell. 5337As with 5338.Sq i 5339(the same operational conditions apply) 5340this character will be present if the 5341.Sq l 5342is present in 5343.Va \&$- 5344when the shell is starting. 5345Note that if 5346.Sq l 5347is present, and 5348.Sq \&\- 5349is not, then the shell was invoked 5350with the 5351.Fl l 5352option on the command line (or the 5353equivalent 5354.Fl o Em login ) . 5355On the other hand, if 5356.Sq \&\- 5357appears, and 5358.Sq l 5359does not, 5360then the shell was invoked with the 5361.Cm +l 5362option (or its equivalent) on the command line. 5363If both 5364.Sq \&\- 5365and 5366.Sq l 5367appear, then the shell is a normal login 5368shell, the 5369.Fl l 5370option might have been given, but had no effect. 5371If neither 5372.Sq \&\- 5373nor 5374.Sq l 5375appear, then the shell is not a login shell, 5376and was never intended to be. 5377The 5378.Cm +l 5379option might have been given, but had no effect. 5380.It \&p 5381The shell was started as a privileged 5382(set user id) process. 5383This indicates that the 5384.Fl p 5385option must have been given on the command 5386line, or privileges would have been dropped. 5387.It \&s 5388The shell will read commands from standard input. 5389The 5390.Fl s 5391option was given, or implied. 5392This does not imply that the shell is interactive. 5393.El 5394.It Ev PATH 5395The default search path for executables. 5396See the 5397.Sx Path Search 5398section above. 5399.It Ev POSIXLY_CORRECT 5400If set in the environment upon initialization of the shell, 5401then the shell option 5402.Ic posix 5403will be set. 5404.Po 5405See the description of the 5406.Ic set 5407command in the 5408.Sx Built-ins 5409section. 5410.Pc 5411After initialization it is unused by the shell, 5412but is usually passed through the environment to 5413descendant processes, including other instances of the shell, 5414which may interpret it in a similar way. 5415.It Ev PPID 5416The process identified of the parent process of the 5417current shell. 5418This value is set at shell startup, ignoring 5419any value in the environment, and then made readonly. 5420.It Ev PS1 5421The primary prompt string, which defaults to 5422.Dq Li "$ " , 5423unless you are the superuser, in which case it defaults to 5424.Dq Li "# " . 5425This string is subject to parameter, arithmetic, and if 5426enabled by setting the 5427.Ic promptcmds 5428option, command substitution before being output. 5429During execution of commands used by command substitution, 5430execution tracing, the 5431.Ic xtrace 5432.Ic ( set Fl x ) 5433option is temporarily disabled. 5434If 5435.Ic promptcmds 5436is not set and the prompt string uses command substitution, 5437the prompt used will be an appropriate error string. 5438For other expansion errors, the prompt will become an 5439empty string, without an error message. 5440To verify parsing of 5441.Ev PS1 , 5442the method suggested for 5443.Ev ENV 5444can be used. 5445.It Ev PS2 5446The secondary prompt string, which defaults to 5447.Dq Li "> " . 5448After expansion (as for 5449.Ev PS1 ) 5450it is written whenever more input is required to complete the 5451current command. 5452.It Ev PS4 5453is output, after expansion as described for 5454.Ev PS1 , 5455as a prefix for each line when execution trace 5456.Ic ( set Fl x ) 5457is enabled. 5458.Ev PS4 5459defaults to 5460.Dq Li "+ " . 5461.It Ev PSc 5462Initialized by the shell, ignoring any value from the environment, 5463to a single character string, either 5464.Sq \&# 5465or 5466.Sq \&$ , 5467depending upon whether the current user is the superuser or not. 5468This is intended for use when building a custom 5469.Ev PS1 . 5470If a privileged shell has its privileges removed by 5471clearing the 5472.Fl p 5473option, an attempt will be made to be reset 5474.Ev PSc 5475to 5476.Dq \&# 5477or 5478.Dq \&$ , 5479as appropriate for its new privilege level. 5480.It Ev PSlit 5481Defines the character which may be embedded in pairs, in 5482.Ev PS1 5483or 5484.Ev PS2 5485to indicate to 5486.Xr editline 7 5487that the characters between each pair of occurrences of the 5488.Dv PSlit 5489character will not appear in the visible prompt, and will not 5490cause the terminal's cursor to change position, but rather set terminal 5491attributes for the following prompt character(s) at least one of 5492which must be present. 5493See 5494.Sx Command Line Editing 5495above for more information. 5496.It Ev RANDOM 5497Returns a different pseudo-random integer, 5498in the range [0,32767] each time it is accessed. 5499.Ev RANDOM 5500can be assigned an integer value to seed the PRNG. 5501If the value assigned is a constant, then the 5502sequence of values produces on subsequent references of 5503.Ev RANDOM 5504will repeat after the next time the same constant is assigned. 5505Note, this is not guaranteed to remain constant from one version 5506of the shell to another \(en the PRNG algorithm, or seeding 5507method is subject to change. 5508If 5509.Ev RANDOM 5510is assigned an empty value (null string) then the next time 5511.Ev RANDOM 5512is accessed, it will be seeded from a more genuinely random source. 5513The sequence of pseudo-random numbers generated will not be able to 5514be generated again (except by luck, whether good or bad, depends!) 5515This is also how the initial seed is generated, if none has been 5516assigned before 5517.Ev RANDOM 5518is first accessed after shell initialization. 5519Should the error message 5520.Dq "RANDOM initialisation failed" 5521appear on standard error, it indicates that the source 5522of good random numbers was not available, and 5523.Ev RANDOM 5524has instead been seeded with a more predictable value. 5525The following sequence of random numbers will 5526not be as unpredictable as they otherwise would be. 5527.It Ev SECONDS 5528Returns the number of seconds since the current shell was started. 5529If unset, it remains unset, and returns nothing, unless set again. 5530If set, it loses its special properties, and becomes a normal variable. 5531See the 5532.Ic specialvar 5533built-in command for remedial action. 5534.It Ev START_TIME 5535Initialized by the shell to the number of seconds since the Epoch 5536(see 5537.Xr localtime 3 ) 5538when the shell was started. 5539The value of 5540.Dl $(( Ns Ev START_TIME + Ev SECONDS Ns )) 5541represents the current time, if 5542.Ev START_TIME 5543has not been modified, and 5544.Ev SECONDS 5545has not been set or unset. 5546.It Ev TERM 5547The default terminal setting for the shell. 5548This is inherited by 5549children of the shell, and is used in the history editing modes. 5550.It Ev ToD 5551When referenced, uses the value of 5552.Ev ToD_FORMAT 5553(or 5554.Dq \&%T 5555if 5556.Ev ToD_FORMAT 5557is unset) as the format argument to 5558.Xr strftime 3 5559to encode the current time of day, in the time zone 5560defined by 5561.Ev TZ 5562if set, or current local time if not, and returns the result. 5563If unset 5564.Ev ToD 5565returns nothing. 5566If set, it loses its special properties, and becomes a normal variable. 5567See the 5568.Ic specialvar 5569built-in command for remedial action. 5570.It Ev ToD_FORMAT 5571Can be set to the 5572.Xr strftime 3 5573format string to be used when expanding 5574.Ev ToD . 5575Initially unset. 5576.It Ev TZ 5577If set, gives the time zone 5578(see 5579.Xr localtime 3 , 5580.Xr environ 7 ) 5581to use when formatting 5582.Ev ToD 5583and if exported, other utilities that deal with times. 5584If unset, the system's local wall clock time zone is used. 5585.\" 5586.\" ========================================================== 5587.\" This is explicitly last, not in sort order - please leave! 5588.It Ev NETBSD_SHELL 5589Unlike the variables previously mentioned, 5590this variable is somewhat strange, 5591in that it cannot be set, 5592inherited from the environment, 5593modified, or exported from the shell. 5594If set, by the shell, it indicates that the shell is the 5595.Ic sh 5596defined by this manual page, and gives its version information. 5597It can also give information in additional space separated words, 5598after the version string. 5599If the shell was built as part of a reproducible build, 5600the relevant date that was used for that build will be included. 5601Finally, any non-standard compilation options, 5602which may affect features available, 5603that were used when building the shell will be listed. 5604.Ev NETBSD_SHELL 5605behaves like any other variable that has the read-only 5606and un-exportable attributes set. 5607.El 5608.Ss Using Dv LINENO 5609.Dv LINENO 5610is in many respects a normal shell variable, containing an 5611integer value, and can be expanded using any of the forms 5612mentioned above which can be used for any other variable. 5613.Pp 5614.Dv LINENO 5615can be exported, made readonly, or unset, as with any other 5616variable, with similar effects. 5617Note that while being readonly prevents later attempts to 5618set, or unset, 5619.Dv LINENO , 5620it does not prevent its value changing. 5621References to 5622.Dv LINENO 5623.Pq "when not unset" 5624always obtain the current line number. 5625However, 5626.Dv LINENO 5627should normally not ever be set or unset. 5628In this shell setting 5629.Dv LINENO 5630reverses the effect of an earlier 5631.Ic unset , 5632but does not otherwise affect the value obtained. 5633If unset, 5634.Dv LINENO 5635should not normally be set again, doing so is not portable. 5636If 5637.Dv LINENO 5638is set or unset, different shells act differently. 5639The value of 5640.Dv LINENO 5641is never imported from the environment when the shell is 5642started, though if present there, as with any other variable, 5643.Dv LINENO 5644will be exported by this shell. 5645.Pp 5646.Dv LINENO 5647is set automatically by the shell to be the number of the source 5648line on which it occurs. 5649When exported, 5650.Dv LINENO 5651is exported with its value set to the line number it would have 5652had had it been referenced on the command line of the command to 5653which it is exported. 5654Line numbers are counted from 1, which is the first line the shell 5655reads from any particular file. 5656For this shell, standard input, including in an interactive shell, 5657the user's terminal, is just another file and lines are counted 5658there as well. 5659However note that not all shells count interactive 5660lines this way, it is not wise to rely upon 5661.Dv LINENO 5662having a useful value, except in a script, or a function. 5663.Pp 5664The role of 5665.Dv LINENO 5666in functions is less clear. 5667In some shells, 5668.Dv LINENO 5669continues to refer to the line number in the script which defines 5670the function, 5671in others lines count from one within the function, always (and 5672resume counting normally once the function definition is complete) 5673and others count in functions from one if the function is defined 5674interactively, but otherwise just reference the line number in the 5675script in which the function is defined. 5676This shell gives the user the option to choose. 5677If the 5678.Fl L 5679flag (the 5680.Ic local_lineno 5681option, see 5682.Sx Argument List Processing ) 5683is set, when the function is defined, then the function 5684defaults to counting lines with one being the first line of the 5685function. 5686When the 5687.Fl L 5688flag is not set, the shell counts lines in a function definition 5689in the same continuous sequence as the lines that surround the 5690function definition. 5691Further, if 5692.Dv LINENO 5693is made local 5694(see 5695.Sx Built-ins 5696above) 5697inside the function, the function can decide which 5698behavior it prefers. 5699If 5700.Dv LINENO 5701is made local and inherited, and not given a value, as in 5702.Dl local Fl I Dv LINENO 5703then from that point in the function, 5704.Dv LINENO 5705will give the line number as if lines are counted in sequence 5706with the lines that surround the function definition (and 5707any other function definitions in which this is nested.) 5708If 5709.Dv LINENO 5710is made local, and in that same command, given a value, as 5711.Dl local Oo Fl I Ns | Ns Fl N Oc Dv LINENO Ns = Ns Ar value 5712then 5713.Dv LINENO 5714will give the line number as if lines are counted from one 5715from the beginning of the function. 5716The value nominally assigned in this case is irrelevant, and ignored. 5717For completeness, if lineno is made local and unset, as in 5718.Dl local Fl N Dv LINENO 5719then 5720.Dv LINENO 5721is simply unset inside the function, and gives no value at all. 5722.Pp 5723Now for some technical details. 5724The line on which 5725.Dv LINENO 5726occurs in a parameter expansion, is the line that contains the 5727.Sq \&$ 5728that begins the expansion of 5729.Dv LINENO . 5730In the case of nested expansions, that 5731.Sq \&$ 5732is the one that actually has 5733.Dv LINENO 5734as its parameter. 5735In an arithmetic expansion, where no 5736.Sq \&$ 5737is used to evaluate 5738.Dv LINENO 5739but 5740.Dv LINENO 5741is simply referenced as a variable, then the value is the 5742line number of the line that contains the 5743.Sq L 5744of 5745.Dv LINENO . 5746For functions line one of the function definition (when relevant) 5747is the line that contains the first character of the 5748function name in the definition. 5749When exported, the line number of the command is the line number 5750where the first character of the word which becomes the command name occurs. 5751.Pp 5752When the shell opens a new file, for any reason, 5753it counts lines from one in that file, 5754and then resumes its original counting once it resumes reading the 5755previous input stream. 5756When handling a string passed to 5757.Ic eval 5758the line number starts at the line on which the string starts, 5759and then if the string contains internal newline characters, 5760those characters increase the line number. 5761This means that references to 5762.Dv LINENO 5763in such a case can produce values larger than would be 5764produced by a reference on the line after the 5765.Ic eval . 5766.Sh FILES 5767.Bl -item 5768.It 5769.Pa $HOME/.profile 5770.It 5771.Pa /etc/profile 5772.El 5773.Sh EXIT STATUS 5774Errors that are detected by the shell, such as a syntax error, will cause the 5775shell to exit with a non-zero exit status. 5776If the shell is not an 5777interactive shell, the execution of the shell file will be aborted. 5778Otherwise 5779the shell will return the exit status of the last command executed, or 5780if the exit built-in is used with a numeric argument, it will return the 5781argument. 5782.Sh SEE ALSO 5783.Xr csh 1 , 5784.Xr echo 1 , 5785.Xr getopt 1 , 5786.Xr ksh 1 , 5787.Xr login 1 , 5788.Xr printf 1 , 5789.Xr test 1 , 5790.Xr editline 3 , 5791.Xr getopt 3 , 5792.\" .Xr profile 4 , 5793.Xr editrc 5 , 5794.Xr passwd 5 , 5795.Xr editline 7 , 5796.Xr environ 7 , 5797.Xr nls 7 , 5798.Xr sysctl 8 5799.Sh HISTORY 5800A 5801.Nm 5802command appeared in 5803.At v1 . 5804It was replaced in 5805.At v7 5806with a version that introduced the basis of the current syntax. 5807That was, however, unmaintainable so we wrote this one. 5808This 5809.Nx 5810.Nm 5811is a much modified descendant of the ash shell written by Ken Almquist. 5812.Sh BUGS 5813Setuid shell scripts should be avoided at all costs, as they are a 5814significant security risk. 5815.Pp 5816The characters generated by filename completion should probably be quoted 5817to ensure that the filename is still valid after the input line has been 5818processed. 5819.Pp 5820Job control of compound statements (loops, etc) is a complete mess. 5821.Pp 5822The 5823.Fl Z 5824option to the 5825.Ic jobs 5826built-in command is bizarre, but is implemented this way to be 5827compatible with the similar option in 5828.Xr zsh 1 . 5829.Pp 5830Many, many, more. 5831(But less than there were...) 5832