1.\" $NetBSD: sh.1,v 1.267 2024/10/14 08:27:53 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 October 14, 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(indicated 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), 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. 2775When the 2776.Cm posix 2777option is not set, 2778file descriptors created via such redirections are marked close-on-exec 2779(see 2780.Xr open 2 2781.Dv O_CLOEXEC 2782or 2783.Xr fcntl 2 2784.Dv F_SETFD / 2785.Dv FD_CLOEXEC ) , 2786unless the descriptors refer to the standard input, 2787output, or error (file descriptors 0, 1, 2). 2788Traditionally Bourne-like shells 2789(except 2790.Xr ksh 1 ) , 2791made those file descriptors available to exec'ed processes. 2792To be assured the close-on-exec setting is off, 2793redirect the descriptor to (or from) itself, 2794either when invoking a command for which the descriptor is wanted open, 2795or by using 2796.Ic exec 2797.Po perhaps the same 2798.Ic exec 2799.No as opened it, after the open Pc 2800to leave the descriptor open in the shell 2801and pass it to all commands invoked subsequently. 2802Alternatively, see the 2803.Ic fdflags 2804command below, which can set, or clear, this, and other, 2805file descriptor flags. 2806.\" 2807.Pp 2808.It Ic exit Op Ar exitstatus 2809Terminate the shell process. 2810If 2811.Ar exitstatus 2812is given it is used as the exit status of the shell; otherwise the 2813exit status of the preceding command (the current value of $?) is used. 2814.\" 2815.Pp 2816.It Ic export Oo Fl nx Oc Ar name Ns Oo =value Oc ... 2817.It Ic export Oo Fl x Oc Oo Fl p Oo Ar name ... Oc Oc 2818.It Ic export Fl q Oo Fl x Oc Ar name ... 2819With no options, 2820but one or more names, 2821the specified names are exported so that they will appear in the 2822environment of subsequent commands. 2823With 2824.Fl n 2825the specified names are un-exported. 2826Variables can also be un-exported using the 2827.Ic unset 2828built in command. 2829With 2830.Fl x 2831.Pq exclude 2832the specified names are marked not to be exported, 2833and any that had been exported, will be un-exported. 2834Later attempts to export the variable will be refused. 2835Note this does not prevent explicitly exporting a variable 2836to a single command, script or function by preceding that 2837command invocation by a variable assignment to that variable, 2838provided the variable is not also read-only. 2839That is 2840.Bd -literal -offset indent 2841export -x FOO # FOO will now not be able to be exported 2842export FOO # this command will fail (non-fatally) 2843.Ed 2844But with 2845.Bd -literal -offset indent -compact 2846FOO=some_value my_command 2847.Ed 2848.Nm 2849still passes the value 2850.Pq Li FOO=some_value 2851to 2852.Li my_command 2853through the environment. 2854.Pp 2855The shell allows the value of a variable to be set at the 2856same time it is exported (or unexported, etc) by writing 2857.Pp 2858.Dl export [-nx] name=value 2859.Pp 2860Note that in such a usage, the 2861.Dq name=value 2862argument often needs to be quoted, 2863more often than is required of an assignment statement, 2864as, like with any other command, the command name and 2865arguments are all subject to the various expansions, 2866including filename expansion and field splitting, 2867before the 2868.Ic export 2869command is invoked. 2870With the default value for 2871.Dv IFS : 2872.Bd -unfilled -offset indent -compact 2873X='a b c' 2874export Y=$X 2875.Ed 2876the command invoked would be 2877.Dl "export Y=a b c" 2878exporting 2879.Dv Y , 2880with the value 2881.Dq a 2882and also exporting the variables named 2883.Dq b 2884and 2885.Dq c , 2886which is probably not as intended. 2887.Pp 2888With no arguments the export command lists the names of all 2889set exported variables, 2890or if 2891.Fl x 2892was given, all set variables marked not for export. 2893With the 2894.Fl p 2895option specified, the output will be formatted suitably for 2896non-interactive use, and unset variables are included. 2897When 2898.Fl p 2899is given, variable names, but not values, may also be 2900given, in which case output is limited to the variables named. 2901.Pp 2902With 2903.Fl q 2904and a list of variable names, the 2905.Ic export 2906command will exit with status 0 if all the named 2907variables have been marked for export, or 1 if 2908any are not so marked. 2909If 2910.Fl x 2911is also given, 2912the test is instead for variables marked not to be exported. 2913.Pp 2914Other than with 2915.Fl q , 2916the 2917.Ic export 2918built-in exits with status 0, 2919unless an attempt is made to export a variable which has 2920been marked as unavailable for export, 2921in which cases it exits with status 1. 2922In all cases if 2923an invalid option, or option combination, is given, 2924or an invalid variable name is present, 2925.Ic export 2926will write a message to the standard error output, 2927and exit with a non-zero status. 2928A non-interactive shell will terminate. 2929.Pp 2930Note that there is no restriction upon exporting, 2931or un-exporting, read-only variables. 2932The no-export flag can be reset by unsetting the variable 2933and creating it again \(en provided the variable is not also read-only. 2934.\" 2935.Pp 2936.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last 2937.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last 2938.It Ic fc Fl s Oo Ar old=new Oc Op Ar first 2939.It Ic fc Fl z 2940.Pp 2941The 2942.Ic fc 2943built-in lists, or edits and re-executes, commands previously entered 2944to an interactive shell. 2945.Bl -tag -width 5n 2946.It Fl e Ar editor 2947Use the editor named by 2948.Ar editor 2949to edit the commands. 2950The 2951.Ar editor 2952string is a command name, subject to search via the 2953.Ev PATH 2954variable. 2955The value in the 2956.Ev FCEDIT 2957variable is used as a default when 2958.Fl e 2959is not specified. 2960If 2961.Ev FCEDIT 2962is null or unset, the value of the 2963.Ev EDITOR 2964variable is used. 2965If 2966.Ev EDITOR 2967is null or unset, 2968.Xr ed 1 2969is used as the editor. 2970.It Fl l No (ell) 2971List the commands rather than invoking an editor on them. 2972The commands are written in the sequence indicated by 2973the first and last operands, as affected by 2974.Fl r , 2975with each command preceded by the command number. 2976.It Fl n 2977Suppress command numbers when listing with 2978.Fl l . 2979.It Fl r 2980Reverse the order of the commands listed (with 2981.Fl l ) 2982or edited (with neither 2983.Fl l 2984nor 2985.Fl s ) . 2986.It Fl s 2987Re-execute the command without invoking an editor. 2988.It Fl z 2989Clear the history buffer. 2990No other options or arguments are permitted. 2991.It Ar first 2992.It Ar last 2993Select the commands to list or edit. 2994The number of previous commands that 2995can be accessed are determined by the value of the 2996.Ev HISTSIZE 2997variable. 2998The value of 2999.Ar first 3000or 3001.Ar last 3002or both are one of the following: 3003.Bl -tag -width 5n 3004.It Oo Cm + Oc Ns Ar number 3005A positive number representing a command number; command numbers can be 3006displayed with the 3007.Fl l 3008option. 3009.It Cm \- Ns Ar number 3010A negative decimal number representing the command that was executed 3011number of commands previously. 3012For example, \-1 is the immediately previous command. 3013.El 3014.It Ar string 3015A string indicating the most recently entered command that begins with 3016that string. 3017If the 3018.Ar old Ns Li = Ns Ar new 3019operand is not also specified with 3020.Fl s , 3021the string form of the first operand cannot contain an embedded equal sign. 3022.El 3023.Pp 3024The following environment variables affect the execution of 3025.Ic fc : 3026.Bl -tag -width HISTSIZE 3027.It Ev FCEDIT 3028Name of the editor to use. 3029If 3030.Ev FCEDIT 3031is not set, 3032.Ev EDITOR 3033is used, if set. 3034If neither is used the 3035.Ic ed 3036utility is used. 3037.It Ev HISTSIZE 3038The number of previous commands that are accessible. 3039.El 3040.\" 3041.Pp 3042.It Ic fg Op Ar job 3043Move the specified job or the current job to the foreground. 3044A foreground job can interact with the user via standard input, 3045and receive signals from the terminal. 3046.\" 3047.Pp 3048.It Ic fdflags Oo Fl v Oc Op Ar fd ... 3049.It Ic fdflags Oo Fl v Oc Fl s Ar flags fd Op ... 3050Get or set file descriptor flags. 3051The 3052.Fl v 3053argument enables verbose printing, printing flags that are also off, and 3054the flags of the file descriptor being set after setting. 3055The 3056.Fl s 3057flag interprets the 3058.Ar flags 3059argument as a comma separated list of file descriptor flags, each preceded 3060with a 3061.Dq \(pl 3062or a 3063.Dq \(mi 3064indicating to set or clear the respective flag. 3065Valid flags are: 3066.Cm append , 3067.Cm async , 3068.Cm sync , 3069.Cm nonblock , 3070.Cm fsync , 3071.Cm dsync , 3072.Cm rsync , 3073.Cm direct , 3074.Cm nosigpipe , 3075and 3076.Cm cloexec . 3077Unique abbreviations of these names, of at least 2 characters, 3078may be used on input. 3079See 3080.Xr fcntl 2 3081and 3082.Xr open 2 3083for more information. 3084.\" 3085.Pp 3086.It Ic getopts Ar optstring var 3087The POSIX 3088.Ic getopts 3089command, not to be confused with the 3090Bell Labs\[en]derived 3091.Xr getopt 1 . 3092.Pp 3093The first argument should be a series of letters, each of which may be 3094optionally followed by a colon (:) to indicate that the option requires an 3095argument. 3096The variable specified is set to the parsed option. 3097.Pp 3098The 3099.Ic getopts 3100command deprecates the older 3101.Xr getopt 1 3102utility due to its handling of arguments containing whitespace. 3103.Pp 3104The 3105.Ic getopts 3106built-in may be used to obtain options and their arguments 3107from a list of parameters. 3108When invoked, 3109.Ic getopts 3110places the value of the next option from the option string in the list in 3111the shell variable specified by 3112.Ar var 3113and its index in the shell variable 3114.Ev OPTIND . 3115When the shell is invoked, 3116.Ev OPTIND 3117is initialized to 1. 3118For each option that requires an argument, the 3119.Ic getopts 3120built-in will place it in the shell variable 3121.Ev OPTARG . 3122If an option is not allowed for in the 3123.Ar optstring , 3124then 3125.Ev OPTARG 3126will be unset. 3127.Pp 3128.Ar optstring 3129is a string of recognized option letters (see 3130.Xr getopt 3 ) . 3131If a letter is followed by a colon (:), the option is expected to have an 3132argument which may or may not be separated from the option by whitespace. 3133If an option character is not found where expected, 3134.Ic getopts 3135will set the variable 3136.Ar var 3137to 3138.Sq Li \&? ; 3139.Ic getopts 3140will then unset 3141.Ev OPTARG 3142and write an error to standard error. 3143.Pp 3144By specifying a colon (:) as the first character of 3145.Ar optstring , 3146the error handling behavior changes: 3147no errors will be written to standard error; 3148unknown option characters will set 3149.Ar var 3150to 3151.Sq Li \&? 3152and set 3153.Ev OPTARG 3154to the unknown option character (instead of unset 3155.Ev OPTARG Ns ); 3156and missing option arguments will set 3157.Ar var 3158to 3159.Sq Li \&: 3160and set 3161.Ev OPTARG 3162to the option character with the missing argument. 3163.Pp 3164A nonzero value is returned when the last option is reached. 3165If there are no remaining arguments, 3166.Ic getopts 3167will set 3168.Ar var 3169to the special option, 3170.Dq Li \-\- , 3171otherwise, it will set 3172.Ar var 3173to 3174.Sq Li \&? . 3175.Pp 3176The following code fragment shows how one might process the arguments 3177for a command that can take the options 3178.Fl a 3179and 3180.Fl b , 3181and the option 3182.Fl c , 3183which requires an argument. 3184.Bd -literal -offset indent 3185while getopts abc: f 3186do 3187 case $f in 3188 a | b) flag=$f;; 3189 c) carg=$OPTARG;; 3190 \e?) echo $USAGE; exit 1;; 3191 esac 3192done 3193shift $((OPTIND - 1)) 3194.Ed 3195.Pp 3196This code will accept any of the following as equivalent: 3197.Bd -literal -offset indent 3198cmd \-acarg file file 3199cmd \-a \-c arg file file 3200cmd \-carg -a file file 3201cmd \-a \-carg \-\- file file 3202.Ed 3203.\" 3204.Pp 3205.It Ic hash Oo Fl befqrsuv Oc Op Ar command ... 3206The shell maintains a hash table which remembers the 3207locations and types of commands. 3208With the 3209.Fl r 3210option given, 3211the 3212.Ic hash 3213command begins by clearing all commands, 3214except special built-in commands and functions, 3215from this table. 3216Commands, other than functions, are added to the table as 3217described below, or as they are encountered 3218through normal execution, or for functions, 3219when they are defined. 3220Functions are removed with the 3221.Ic unset 3222built-in command. 3223Special built-in commands are added at shell startup, 3224and never removed. 3225Utilities can also be removed when 3226.Ev PATH 3227is altered. 3228.Pp 3229With no 3230.Ar command 3231arguments 3232the 3233.Ic hash 3234command then prints out the contents of this table. 3235Note that this is a hash table, the order of the 3236contents is unpredictable, and meaningless. 3237.Pp 3238The 3239.Fl b , 3240.Fl f , 3241.Fl s , 3242and 3243.Fl u 3244options control which entries are printed. 3245With 3246.Fl f 3247functions are printed; with 3248.Fl b 3249or 3250.Fl s 3251regular, or special, built-in commands are listed; 3252and with 3253.Fl u 3254normal utilities (those commands found in the filesystem 3255by searching 3256.Ev PATH ) 3257are printed. 3258For compatibility with some older versions of the 3259.Ic hash 3260command, 3261.Fl c 3262is accepted as an alternative of 3263.Fl u . 3264.Pp 3265Some normal command entries which have not been verified since the last 3266.Ic cd 3267command are marked with an asterisk; it is possible for these entries 3268to be invalid. 3269.Pp 3270The 3271.Fl v 3272option causes more verbose output to be included, indicating the 3273type of the command, rather than simply its name. 3274For functions, the body of the function is included. 3275.Pp 3276If none of the above options is given, the default is to 3277show normal commands only. 3278With 3279.Fl v 3280and no other options, the whole table (all types) will be shown. 3281.Pp 3282Unless there is an error writing the output, the 3283.Ic hash 3284command will exit with status 0 in this usage. 3285.Pp 3286With 3287.Ar command 3288arguments, the 3289.Ic hash 3290command removes the specified commands from the hash table (unless 3291they are functions or special built-in commands) and then locates 3292and reinstalls them. 3293With the 3294.Fl v 3295option, 3296.Ic hash 3297prints the locations of the commands as it finds them. 3298The 3299.Fl bfsu 3300options control which types of commands will be affected. 3301If any of those options is given, and a command found to 3302already be in the hash table is not one of the designated types, 3303that entry, and the 3304.Ar command 3305argument, will simply be silently skipped. 3306If none of those flags is given, any command type can be affected. 3307.Pp 3308If a 3309.Ar command 3310is not located, then unless 3311.Fl q 3312was given, a 3313.Dq not found 3314error message will be printed. 3315.Pp 3316The 3317.Fl e 3318option implies 3319.Fl q 3320if that option was not given, and also causes the exit status 3321of the 3322.Ic hash 3323command to ignore the unfound 3324.Ar command . 3325Otherwise if any 3326.Ar command 3327is not found, the 3328.Ic hash 3329command will exit with status 1. 3330.Pp 3331To allow a method to permit backwards compatibility with the way 3332that the 3333.Ic hash 3334command worked before 3335.Nx 10.0 , 3336if both the 3337.Fl e 3338and 3339.Fl q 3340options are given, then an error message will be printed about 3341.Ar command Ns s 3342unable to be found, but the exit status will remain 0. 3343This is not considered useful. 3344.\" 3345.Pp 3346.It Ic inputrc Ar file 3347Read the 3348.Ar file 3349to set key bindings as defined by 3350.Xr editrc 5 . 3351.\" 3352.Pp 3353.It Ic jobid Oo Fl g Ns \&| Ns Fl j Ns \&| Ns Fl p Oc Op Ar job 3354With no flags, print the process identifiers of the processes in the job. 3355If the 3356.Ar job 3357argument is omitted, the current job is used. 3358Any of the ways to select a job may be used for 3359.Ar job , 3360including the 3361.Sq Li \&% 3362forms, or the process id of the job leader 3363.Po 3364.Dq Li \&$! 3365if the job was created in the background. 3366.Pc 3367.Pp 3368If one of the flags is given, then instead of the list of 3369process identifiers, the 3370.Ic jobid 3371command prints: 3372.Bl -tag -width ".Fl g" 3373.It Fl g 3374the process group, if one was created for this job, 3375or nothing otherwise (the job is in the same process 3376group as the shell.) 3377.It Fl j 3378the job identifier (using 3379.Dq Li \&% Ns Ar n 3380notation, where 3381.Ar n 3382is a number) is printed. 3383.It Fl p 3384only the process id of the process group leader is printed. 3385.El 3386.Pp 3387These flags are mutually exclusive. 3388.Pp 3389.Ic jobid 3390exits with status 2 if there is an argument error, 3391status 1, if with 3392.Fl g 3393the job had no separate process group, 3394or with 3395.Fl p 3396there is no process group leader (should not happen), 3397and otherwise exits with status 0. 3398.\" 3399.Pp 3400.It Ic jobs Oo Fl l Ns \&| Ns Fl p Oc Op Ar job ... 3401.It Ic jobs Fl Z Op Ar title 3402Without 3403.Ar job 3404arguments, 3405this command lists out all the background processes 3406which are children of the current shell process. 3407With 3408.Ar job 3409arguments, the listed jobs are shown instead. 3410Without flags, the output contains the job 3411identifier (see 3412.Sx Job Control 3413below), an indicator character if the job is the current or previous job, 3414the current status of the job (running, suspended, or terminated successfully, 3415unsuccessfully, or by a signal) 3416and a (usually abbreviated) command string. 3417.Pp 3418With the 3419.Fl l 3420flag the output is in a longer form, with the process identifiers 3421of each process (run from the top level, as in a pipeline), and the 3422status of each process, rather than the job status. 3423.Pp 3424With the 3425.Fl p 3426flag, the output contains only the process identifier of the lead 3427process (which is also the process group identifier). 3428Note that this is not necessarily the same process identifier as 3429reported in the special parameter 3430.Dv \&! 3431when a background job is started. 3432.Pp 3433With the 3434.Fl Z 3435flag, the process command line is set using 3436.Xr setproctitle 3 . 3437If 3438.Ar title 3439is omitted or a null string, 3440.Xr setproctitle 3 3441is called with a 3442.Dv NULL 3443format. 3444.Pp 3445These options are mutually exclusive, the last specified is used. 3446.Pp 3447In an interactive shell, each job shown as completed in the output 3448from the jobs command is implicitly waited for, and is removed from 3449the jobs table, never to be seen again. 3450In an interactive shell, when a background job terminates, the 3451.Ic jobs 3452command (with that job as an argument) is implicitly run just 3453before outputting the next PS1 command prompt, after the job 3454terminated. 3455This indicates that the job finished, shows its status, 3456and cleans up the job table entry for that job. 3457Non-interactive shells need to execute 3458.Ic wait 3459commands to clean up terminated background jobs. 3460.\" 3461.Pp 3462.It Ic local Oo Fl INx Oc Oo Ar variable | \- Oc ... 3463Define local variables for a function. 3464Local variables have their attributes, and values, 3465as they were before the 3466.Ic local 3467declaration, restored when the function terminates. 3468.Pp 3469With the 3470.Fl N 3471flag, variables made local, are unset initially inside 3472the function. 3473Unless the 3474.Fl x 3475flag is also given, such variables are also unexported. 3476The 3477.Fl I 3478flag, which is the default in this shell, causes 3479the initial value and exported attribute 3480of local variables 3481to be inherited from the variable 3482with the same name in the surrounding 3483scope, if there is one. 3484If there is not, the variable is initially unset, 3485and not exported. 3486The 3487.Fl N 3488and 3489.Fl I 3490flags are mutually exclusive, if both are given, the last specified applies. 3491The read-only and unexportable attributes are always 3492inherited, if a variable with the same name already exists. 3493.Pp 3494The 3495.Fl x 3496flag (lower case) causes the local variable to be exported, 3497while the function runs, unless it has the unexportable attribute. 3498This can also be accomplished by using the 3499.Ic export 3500command, giving the same 3501.Ar variable 3502names, after the 3503.Ic local 3504command. 3505.Pp 3506Making an existing read-only variable local is possible, 3507but pointless. 3508If an attempt is made to assign an initial value to such 3509a variable, the 3510.Ic local 3511command fails, as does any later attempted assignment. 3512If the 3513.Ic readonly 3514command is applied to a variable that has been declared local, 3515the variable cannot be (further) modified within the function, 3516or any other functions it calls, however when the function returns, 3517the previous status (and value) of the variable is returned. 3518.Pp 3519Values may be given to local variables on the 3520.Ic local 3521command line in a similar fashion as used for 3522.Ic export 3523and 3524.Ic readonly . 3525These values are assigned immediately after the initialization 3526described above. 3527Note that any variable references on the command line will have 3528been expanded before 3529.Ic local 3530is executed, so expressions like 3531.Bd -unfilled -offset indent 3532local -N X="${X}" 3533.Ed 3534.Pp 3535are well defined, first $X is expanded, and then the command run is 3536.Dl "local -N X='old-value-of-X'" 3537See the description of the 3538.Ic export 3539built-in command for notes on why quoting the value is required. 3540.Pp 3541After arranging to preserve the old value and attributes, of 3542.Dv X 3543.Dq ( old-value-of X ) 3544.Ic local 3545unsets 3546.Dv X , 3547unexports it, and then assigns the 3548.Dq old-value-of-X 3549to 3550.Ev X . 3551.Pp 3552The shell uses dynamic scoping, so that if you make the variable 3553.Dv x 3554local to 3555function 3556.Dv f , 3557which then calls function 3558.Dv g , 3559references to the variable 3560.Dv x 3561made inside 3562.Dv g 3563will refer to the variable 3564.Dv x 3565declared inside 3566.Dv f , 3567not to the global variable named 3568.Dv x . 3569.Pp 3570Another way to view this, is as if the shell just has one flat, global, 3571namespace, in which all variables exist. 3572The 3573.Ic local 3574command conceptually copies the variable(s) named to unnamed temporary 3575variables, and when the function ends, copies them back again. 3576All references to the variables reference the same global variables, 3577but while the function is active, after the 3578.Ic local 3579command has run, the values and attributes of the variables might 3580be altered, and later, when the function completes, be restored. 3581.Pp 3582Note that the positional parameters 3583.Dv 1 , \" $1 3584.Dv 2 , \" $2 3585\&... (see 3586.Sx Positional Parameters ) , 3587and the special parameters 3588.Dv \&# , \" $# 3589.Dv \&* \" $* 3590and 3591.Dv \&@ \" $@ 3592(see 3593.Sx Special Parameters ) , 3594are always made local in all functions, and are reset inside the 3595function to represent the options and arguments passed to the function. 3596Note that 3597.Li $0 3598however retains the value it had outside the function, 3599as do all the other special parameters. 3600.Pp 3601The only special parameter that can optionally be made local is 3602.Dq Li \- . 3603Making 3604.Dq Li \- 3605local causes any shell options that are changed via the set command inside the 3606function to be restored to their original values when the function 3607returns. 3608If 3609.Fl X 3610option is altered after 3611.Dq Li \- 3612has been made local, then when the function returns, the previous 3613destination for 3614.Cm xtrace 3615output (as of the time of the 3616.Ic local 3617command) will also be restored. 3618If any of the shell's magic variables 3619(those which return a value which may vary without 3620the variable being explicitly altered, 3621e.g.: 3622.Dv SECONDS 3623or 3624.Dv HOSTNAME ) 3625are made local in a function, 3626they will lose their special properties when set 3627within the function, including by the 3628.Ic local 3629command itself 3630(if not to be set in the function, there is little point 3631in making a variable local) 3632but those properties will be restored when the function returns. 3633.Pp 3634It is an error to use 3635.Ic local 3636outside the scope of a function definition. 3637When used inside a function, it exits with status 0, 3638unless an undefined option is used, or an attempt is made to 3639assign a value to a read-only variable. 3640.Pp 3641Note that either 3642.Fl I 3643or 3644.Fl N 3645should always be used, or variables made local should always 3646be given a value, or explicitly unset, as the default behavior 3647(inheriting the earlier value, or starting unset after 3648.Ic local ) 3649differs amongst shell implementations. 3650Using 3651.Dq Li local \&\- 3652is an extension not implemented by most shells. 3653.Pp 3654See the section 3655.Sx Using Dv LINENO 3656below for details of the effects of making the variable 3657.Dv LINENO 3658local. 3659.\" 3660.Pp 3661.It Ic pwd Op Fl \&LP 3662Print the current directory. 3663If 3664.Fl L 3665is specified the cached value (initially set from 3666.Ev PWD ) 3667is checked to see if it refers to the current directory; if it does 3668the value is printed. 3669Otherwise the current directory name is found using 3670.Xr getcwd 3 . 3671.Pp 3672The default is 3673.Ic pwd 3674.Fl L , 3675but note that the built-in 3676.Ic cd 3677command doesn't support the 3678.Fl L 3679option and will cache (almost) the absolute path. 3680If 3681.Ic cd 3682is changed (as unlikely as that is), 3683.Ic pwd 3684may be changed to default to 3685.Ic pwd 3686.Fl P . 3687.Pp 3688If the current directory is renamed and replaced by a symlink to the 3689same directory, or the initial 3690.Ev PWD 3691value followed a symbolic link, then the cached value may not 3692be the absolute path. 3693.Pp 3694The built-in command may differ from the program of the same name because 3695the program will use 3696.Ev PWD 3697and the built-in uses a separately cached value. 3698.\" 3699.Pp 3700.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 ... 3701.Pp 3702The 3703.Ic read 3704command reads a record (by default one line) from its standard input, 3705splits that record as if by field splitting, and assigns the results 3706to the named 3707.Ar variable 3708arguments, as detailed below. 3709.Pp 3710The options are: 3711.Bl -tag -width ".Fl ppromptM" 3712.It Fl b 3713Do buffered reads, rather than reading one byte at a time. 3714This option is ignored if reading from a pipe. 3715Use of this option might result in reading more bytes from 3716standard input than the 3717.Ic read 3718utility actually processes, 3719causing some data from standard input to be unavailable 3720to any subsequent utility that expects to obtain them, 3721though this will be avoided wherever possible. 3722.It Fl d Ar delim 3723End the read when the first byte of 3724.Ar delim 3725is obtained from standard input. 3726The default end delimiter is 3727.Aq newline 3728.Pq Sq \en . 3729Specifying 3730.Qq 3731as 3732.Ar delim 3733causes the nul character 3734.Pq Sq \e0 3735to be the end delimiter. 3736If the delimiter is set to 3737.Aq backslash 3738.Pq Sq \&\e 3739then neither line continuation nor escaping are available. 3740The input will end when the first 3741.Aq backslash 3742is read. 3743.It Fl n Ar max 3744.Ic read 3745will read no more than 3746.Ar max 3747bytes from standard input. 3748The default is unlimited. 3749If the end 3750.Ar delim 3751has not been encountered within 3752.Ar max 3753bytes, and EOF has not been reached, 3754.Ic read 3755will act as if the delimiter immediately followed 3756the 3757.Ar max Ns 'th 3758byte, without attempting to obtain it. 3759However, even if the 3760.Fl r 3761option is not given and the final byte actually read 3762were the escape character (not itself escaped), 3763no more bytes will be read, and that escape 3764character would simply be removed as described below. 3765.It Fl p Ar prompt 3766If the standard input is a terminal, then 3767.Ar prompt 3768is written to standard error before the read commences. 3769If more lines of data are required in that case, the 3770normal 3771.Ev PS2 3772prompt is written as each subsequent line is to be obtained. 3773.It Fl r 3774Reduced processing of the input. 3775No escape characters are recognised, 3776and line continuation is not performed. 3777See below. 3778.El 3779.Pp 3780If the read is from a terminal device, 3781and the 3782.Fl p 3783option was given, 3784.Ar prompt 3785is printed on standard error. 3786Then a record, terminated by the first character of 3787.Ar delim 3788if the 3789.Fl d 3790option was given, or a 3791.Aq newline 3792.Pq Sq \en 3793character otherwise, 3794but no longer than 3795.Ar max 3796bytes if the 3797.Fl n 3798option was given, 3799is read from the standard input. 3800If the 3801.Fl b 3802option is not given, no data from standard 3803input beyond the end delimiter, or the 3804.Ar max 3805bytes that may be read, 3806whichever occurs first, 3807are obtained. 3808Any nul characters 3809.Pq Sq \e0 3810encountered in the input stream, 3811other than when being the delimiter if 3812.Fl d Qq 3813was used, 3814are simply ignored, even if escaped (in which case the 3815preceding 3816.Sq \e 3817is also ignored) though these ignored characters are 3818included in the byte count for the purposes of the 3819.Fl n 3820option. 3821.Pp 3822If the 3823.Fl r 3824option was not given, 3825and the two character sequence 3826.Sq \&\e 3827.Sq \en 3828is encountered, 3829those two characters are simply deleted, 3830and provided that 3831.Ar max 3832bytes have not yet been obtained, 3833and the end delimiter has yet to be encountered, 3834more input is obtained, 3835with the first character of the following line 3836placed in the input where the deleted 3837.Sq \e 3838had been. 3839This allows logical lines longer than the maximum line 3840length permitted for text files to be processed. 3841The two removed characters are still counted 3842for the purposes of the 3843.Ar max 3844input limit. 3845.Pp 3846If the 3847.Fl r 3848flag was not given, the 3849.Aq backslash 3850character 3851.Pq Sq \e 3852character is then treated as an escape character, 3853the character following it, if not 3854.Sq \e0 , 3855is always treated as a normal, 3856insignificant, data character, 3857and is never treated as the end delimiter nor as 3858an IFS character for field splitting. 3859.Pp 3860After field splitting has completed, 3861but before data has been 3862assigned to any variables, 3863all escape characters are removed. 3864Note that the two character sequence 3865.Sq \&\e 3866.Sq \&\e 3867can be used to enter the escape character as data, 3868the first acts as the escape character, the second 3869becomes just a normal data character. 3870.Pp 3871The ending delimiter, if encountered, and not escaped, 3872is deleted from the record which is then split as described 3873in the field splitting section of the 3874.Sx Word Expansions 3875section above. 3876The pieces (fields) are assigned to the 3877.Ar variable Ns s 3878in order. 3879If there are more pieces than variables, 3880the remaining pieces 3881(along with the characters in 3882.Ev IFS 3883that separated them) are all assigned to the last 3884.Ar variable . 3885If there are more variables than pieces, 3886the remaining variables are assigned the null string. 3887.Pp 3888The 3889.Ic read 3890built-in utility will indicate success (exit status 0) 3891unless EOF, or a read error, 3892is encountered on input, before encountering the delimiter, 3893or having read 3894.Ar max 3895bytes. 3896In this case any data previously read will be assigned to 3897the variables, as if the delimiter had been located at that 3898point, and 3899.Ic read 3900will exit with status 1. 3901If there is a usage error (unknown option, etc) 3902no variables will be altered, 3903.Ic read 3904will issue a diagnostic to standard error, 3905and exit with a status greater than 1. 3906.Pp 3907The 3908.Fl b 3909and 3910.Fl n 3911options are not available in SMALL shells. 3912.\" 3913.Pp 3914.It Ic readonly Ar name Ns Oo =value Oc ... 3915.It Ic readonly Oo Fl p Oo Ar name ... Oc Oc 3916.It Ic readonly Fl q Ar name ... 3917With no options, 3918the specified names are marked as read only, so that they cannot be 3919subsequently modified or unset. 3920The shell allows the value of a variable 3921to be set at the same time it is marked read only by writing 3922.Pp 3923.Dl readonly name=value 3924.Pp 3925where the value often needs to be quoted, as explained for the 3926.Ic export 3927command. 3928.Pp 3929With no arguments the 3930.Ic readonly 3931command lists the names of all set read only variables. 3932With the 3933.Fl p 3934option specified, 3935the output will be formatted suitably for non-interactive use, 3936and unset variables are included. 3937When the 3938.Fl p 3939option is given, 3940a list of variable names (without values) may also be specified, 3941in which case output is limited to the named variables. 3942.Pp 3943With the 3944.Fl q 3945option, the 3946.Ic readonly 3947command tests the read-only status of the variables listed 3948and exits with status 0 if all named variables are read-only, 3949or with status 1 if any are not read-only. 3950.Pp 3951Other than as specified for 3952.Fl q 3953the 3954.Ic readonly 3955command normally exits with status 0. 3956In all cases, if an unknown option, or an invalid option combination, 3957or an invalid variable name, is given; 3958or a variable which was already read-only is attempted to be set; 3959the exit status will not be zero, a diagnostic 3960message will be written to the standard error output, 3961and a non-interactive shell will terminate. 3962.\" 3963.Pp 3964.It Ic return Op Ar n 3965Stop executing the current function or a dot command with return value of 3966.Ar n 3967or the value of the last executed command, if not specified. 3968For portability, 3969.Ar n 3970should be in the range from 0 to 255. 3971.Pp 3972The POSIX standard says that the results of 3973.Ic return 3974outside a function or a dot command are unspecified. 3975This implementation treats such a return as a no-op with a return value of 0 3976(success, true). 3977Use the 3978.Ic exit 3979command instead, if you want to return from a script or exit 3980your shell. 3981.\" 3982.Pp 3983.It Ic set 3984.It Ic set No { Fl o | Cm +o No } 3985.It Ic set No { Fl options | Cm +options | Fl o Ar opt | Cm +o Ar opt } ... Oo Cm \-\|\- Oc Oo Ar arg ... Oc 3986.It Ic set \-\|\- Oo Ar arg ... Oc 3987.Pp 3988The 3989.Ic set 3990command performs four different functions. 3991.Pp 3992With no arguments, 3993.Ic set 3994lists the names and values of all set shell variables. 3995.Pp 3996With a single option of either 3997.Dq Fl o 3998or 3999.Dq Cm +o 4000.Ic set 4001outputs the current values of the options. 4002In the 4003.Fl o 4004form, all options are listed, with their current values. 4005In the 4006.Cm +o 4007form, the shell outputs a string that can later be used 4008as a command to reset all options to their current values. 4009.Pp 4010If options are given, 4011.Nm 4012sets the specified option flags, 4013or clears them as described in the 4014.Sx Argument List Processing 4015section. 4016Note that not all options available on the command 4017line are available to the 4018.Ic set 4019built-in command. 4020However, in addition to the options listed there, 4021when the 4022.Dq "option name" 4023.Pq Ar opt 4024given to 4025.Ic set Fl o 4026is 4027.Cm default 4028all of the options are reset to the values they had immediately 4029after 4030.Nm 4031initialization, before any startup scripts, or other input, had been processed. 4032While this may be of use to users or scripts, its primary purpose 4033is for use in the output of 4034.Dq Ic set Cm +o , 4035to avoid that command needing to list every available option. 4036There is no 4037.Cm +o default . 4038.Pp 4039The fourth use of the 4040.Ic set 4041command is to set the values of the shell's 4042positional parameters to the specified arguments. 4043To change the positional 4044parameters with no possibility of changing any options, use 4045.Dq \-\|\- 4046as the first argument to 4047.Ic set . 4048If no following 4049.Ar arg Ns s 4050are present, the 4051.Ic set 4052command 4053will clear all the positional parameters (equivalent to executing 4054.Dq Li shift $# . ) 4055Otherwise the following 4056.Ar arg Ns s 4057become 4058.Li \&$1 , 4059.Li \&$2 , 4060\&..., 4061and 4062.Li \&$# 4063is set to the number of 4064.Ar arg Ns s 4065present. 4066The third and fourth forms may be combined, to set options, 4067and the positional parameters, in one operation. 4068Note that if it is possible that no 4069.Ar arg Ns uments 4070might be present, 4071or if the first 4072.Ar arg 4073might begin with a minus 4074.Pq Sq \&\- 4075then the 4076.Dq \-\|\- 4077is required to distinguish this case from the first 4078and third variants of this command, and an 4079.Ar arg 4080beginning with 4081.Sq \&\- 4082from being an attempt to set options. 4083.\" 4084.Pp 4085.It Ic setvar Ar variable Ar value 4086Assigns 4087.Ar value 4088to 4089.Ar variable . 4090(In general it is better to write 4091.Li variable=value 4092rather than using 4093.Ic setvar . 4094.Ic setvar 4095is intended to be used in 4096functions that assign values to variables whose names are passed as 4097parameters.) 4098.\" 4099.Pp 4100.It Ic shift Op Ar n 4101If 4102.Ar n , 4103which must be a decimal integer, 4104is omitted, 1 is assumed. 4105.Pp 4106If 4107.Ar n 4108is unsigned 4109.Pq or omitted 4110shift the positional parameters 4111.Ar n 4112times. 4113Each 4114.Ic shift 4115sets the value of 4116.Li $1 4117to the previous value of 4118.Li $2 , 4119the value of 4120.Li $2 4121to the previous value of 4122.Li $3 , 4123and so on, decreasing 4124the value of 4125.Li $# 4126by one. 4127The shift count 4128.Pq Ar n 4129must be less than or equal to the number of 4130positional parameters 4131.Pq Dq Li $# 4132before the shift. 4133A shift of 4134.Li $# 4135positions is equivalent to 4136.Dq Li set\ Ns Fl Fl 4137and results in unsetting all of the positional parameters 4138and setting 4139.Li $# 4140to zero. 4141The command 4142.Dq Li shift\ 0 4143does not alter 4144.Li $# 4145or any of the positional parameters. 4146.Pp 4147If 4148.Ar n 4149is negative, then the 4150.Ic shift 4151becomes a clockwise rotation, 4152.Ar \&\-n 4153times. 4154The absolute value of 4155.Ar n 4156must be less than or equal to 4157.Li $# 4158.Pq the number of set positional parameters . 4159Each rotation sets the value of 4160.Li $1 4161to the previous value of 4162.Li ${$#} 4163(if that were valid syntax) \(en the previous last positional parameter, 4164sets 4165.Li $2 4166to the previous value of 4167.Li $1 , 4168the value of 4169.Li $3 4170to the previous value of 4171.Li $2 , 4172and so on, with the new last positional parameter becoming 4173what was previously the penultimate positional parameter. 4174The value of 4175.Li $# 4176is not altered. 4177Shifts of 4178.Li \&\-0 4179and 4180.Li \&\-$# 4181are no-ops. 4182The command sequence: 4183.Dl shift\ \-n;\ shift\ n 4184unsets the final 4185.Ar n 4186positional parameters. 4187.Pp 4188An anti-clockwise rotation of 4189.Ar n 4190places 4191.Pq 0\ <=\ Ns Ar n Ns \ <=\ $# 4192can be achieved using 4193.Dq Li shift\ \-$(($#\ \-\ n)) . 4194The command 4195.Dq Li shift\ \-$(($#\ \-\ 1)) 4196is equivalent to, but much faster than: 4197.Dl set Fl Fl \&\ Ns Do $@ Dc Do $1 Dc ; shift 1 4198.\" 4199.Pp 4200The exit status is 0 if no error occurs, otherwise greater than 0. 4201.Pp 4202.It Ic specialvar Ar variable ... 4203For each 4204.Ar variable 4205name given, 4206if the variable named is one which, 4207in this 4208.Nm , 4209could be treated as a special variable, 4210then cause that 4211.Ar variable 4212to be made special, undoing any effects of an earlier 4213.Ic unset 4214or assignment to the variable. 4215If all 4216.Ar variable Ns s 4217given are recognized special variables in this 4218.Nm 4219the 4220.Ic specialvar 4221command will exit with status 0, otherwise 1. 4222Invalid usage will result in an exit status of 2. 4223.Pp 4224Note that all variables capable of being special are created 4225that way, this command is not required to cause that to happen. 4226However should such a variable be imported from the environment, 4227that will cause (for those special variables so designated) 4228the special effects for that variable to be lost. 4229Consequently, as the contents of the environment cannot be controlled, 4230any script which desires to make use of the properties 4231of most of the special variables should use this command, 4232naming the variables required, 4233to ensure that their special properties are available. 4234.\" 4235.Pp 4236.It Ic suspend Oo Fl fg Oc Oo Fl s Ar sig Oc Oo Ar pid Ns \&| Ns Ar job ... Oc 4237Causes the processes or jobs indicated to be suspended, if possible. 4238If no 4239.Ar pid 4240or 4241.Ar job 4242arguments are given, or if a 4243.Ar pid 4244argument refers to the shell itself, and if the 4245.Ic suspend 4246command is issued in a shell that is not a login shell, 4247has job control enabled, 4248and is not executing in a subshell environment, 4249then the shell will suspend itself. 4250The 4251.Fl f 4252(force) option causes those checks to be ignored, 4253the shell, when instructed to suspend itself with force, 4254will always attempt to do so, which may result in a subshell 4255environment becoming suspended. 4256.Pp 4257The 4258.Fl g 4259option indicates that each 4260.Ar pid 4261argument is to be treated as a process group identifier, 4262or if no targets are given, the current process group of the shell, 4263and that process group will be suspended, instead of just 4264the process identified. 4265This option is implied, for the one agument only, by use of a 4266.Ar job 4267specifier. 4268Note that, unlike other built-in commands, use of a 4269.Ar pid 4270argument causes only that process to be suspended, 4271even if that 4272.Ar pid 4273happens to be the process leader of a job, or another 4274process in a job. 4275.Pp 4276The 4277.Fl s Ar sig 4278option cause the signal 4279.Ar sig 4280to be used to suspend the process, or process group. 4281Only the signals that, by default, cause processes to be 4282suspended 4283.Pq Dv STOP Dv TSTP Dv TTIN No and Dv TTOU 4284are permitted. 4285The default is 4286.Dv SIGTSTP . 4287Note that except when 4288.Dv SIGSTOP 4289is sent, the target process can arrange to catch or 4290ignore the signal, and perhaps not become suspended, 4291if it so desires. 4292Interactive processes that suport job control 4293(eg: shells) 4294generally ignore those signals. 4295.Pp 4296The 4297.Ic suspend 4298command exits with status 0, except if an error occurs, 4299in which case it exits with a status greater than 0. 4300Possible errors include usage errors; 4301attempting to suspend the shell itself, when not 4302permitted and without the 4303.Fl f 4304option; 4305a target process or job not existing; 4306insufficient prvileges to signal the target process or job; 4307and more. 4308It is not an error if the target process decides not to comply 4309with a request to suspend itself. 4310.Pp 4311.It Ic times 4312Prints two lines to standard output. 4313Each line contains two accumulated time values, expressed 4314in minutes and seconds (including fractions of a second.) 4315The first value gives the user time consumed, the second the system time. 4316.Pp 4317The first output line gives the CPU and system times consumed by the 4318shell itself. 4319The second line gives the accumulated times for children of this 4320shell (and their descendants) which have exited, and then been 4321successfully waited for by the relevant parent. 4322See 4323.Xr times 3 4324for more information. 4325.Pp 4326.Ic times 4327has no parameters, and exits with an exit status of 0 unless 4328an attempt is made to give it an option. 4329.\" 4330.Pp 4331.It Ic trap Ar action signal ... 4332.It Ic trap \- 4333.It Ic trap Op Fl l 4334.It Ic trap Fl p Oo Ar signal ... Oc 4335.It Ic trap Fl P Ar signal ... 4336.It Ic trap Ar N signal ... 4337.Pp 4338Cause the shell to parse and execute action when any of the specified 4339signals are received. 4340The signals are specified by signal number or as the name of the signal. 4341If 4342.Ar signal 4343is 4344.Li 0 \" $0 4345or its equivalent, 4346.Li EXIT , 4347the action is executed when the shell exits. 4348The 4349.Ar action 4350may be a null (empty) string, 4351which causes the specified signals to be ignored. 4352With 4353.Ar action 4354set to 4355.Sq Li - 4356the specified signals are set to their default actions. 4357If the first 4358.Ar signal 4359is specified in its numeric form, then 4360.Ar action 4361can be omitted to achieve the same effect. 4362This archaic, 4363but still standard, 4364form should not be relied upon, use the explicit 4365.Sq Li - 4366action. 4367If no signals are specified with an action of 4368.Sq Li - , 4369all signals are reset. 4370.Pp 4371When the shell forks off a sub-shell, it resets trapped (but not ignored) 4372signals to the default action. 4373On non-interactive shells, the 4374.Ic trap 4375command has no effect on signals that were 4376ignored on entry to the shell. 4377On interactive shells, the 4378.Ic trap 4379command will catch or reset signals ignored on entry. 4380.Pp 4381Issuing 4382.Ic trap 4383with option 4384.Fl l 4385will print a list of valid signal names. 4386.Ic trap 4387without any arguments causes it to write a list of signals and their 4388associated non-default actions to the standard output in a format 4389that is suitable as an input to the shell that achieves the same 4390trapping results. 4391With the 4392.Fl p 4393flag, trap prints the same information for the signals specified, 4394or if none are given, for all signals, including those where the 4395action is the default. 4396The 4397.Fl P 4398flag is similar, but prints only the action(s) associated with the 4399named signals, at least (and usually only) one of which must be given. 4400Nothing is printed if the action is the default, 4401an empty line is printed for ignored signals. 4402These variants of the trap command may be executed in a sub-shell 4403.Pq "such as in a command substitution" , 4404provided they appear as the initial sequence of commands in that sub-shell, 4405in which case the state of traps from the parent of that 4406sub-shell is reported. 4407.Pp 4408Examples: 4409.Pp 4410.Dl trap 4411.Pp 4412List trapped signals and their corresponding actions. 4413.Pp 4414.Dl trap -l 4415.Pp 4416Print a list of valid signals. 4417.Pp 4418.Dl trap '' INT QUIT tstp 30 4419.Pp 4420Ignore signals INT QUIT TSTP USR1. 4421.Pp 4422.Dl trap date INT 4423.Pp 4424Run the 4425.Dq date 4426command (print the date) upon receiving signal INT. 4427.Pp 4428.Dl trap HUP INT 4429.Pp 4430Run the 4431.Dq HUP 4432command, or function, upon receiving signal INT. 4433.Pp 4434.Dl Ic eval Qo \&$( trap -P QUIT \&) Qc 4435.Pp 4436Parse and execute the action that would be invoked were a 4437.Dv SIGQUIT 4438received. 4439.Pp 4440.Dl trap 1 2 4441.Pp 4442Reset the actions for signals 1 (HUP) and 2 (INT) to their defaults. 4443.Bd -literal -offset indent 4444traps=$(trap -p) 4445 # more commands ... 4446trap 'action' SIG 4447 # more commands ... 4448eval "$traps" 4449.Ed 4450.Pp 4451Save the trap status, execute commands, changing some traps, 4452and then reset all traps to their values at the start of the sequence. 4453The 4454.Fl p 4455option is required in the first command here, 4456or any signals that were previously 4457untrapped (in their default states) 4458and which were altered during the intermediate code, 4459would not be reset by the final 4460.Ic eval . 4461.\" 4462.Pp 4463.It Ic type Op Ar name ... 4464Interpret each 4465.Ar name 4466as a command and print the resolution of the command search. 4467Possible resolutions are: 4468shell keyword, alias, shell built-in, 4469command, tracked alias and not found. 4470For aliases the alias expansion is 4471printed; for commands and tracked aliases the complete pathname of the 4472command is printed. 4473.\" 4474.Pp 4475.It Ic ulimit Oo Fl H Ns \*(Ba Ns Fl S Oc Op Fl a \*(Ba Fl btfdscmlrpnv Op Ar value 4476Inquire about or set the hard or soft limits on processes or set new 4477limits. 4478The choice between hard limit (which no process is allowed to 4479violate, and which may not be raised once it has been lowered) and soft 4480limit (which causes processes to be signaled but not necessarily killed, 4481and which may be raised) is made with these flags: 4482.Bl -tag -width Fl 4483.It Fl H 4484set or inquire about hard limits 4485.It Fl S 4486set or inquire about soft limits. 4487.El 4488.Pp 4489If neither 4490.Fl H 4491nor 4492.Fl S 4493is specified, the soft limit is displayed or both limits are set. 4494If both are specified, 4495then with 4496.Fl a 4497both are displayed, the soft followed by the hard limit, 4498otherwise for setting, both limits are set, 4499and for interrogating the soft limit is displayed. 4500.Pp 4501The limit to be interrogated or set, then, is chosen by specifying 4502any one of these flags: 4503.Bl -tag -width Fl 4504.It Fl a 4505show all the current limits (it is an error to 4506attempt to set the limits by giving a 4507.Ar value ) 4508.It Fl b 4509the socket buffer size of a process (bytes) 4510.It Fl c 4511the largest core dump size that can be produced 4512(512-byte blocks) 4513.It Fl d 4514the data segment size of a process (kilobytes) 4515.It Fl f 4516the largest file that can be created 4517(512-byte blocks) 4518.It Fl l 4519how much memory a process can lock with 4520.Xr mlock 2 4521(kilobytes) 4522.It Fl m 4523the total physical memory that can be 4524in use by a process (kilobytes) 4525.It Fl n 4526the number of files a process can have open at once 4527.It Fl p 4528the number of processes this user can 4529have at one time 4530.It Fl r 4531the number of threads this user can 4532have at one time 4533.It Fl s 4534the stack size of a process (kilobytes) 4535.It Fl t 4536CPU time (seconds) 4537.It Fl v 4538how large a process address space can be 4539.El 4540.Pp 4541If none of these is specified, it is the limit on file size that is shown 4542or set. 4543If value is specified, the limit is set to that number; otherwise 4544the current limit is displayed. 4545.Pp 4546Limits of an arbitrary process can be displayed or set using the 4547.Xr sysctl 8 4548utility. 4549.\" 4550.Pp 4551.It Ic umask Oo Fl S Oc Op Ar mask 4552Set the value of umask (see 4553.Xr umask 2 ) 4554to the specified octal value. 4555If the argument is omitted, the umask value is printed. 4556With 4557.Fl S 4558a symbolic form is used instead of an octal number. 4559.\" 4560.Pp 4561.It Ic unalias Oo Fl a Oc Op Ar name 4562If 4563.Ar name 4564is specified, the shell removes that alias. 4565If 4566.Fl a 4567is specified, all aliases are removed. 4568.\" 4569.Pp 4570.It Ic unset Oo Fl efvx Oc Ar name ... 4571If 4572.Fl v 4573is specified, the specified variables are unset and unexported. 4574Readonly variables cannot be unset. 4575If 4576.Fl f 4577is specified, the specified functions are undefined. 4578If 4579.Fl e 4580is given, the specified variables are unexported, but otherwise unchanged, 4581alternatively, if 4582.Fl x 4583is given, the exported status of the variable will be retained, 4584even after it is unset. 4585.Pp 4586If no flags are provided 4587.Fl v 4588is assumed. 4589If 4590.Fl f 4591is given with one of the other flags, 4592then the named variables will be unset, or unexported, and functions 4593of the same names will be undefined. 4594The 4595.Fl e 4596and 4597.Fl x 4598flags both imply 4599.Fl v . 4600If 4601.Fl e 4602is given, the 4603.Fl x 4604flag is ignored. 4605.Pp 4606The exit status is 0, unless an attempt was made to unset 4607a readonly variable, in which case the exit status is 1. 4608It is not an error to unset (or undefine) a variable (or function) 4609that is not currently set (or defined.) 4610.\" 4611.Pp 4612.It Ic wait Oo Fl n Oc Oo Fl p Ar var Oc Op Ar job ... 4613Wait for the specified jobs to complete 4614and return the exit status of the last job in the parameter list, 4615or 127 if that job is not a current child of the shell. 4616.Pp 4617If no 4618.Ar job 4619arguments are given, wait for all jobs to 4620complete and then return an exit status of zero 4621(including when there were no jobs, and so nothing exited.) 4622.Pp 4623With the 4624.Fl n 4625option, wait instead for any one of the given 4626.Ar job Ns s, 4627or if none are given, any job, to complete, and 4628return the exit status of that job. 4629If none of the given 4630.Ar job 4631arguments is a current child of the shell, 4632or if no 4633.Ar job 4634arguments are given and the shell has no unwaited for children, 4635then the exit status will be 127. 4636.Pp 4637The 4638.Fl p Ar var 4639option allows the process (or job) identifier of the 4640job for which the exit status is returned to be obtained. 4641The variable named (which must not be readonly) will be 4642unset initially, then if a job has exited and its status is 4643being returned, set to the identifier from the 4644arg list (if given) of that job, 4645or the lead process identifier of the job to exit when used with 4646.Fl n 4647and no job arguments. 4648Note that 4649.Fl p 4650with neither 4651.Fl n 4652nor 4653.Ar job 4654arguments is useless, as in that case no job status is 4655returned, the variable named is simply unset. 4656.Pp 4657If the wait is interrupted by a signal, 4658its exit status will be greater than 128, 4659and 4660.Ar var , 4661if given, will remain unset. 4662.Pp 4663Once waited upon, by specific process number or job-id, 4664or by a 4665.Ic wait 4666with no arguments, 4667knowledge of the child is removed from the system, 4668and it cannot be waited upon again. 4669.Pp 4670Note than when a list of jobs are given, more that 4671one argument might refer to the same job. 4672In that case, if the final argument represents a job 4673that is also given earlier in the list, it is not 4674defined whether the status returned will be the 4675exit status of the job, or 127 indicating that 4676the child no longer existed when the wait command 4677reached the later argument in the list. 4678In this 4679.Nm 4680the exit status will be that from the job. 4681.Nm 4682waits for each job exactly once, regardless of 4683how many times (or how many different ways) it 4684is listed in the arguments to 4685.Ic wait . 4686That is 4687.Bd -literal -offset indent -compact 4688wait 100 100 100 4689.Ed 4690is identical to 4691.Bd -literal -offset indent -compact 4692wait 100 4693.Ed 4694.El 4695.\" 4696.\" 4697.Ss Job Control 4698.\" 4699Each process (or set of processes) started by 4700.Nm 4701is created as a 4702.Dq job 4703and added to the jobs table. 4704When enabled by the 4705.Fl m 4706option 4707.Pq aka Fl o Cm monitor 4708when the job is created, 4709.Nm 4710places each job (if run from the top level shell) 4711into a process group of its own, which allows control 4712of the process(es), and its/their descendants, as a unit. 4713When the 4714.Fl m 4715option is off, or when started from a sub-shell environment, 4716jobs share the same process group as the parent shell. 4717The 4718.Fl m 4719option is enabled by default in interactive shells with 4720a terminal as standard input and standard error. 4721.Pp 4722Jobs with separate process groups may be stopped, and then later 4723resumed in the foreground (with access to the terminal) 4724or in the background (where attempting to read from the 4725terminal will result in the job stopping.) 4726A list of current jobs can be obtained using the 4727.Ic jobs 4728built-in command. 4729Jobs are identified using either the process identifier 4730of the lead process of the job (the value available in 4731the special parameter 4732.Dq Dv \&! 4733if the job is started in the background), or using percent 4734notation. 4735Each job is given a 4736.Dq job number 4737which is a small integer, starting from 1, and can be 4738referenced as 4739.Dq Li \&% Ns Ar n 4740where 4741.Ar n 4742is that number. 4743Note that this applies to jobs both with and without their own process groups. 4744Job numbers are shown in the output from the 4745.Ic jobs 4746command enclosed in brackets 4747.Po 4748.Sq Li \&[ 4749and 4750.Sq Li \&] 4751.Pc . 4752Whenever the job table becomes empty, the numbers begin at one again. 4753In addition, there is the concept of a current, and a previous job, 4754identified by 4755.Dq Li \&%+ 4756.Po 4757or 4758.Dq Li \&%% 4759or even just 4760.Dq Li \&% 4761.Pc , 4762and a previous job, identified by 4763.Dq Li \&%\- . 4764Whenever a background job is started, 4765or a job is resumed in the background, 4766it becomes the current job. 4767The job that was the current job 4768(prepare for a big surprise here, drum roll..., wait for it...\&) 4769becomes the previous job. 4770When the current job terminates, the previous job is 4771promoted to be the current job. 4772In addition the form 4773.Dq Li \&% Ns Ar string\^ 4774finds the job for which the command starts with 4775.Ar string 4776and the form 4777.Dq Li \&%? Ns Ar string\^ 4778finds the job which contains the 4779.Ar string 4780in its command somewhere. 4781Both forms require the result to be unambiguous. 4782For this purpose the 4783.Dq command 4784is that shown in the output from the 4785.Ic jobs 4786command, not the original command line. 4787.Pp 4788The 4789.Ic bg , 4790.Ic fg , 4791.Ic jobid , 4792.Ic jobs , 4793.Ic kill , 4794.Ic suspend , 4795and 4796.Ic wait 4797commands all accept job identifiers as arguments, in addition to 4798process identifiers (larger integers). 4799See the 4800.Sx Built-ins 4801section above, and 4802.Xr kill 1 , 4803for more details of those commands. 4804In addition, a job identifier 4805(using one of the 4806.Dq \&% forms ) 4807issued as a command, without arguments, is interpreted as 4808if it had been given as the argument to the 4809.Ic fg 4810command. 4811.Pp 4812To cause a foreground process to stop, enter the terminal's 4813.Ic stop 4814character (usually control-Z). 4815To cause a background process to stop, 4816use the 4817.Ic suspend 4818built in command, or 4819send it a 4820.Dv STOP 4821signal, using the kill command. 4822A useful function to define is 4823.Bd -literal -offset indent 4824stop() { kill -s STOP "${@:-%%}"; } 4825.Ed 4826.Pp 4827The 4828.Ic fg 4829command resumes a stopped job, placing it in the foreground, 4830and 4831.Ic bg 4832resumes a stopped job in the background. 4833The 4834.Ic jobid 4835command provides information about process identifiers, job identifiers, 4836and the process group identifier, for a job. 4837.Pp 4838Whenever a sub-shell is created, the jobs table becomes invalid 4839(the sub-shell has no children.) 4840However, to enable uses like 4841.Bd -literal -offset indent 4842PID=$(jobid -p %1) 4843.Ed 4844.Pp 4845the table is only actually cleared in a sub-shell when needed to 4846create the first job there (built-in commands run in the foreground 4847do not create jobs.) 4848Note that in this environment, there is no useful current job 4849.Dq ( Li \&%% 4850actually refers to the sub-shell itself, but is not accessible) 4851but the job which is the current job in the parent can be accessed as 4852.Dq Li \&%\- . 4853.\" 4854.\" 4855.Ss Command Line Editing 4856.\" 4857When 4858.Nm 4859is being used interactively from a terminal, the current command 4860and the command history (see 4861.Ic fc 4862in the 4863.Sx Built-ins 4864section) 4865can be edited using emacs-mode or vi-mode command-line editing. 4866The command 4867.Ql set -o emacs 4868(or 4869.Fl E 4870option) 4871enables emacs-mode editing. 4872The command 4873.Ql set -o vi 4874(or 4875.Fl V 4876option) 4877enables vi-mode editing and places the current shell process into 4878vi insert mode. 4879(See the 4880.Sx Argument List Processing 4881section above.) 4882.Pp 4883The vi-mode uses commands similar to a subset of those described in the 4884.Xr vi 1 4885man page. 4886With vi-mode 4887enabled, 4888.Nm sh 4889can be switched between insert mode and command mode. 4890It's similar to 4891.Ic vi : 4892pressing the 4893.Aq ESC 4894key will throw you into vi command mode. 4895Insert mode is re-entered in any of the usual vi ways, 4896using the append (a) insert (i) substitute (s) (etc) commands. 4897Pressing the 4898.Aq return 4899key in either mode will pass the line to the shell. 4900.Pp 4901The emacs-mode uses commands similar to a subset available in the 4902.Ic emacs 4903editor. 4904With emacs-mode enabled, special keys can be used to modify the text 4905in the buffer using the control key. 4906.Pp 4907.Nm 4908uses the 4909.Xr editline 3 4910library. 4911See 4912.Xr editline 7 4913for a list of the possible command bindings, 4914and the default settings in emacs and vi modes. 4915Also see 4916.Xr editrc 5 4917for the commands that can be given to configure 4918.Xr editline 7 4919in the file named by the 4920.Ev EDITRC 4921parameter, 4922or a file used with the 4923.Ic inputrc 4924built-in command, 4925or using 4926.Xr editline 7 Ap s 4927configuration command line. 4928.Pp 4929When command line editing is enabled, the 4930.Xr editline 7 4931functions control printing of the 4932.Ev PS1 4933and 4934.Ev PS2 4935prompts when required. 4936As, in this mode, the command line editor needs to 4937keep track of what characters are in what position on 4938the command line, care needs to be taken when setting 4939the prompts. 4940Normal printing characters are handled automatically, 4941however mode setting sequences, which do not actually display 4942on the terminal, need to be identified to 4943.Xr editline 7 . 4944This is done, when needed, by choosing a character that 4945is not needed anywhere in the prompt, including in the mode 4946setting sequences, any single character is acceptable, 4947and assigning it to the shell parameter 4948.Dv PSlit . 4949Then that character should be used, in pairs, in the 4950prompt string. 4951Between each pair of 4952.Dv PSlit 4953characters are mode setting sequences, which affect the printing 4954attributes of the following (normal) characters of the prompt, 4955but do not themselves appear visibly, nor change the terminal's 4956cursor position. 4957.Pp 4958Each such sequence, that is 4959.Dv PSlit 4960character, mode setting character sequence, and another 4961.Dv PSlit 4962character, must currently be followed by at least one following 4963normal prompt character, or it will be ignored. 4964That is, a 4965.Dv PSlit 4966character cannot be the final character of 4967.Ev PS1 4968or 4969.Ev PS2 , 4970nor may two 4971.Dv PSlit 4972delimited sequences appear adjacent to each other. 4973Each sequence can contain as many mode altering sequences as are 4974required however. 4975Only the first character from 4976.Dv PSlit 4977will be used. 4978When set 4979.Dv PSlit 4980should usually be set to a string containing just one 4981character, then it can simply be embedded in 4982.Ev PS1 4983(or 4984.Ev PS2 ) 4985as in 4986.Pp 4987.D1 Li PS1=\*q${PSlit} Ns Ar mset\^ Ns Li ${PSlit}XYZ${PSlit} Ns Ar mclr\^ Ns Li ${PSlit}ABC\*q 4988.Pp 4989The prompt visible will be 4990.Dq XYZABC 4991with the 4992.Dq XYZ 4993part shown according as defined by the mode setting characters 4994.Ar mset , 4995and then cleared again by 4996.Ar mclr . 4997See 4998.Xr tput 1 4999for one method to generate appropriate mode sequences. 5000Note that both parts, XYZ and ABC, must each contain at least one 5001character. 5002.Pp 5003If 5004.Dv PSlit 5005is unset, which is its initial state, or set to a null string, 5006no literal character will be defined, 5007and all characters of the prompt strings will be assumed 5008to be visible characters (which includes spaces etc.) 5009To allow smooth use of prompts, without needing redefinition, when 5010.Xr editline 7 5011is disabled, the character chosen should be one which will be 5012ignored by the terminal if received, as when 5013.Xr editline 7 5014is not in use, the prompt strings are simply written to the terminal. 5015For example, setting: 5016.\" XXX: PS1 line is too long for -offset indent 5017.Bd -literal -offset left 5018 PSlit="$(printf\ '\e1')" 5019 PS1="${PSlit}$(tput\ bold\ blink)${PSlit}\e$${PSlit}$(tput\ sgr0)${PSlit}\ " 5020.Ed 5021.Pp 5022will arrange for the primary prompt to be a bold blinking dollar sign, 5023if supported by the current terminal, followed by an (ordinary) space, 5024and, as the SOH (control-A) character 5025.Pq Sq \e1 5026will not normally affect 5027a terminal, this same prompt will usually work with 5028.Xr editline 7 5029enabled or disabled. 5030.Sh ENVIRONMENT 5031.Bl -tag -width MAILCHECK 5032.It Ev CDPATH 5033The search path used with the 5034.Ic cd 5035built-in. 5036.It Ev EDITRC 5037Gives the name of the file containing commands for 5038.Xr editline 7 . 5039See 5040.Xr editrc 5 5041for possible content and format. 5042The file is processed, when in interactive mode with 5043command line editing enabled, whenever 5044.Ev EDITRC 5045is set (even with no actual value change,) 5046and if command line editing changes from disabled to enabled, 5047or the editor style used is changed. 5048(See the 5049.Fl E 5050and 5051.Fl V 5052options of the 5053.Ic set 5054built-in command, described in 5055.Sx Built-ins 5056above, which are documented further above in 5057.Sx Argument List Processing . ) 5058If unset 5059.Dq $HOME/.editrc 5060is used. 5061.It Ev ENV 5062Names the file sourced at startup by the shell. 5063Unused by this shell after initialization, 5064but is usually passed through the environment to 5065descendant shells. 5066See the 5067.Sx Invocation 5068section above for details of how 5069.Ev ENV 5070is processed and used. 5071.It Ev EUSER 5072Set to the login name of the effective user id running the shell, 5073as returned by 5074.Bd -literal -offset indent -compact 5075getpwuid(geteuid())->pw_name 5076.Ed 5077.Po 5078See 5079.Xr getpwuid 3 5080and 5081.Xr geteuid 2 5082for more details. 5083.Pc 5084This is obtained each time 5085.Ev EUSER 5086is expanded, so changes to the shell's execution identity 5087cause updates without further action. 5088If unset, it returns nothing. 5089If set it loses its special properties, and is simply a variable. 5090See the 5091.Ic specialvar 5092built-in command for remedial action. 5093.It Ev HISTAPPEND 5094If set to one of 5095.Ql true , 5096.Ql yes , 5097.Ql on , 5098or an integral value greater than zero, 5099and if 5100.Ev HISTFILE 5101is also set, and is a valid history file, 5102then as commands are read and added to the 5103history buffer, they are also written to the 5104.Ev HISTFILE 5105named. 5106.It Ev HISTFILE 5107When assigned to in an interactive shell 5108the contents of the file named by expanding 5109the new value of 5110.Ev HISTFILE 5111will, if it exists, 5112can be opened for reading, 5113and is a suitable 5114.Nm 5115history file (one previously written by 5116.Nm ) , 5117be read into the history buffer, 5118appending its contents to any existing history entries. 5119If 5120.Ev HISTFILE 5121is set when 5122.Nm 5123exits, 5124after any EXIT trap has been evaluated, 5125and if 5126.Ev HISTAPPEND 5127is not enabled, 5128or if 5129.Ev HISTFILE 5130is assigned when HISTAPPEND is enabled, 5131or if 5132.Ev HISTAPPEND 5133is enabled when 5134.Ev HISTFILE 5135is set, 5136the contents of the history buffer will be written 5137to the file named after expanding this variable. 5138If the file named did not previously exist, it will be created. 5139If it did exist, it must be writable. 5140The file will be truncated, and then if owned by the current user, 5141the current history buffer will be written to it. 5142.Pp 5143When used for reading or writing history entries, 5144variable and arithmetic expansions are performed, 5145upon its value to produce a file name, and if the 5146.Ev HISTFILE 5147variable was set by this shell, 5148rather than obtained from the environment, 5149command substitutions will also be performed. 5150No file will be used if an expansion error occurs, 5151or if there is a command substitution in a value obtained 5152from the environment. 5153.It Ev HISTSIZE 5154The number of lines in the history buffer for the shell. 5155If unset, or set to an empty string, 100 lines will be used. 5156Attempts to set HISTSIZE to anything other than a string of 5157digits will generate an error. 5158An invalid value found in the environment will be ignored. 5159.It Ev HOME 5160Set automatically by 5161.Xr login 1 5162from the user's login directory in the password file 5163.Pq Xr passwd 5 . 5164This environment variable also functions as the default argument for the 5165.Ic cd 5166built-in, and as the value of a tilde expansion without a user name. 5167.It Ev HOSTNAME 5168Set to the current hostname of the system, as returned by 5169.Xr gethostname 3 . 5170This is obtained each time 5171.Ev HOSTNAME 5172is expanded, so changes to the system's name are reflected 5173without further action. 5174If unset, it returns nothing. 5175If set it loses its special properties, and is simply a variable. 5176See the 5177.Ic specialvar 5178built-in command for remedial action. 5179.It Ev IFS 5180Input Field Separators. 5181This is normally set to 5182.Aq space , 5183.Aq tab , 5184and 5185.Aq newline . 5186See the 5187.Sx Field Splitting 5188section for more details. 5189.It Ev LANG 5190The string used to specify localization information that allows users 5191to work with different culture-specific and language conventions. 5192See 5193.Xr nls 7 . 5194.It Dv LINENO 5195The current line number in the script or function. 5196See the section 5197.Sx Using Dv LINENO 5198below for more details. 5199.It Ev MAIL 5200The name of a mail file, that will be checked for the arrival of new mail. 5201Overridden by 5202.Ev MAILPATH . 5203The check occurs just before 5204.Ev PS1 5205is written, immediately after reporting jobs which have changed status, 5206in interactive shells only. 5207New mail is considered to have arrived if the monitored file 5208has increased in size since the last check. 5209.\" .It Ev MAILCHECK 5210.\" The frequency in seconds that the shell checks for the arrival of mail 5211.\" in the files specified by the 5212.\" .Ev MAILPATH 5213.\" or the 5214.\" .Ev MAIL 5215.\" file. 5216.\" If set to 0, the check will occur at each prompt. 5217.It Ev MAILPATH 5218A colon 5219.Dq \&: 5220separated list of file names, for the shell to check for incoming mail. 5221This environment setting overrides the 5222.Ev MAIL 5223setting. 5224There is a maximum of 10 mailboxes that can be monitored at once. 5225.It Ev NBSH_INVOCATION 5226When 5227.Nm 5228starts, after it has processed its arguments, 5229and imported variables from the environment, 5230this variable is set to a string of one or more 5231characters which indicate the way the command line 5232was processed. 5233This is intended to be used in the startup 5234scripts 5235.Pq see Sx Invocation 5236to allow them to determine what actions are 5237appropriate to take. 5238.Ev NBSH_INVOCATION 5239is marked 5240.Dq not to be exported . 5241Apart from the way it is initialized, 5242and that it overrides any value that may 5243have been set in the environment, 5244there is nothing special about it. 5245It can be unset, or altered, 5246with no ramifications, 5247other than whatever effect this might have 5248on its use in the startup scripts. 5249.Pp 5250When the value of this variable remains as set at startup by 5251.Nm 5252the following characters may appear in the value, 5253in the circumstances described. 5254Any present will always appear in ASCII lexical 5255order, as they appear below (to make testing the value easier to code). 5256.Pp 5257.Bl -tag -width M__ -offset indent -compact 5258.It \&! 5259Always present when set by 5260.Nm , 5261and is always first. 5262No specific meaning is attributed to this character. 5263.It \&\- 5264Set when the first character of 5265.Va argv[0] 5266as set when the shell was invoked was a dash 5267.Pq Sq \&\- . 5268.It \&0 5269Set when at startup, the special parameter 5270.Dv \&$# 5271has the value 0. 5272That is, no arguments were given to the script 5273in the case that there is a script. 5274.It \&c 5275The 5276.Fl c 5277option was given on the command line. 5278.It \&f 5279Neither the 5280.Fl c 5281nor 5282.Fl s 5283options were present on the command line, 5284but there is at least one non-option argument, 5285which will then be interpreted as the name of the 5286.Ar command_file 5287to process. 5288.It \&i 5289The shell is interactive. 5290At startup this indicates that 5291.Sq i 5292will appear in the value of the 5293special parameter 5294.Va \&$\- . 5295However, the special parameter will 5296alter as the 5297.Fl i 5298option is manipulated by the 5299.Ic set 5300built-in command, but 5301.Ev NBSH_INVOCATION 5302is never subsequently altered by the shell itself 5303(unless manipulated by a regular variable operations). 5304.It \&l 5305The shell is a login shell. 5306As with 5307.Sq i 5308(the same operational conditions apply) 5309this character will be present if the 5310.Sq l 5311is present in 5312.Va \&$- 5313when the shell is starting. 5314Note that if 5315.Sq l 5316is present, and 5317.Sq \&\- 5318is not, then the shell was invoked 5319with the 5320.Fl l 5321option on the command line (or the 5322equivalent 5323.Fl o Em login ) . 5324On the other hand, if 5325.Sq \&\- 5326appears, and 5327.Sq l 5328does not, 5329then the shell was invoked with the 5330.Cm +l 5331option (or its equivalent) on the command line. 5332If both 5333.Sq \&\- 5334and 5335.Sq l 5336appear, then the shell is a normal login 5337shell, the 5338.Fl l 5339option might have been given, but had no effect. 5340If neither 5341.Sq \&\- 5342nor 5343.Sq l 5344appear, then the shell is not a login shell, 5345and was never intended to be. 5346The 5347.Cm +l 5348option might have been given, but had no effect. 5349.It \&p 5350The shell was started as a privileged 5351(set user id) process. 5352This indicates that the 5353.Fl p 5354option must have been given on the command 5355line, or privileges would have been dropped. 5356.It \&s 5357The shell will read commands from standard input. 5358The 5359.Fl s 5360option was given, or implied. 5361This does not imply that the shell is interactive. 5362.El 5363.It Ev PATH 5364The default search path for executables. 5365See the 5366.Sx Path Search 5367section above. 5368.It Ev POSIXLY_CORRECT 5369If set in the environment upon initialization of the shell, 5370then the shell option 5371.Ic posix 5372will be set. 5373.Po 5374See the description of the 5375.Ic set 5376command in the 5377.Sx Built-ins 5378section. 5379.Pc 5380After initialization it is unused by the shell, 5381but is usually passed through the environment to 5382descendant processes, including other instances of the shell, 5383which may interpret it in a similar way. 5384.It Ev PPID 5385The process identified of the parent process of the 5386current shell. 5387This value is set at shell startup, ignoring 5388any value in the environment, and then made readonly. 5389.It Ev PS1 5390The primary prompt string, which defaults to 5391.Dq Li "$ " , 5392unless you are the superuser, in which case it defaults to 5393.Dq Li "# " . 5394This string is subject to parameter, arithmetic, and if 5395enabled by setting the 5396.Ic promptcmds 5397option, command substitution before being output. 5398During execution of commands used by command substitution, 5399execution tracing, the 5400.Ic xtrace 5401.Ic ( set Fl x ) 5402option is temporarily disabled. 5403If 5404.Ic promptcmds 5405is not set and the prompt string uses command substitution, 5406the prompt used will be an appropriate error string. 5407For other expansion errors, the prompt will become an 5408empty string, without an error message. 5409To verify parsing of 5410.Ev PS1 , 5411the method suggested for 5412.Ev ENV 5413can be used. 5414.It Ev PS2 5415The secondary prompt string, which defaults to 5416.Dq Li "> " . 5417After expansion (as for 5418.Ev PS1 ) 5419it is written whenever more input is required to complete the 5420current command. 5421.It Ev PS4 5422is output, after expansion as described for 5423.Ev PS1 , 5424as a prefix for each line when execution trace 5425.Ic ( set Fl x ) 5426is enabled. 5427.Ev PS4 5428defaults to 5429.Dq Li "+ " . 5430.It Ev PSc 5431Initialized by the shell, ignoring any value from the environment, 5432to a single character string, either 5433.Sq \&# 5434or 5435.Sq \&$ , 5436depending upon whether the current user is the superuser or not. 5437This is intended for use when building a custom 5438.Ev PS1 . 5439If a privileged shell has its privileges removed by 5440clearing the 5441.Fl p 5442option, an attempt will be made to be reset 5443.Ev PSc 5444to 5445.Dq \&# 5446or 5447.Dq \&$ , 5448as appropriate for its new privilege level. 5449.It Ev PSlit 5450Defines the character which may be embedded in pairs, in 5451.Ev PS1 5452or 5453.Ev PS2 5454to indicate to 5455.Xr editline 7 5456that the characters between each pair of occurrences of the 5457.Dv PSlit 5458character will not appear in the visible prompt, and will not 5459cause the terminal's cursor to change position, but rather set terminal 5460attributes for the following prompt character(s) at least one of 5461which must be present. 5462See 5463.Sx Command Line Editing 5464above for more information. 5465.It Ev RANDOM 5466Returns a different pseudo-random integer, 5467in the range [0,32767] each time it is accessed. 5468.Ev RANDOM 5469can be assigned an integer value to seed the PRNG. 5470If the value assigned is a constant, then the 5471sequence of values produces on subsequent references of 5472.Ev RANDOM 5473will repeat after the next time the same constant is assigned. 5474Note, this is not guaranteed to remain constant from one version 5475of the shell to another \(en the PRNG algorithm, or seeding 5476method is subject to change. 5477If 5478.Ev RANDOM 5479is assigned an empty value (null string) then the next time 5480.Ev RANDOM 5481is accessed, it will be seeded from a more genuinely random source. 5482The sequence of pseudo-random numbers generated will not be able to 5483be generated again (except by luck, whether good or bad, depends!) 5484This is also how the initial seed is generated, if none has been 5485assigned before 5486.Ev RANDOM 5487is first accessed after shell initialization. 5488Should the error message 5489.Dq "RANDOM initialisation failed" 5490appear on standard error, it indicates that the source 5491of good random numbers was not available, and 5492.Ev RANDOM 5493has instead been seeded with a more predictable value. 5494The following sequence of random numbers will 5495not be as unpredictable as they otherwise would be. 5496.It Ev SECONDS 5497Returns the number of seconds since the current shell was started. 5498If unset, it remains unset, and returns nothing, unless set again. 5499If set, it loses its special properties, and becomes a normal variable. 5500See the 5501.Ic specialvar 5502built-in command for remedial action. 5503.It Ev START_TIME 5504Initialized by the shell to the number of seconds since the Epoch 5505(see 5506.Xr localtime 3 ) 5507when the shell was started. 5508The value of 5509.Dl $(( Ns Ev START_TIME + Ev SECONDS Ns )) 5510represents the current time, if 5511.Ev START_TIME 5512has not been modified, and 5513.Ev SECONDS 5514has not been set or unset. 5515.It Ev TERM 5516The default terminal setting for the shell. 5517This is inherited by 5518children of the shell, and is used in the history editing modes. 5519.It Ev ToD 5520When referenced, uses the value of 5521.Ev ToD_FORMAT 5522(or 5523.Dq \&%T 5524if 5525.Ev ToD_FORMAT 5526is unset) as the format argument to 5527.Xr strftime 3 5528to encode the current time of day, in the time zone 5529defined by 5530.Ev TZ 5531if set, or current local time if not, and returns the result. 5532If unset 5533.Ev ToD 5534returns nothing. 5535If set, it loses its special properties, and becomes a normal variable. 5536See the 5537.Ic specialvar 5538built-in command for remedial action. 5539.It Ev ToD_FORMAT 5540Can be set to the 5541.Xr strftime 3 5542format string to be used when expanding 5543.Ev ToD . 5544Initially unset. 5545.It Ev TZ 5546If set, gives the time zone 5547(see 5548.Xr localtime 3 , 5549.Xr environ 7 ) 5550to use when formatting 5551.Ev ToD 5552and if exported, other utilities that deal with times. 5553If unset, the system's local wall clock time zone is used. 5554.\" 5555.\" ========================================================== 5556.\" This is explicitly last, not in sort order - please leave! 5557.It Ev NETBSD_SHELL 5558Unlike the variables previously mentioned, 5559this variable is somewhat strange, 5560in that it cannot be set, 5561inherited from the environment, 5562modified, or exported from the shell. 5563If set, by the shell, it indicates that the shell is the 5564.Ic sh 5565defined by this manual page, and gives its version information. 5566It can also give information in additional space separated words, 5567after the version string. 5568If the shell was built as part of a reproducible build, 5569the relevant date that was used for that build will be included. 5570Finally, any non-standard compilation options, 5571which may affect features available, 5572that were used when building the shell will be listed. 5573.Ev NETBSD_SHELL 5574behaves like any other variable that has the read-only 5575and un-exportable attributes set. 5576.El 5577.Ss Using Dv LINENO 5578.Dv LINENO 5579is in many respects a normal shell variable, containing an 5580integer value, and can be expanded using any of the forms 5581mentioned above which can be used for any other variable. 5582.Pp 5583.Dv LINENO 5584can be exported, made readonly, or unset, as with any other 5585variable, with similar effects. 5586Note that while being readonly prevents later attempts to 5587set, or unset, 5588.Dv LINENO , 5589it does not prevent its value changing. 5590References to 5591.Dv LINENO 5592.Pq "when not unset" 5593always obtain the current line number. 5594However, 5595.Dv LINENO 5596should normally not ever be set or unset. 5597In this shell setting 5598.Dv LINENO 5599reverses the effect of an earlier 5600.Ic unset , 5601but does not otherwise affect the value obtained. 5602If unset, 5603.Dv LINENO 5604should not normally be set again, doing so is not portable. 5605If 5606.Dv LINENO 5607is set or unset, different shells act differently. 5608The value of 5609.Dv LINENO 5610is never imported from the environment when the shell is 5611started, though if present there, as with any other variable, 5612.Dv LINENO 5613will be exported by this shell. 5614.Pp 5615.Dv LINENO 5616is set automatically by the shell to be the number of the source 5617line on which it occurs. 5618When exported, 5619.Dv LINENO 5620is exported with its value set to the line number it would have 5621had had it been referenced on the command line of the command to 5622which it is exported. 5623Line numbers are counted from 1, which is the first line the shell 5624reads from any particular file. 5625For this shell, standard input, including in an interactive shell, 5626the user's terminal, is just another file and lines are counted 5627there as well. 5628However note that not all shells count interactive 5629lines this way, it is not wise to rely upon 5630.Dv LINENO 5631having a useful value, except in a script, or a function. 5632.Pp 5633The role of 5634.Dv LINENO 5635in functions is less clear. 5636In some shells, 5637.Dv LINENO 5638continues to refer to the line number in the script which defines 5639the function, 5640in others lines count from one within the function, always (and 5641resume counting normally once the function definition is complete) 5642and others count in functions from one if the function is defined 5643interactively, but otherwise just reference the line number in the 5644script in which the function is defined. 5645This shell gives the user the option to choose. 5646If the 5647.Fl L 5648flag (the 5649.Ic local_lineno 5650option, see 5651.Sx Argument List Processing ) 5652is set, when the function is defined, then the function 5653defaults to counting lines with one being the first line of the 5654function. 5655When the 5656.Fl L 5657flag is not set, the shell counts lines in a function definition 5658in the same continuous sequence as the lines that surround the 5659function definition. 5660Further, if 5661.Dv LINENO 5662is made local 5663(see 5664.Sx Built-ins 5665above) 5666inside the function, the function can decide which 5667behavior it prefers. 5668If 5669.Dv LINENO 5670is made local and inherited, and not given a value, as in 5671.Dl local Fl I Dv LINENO 5672then from that point in the function, 5673.Dv LINENO 5674will give the line number as if lines are counted in sequence 5675with the lines that surround the function definition (and 5676any other function definitions in which this is nested.) 5677If 5678.Dv LINENO 5679is made local, and in that same command, given a value, as 5680.Dl local Oo Fl I Ns | Ns Fl N Oc Dv LINENO Ns = Ns Ar value 5681then 5682.Dv LINENO 5683will give the line number as if lines are counted from one 5684from the beginning of the function. 5685The value nominally assigned in this case is irrelevant, and ignored. 5686For completeness, if lineno is made local and unset, as in 5687.Dl local Fl N Dv LINENO 5688then 5689.Dv LINENO 5690is simply unset inside the function, and gives no value at all. 5691.Pp 5692Now for some technical details. 5693The line on which 5694.Dv LINENO 5695occurs in a parameter expansion, is the line that contains the 5696.Sq \&$ 5697that begins the expansion of 5698.Dv LINENO . 5699In the case of nested expansions, that 5700.Sq \&$ 5701is the one that actually has 5702.Dv LINENO 5703as its parameter. 5704In an arithmetic expansion, where no 5705.Sq \&$ 5706is used to evaluate 5707.Dv LINENO 5708but 5709.Dv LINENO 5710is simply referenced as a variable, then the value is the 5711line number of the line that contains the 5712.Sq L 5713of 5714.Dv LINENO . 5715For functions line one of the function definition (when relevant) 5716is the line that contains the first character of the 5717function name in the definition. 5718When exported, the line number of the command is the line number 5719where the first character of the word which becomes the command name occurs. 5720.Pp 5721When the shell opens a new file, for any reason, 5722it counts lines from one in that file, 5723and then resumes its original counting once it resumes reading the 5724previous input stream. 5725When handling a string passed to 5726.Ic eval 5727the line number starts at the line on which the string starts, 5728and then if the string contains internal newline characters, 5729those characters increase the line number. 5730This means that references to 5731.Dv LINENO 5732in such a case can produce values larger than would be 5733produced by a reference on the line after the 5734.Ic eval . 5735.Sh FILES 5736.Bl -item 5737.It 5738.Pa $HOME/.profile 5739.It 5740.Pa /etc/profile 5741.El 5742.Sh EXIT STATUS 5743Errors that are detected by the shell, such as a syntax error, will cause the 5744shell to exit with a non-zero exit status. 5745If the shell is not an 5746interactive shell, the execution of the shell file will be aborted. 5747Otherwise 5748the shell will return the exit status of the last command executed, or 5749if the exit built-in is used with a numeric argument, it will return the 5750argument. 5751.Sh SEE ALSO 5752.Xr csh 1 , 5753.Xr echo 1 , 5754.Xr getopt 1 , 5755.Xr ksh 1 , 5756.Xr login 1 , 5757.Xr printf 1 , 5758.Xr test 1 , 5759.Xr editline 3 , 5760.Xr getopt 3 , 5761.\" .Xr profile 4 , 5762.Xr editrc 5 , 5763.Xr passwd 5 , 5764.Xr editline 7 , 5765.Xr environ 7 , 5766.Xr nls 7 , 5767.Xr sysctl 8 5768.Sh HISTORY 5769A 5770.Nm 5771command appeared in 5772.At v1 . 5773It was replaced in 5774.At v7 5775with a version that introduced the basis of the current syntax. 5776That was, however, unmaintainable so we wrote this one. 5777This 5778.Nx 5779.Nm 5780is a much modified descendant of the ash shell written by Ken Almquist. 5781.Sh BUGS 5782Setuid shell scripts should be avoided at all costs, as they are a 5783significant security risk. 5784.Pp 5785The characters generated by filename completion should probably be quoted 5786to ensure that the filename is still valid after the input line has been 5787processed. 5788.Pp 5789Job control of compound statements (loops, etc) is a complete mess. 5790.Pp 5791The 5792.Fl Z 5793option to the 5794.Ic jobs 5795built-in command is bizarre, but is implemented this way to be 5796compatible with the similar option in 5797.Xr zsh 1 . 5798.Pp 5799Many, many, more. 5800(But less than there were...) 5801