1.\" $OpenBSD: sh.1,v 1.90 2011/04/23 10:14:59 sobrado Exp $ 2.\" 3.\" Public Domain 4.\" 5.Dd $Mdocdate: April 23 2011 $ 6.Dt SH 1 7.Os 8.Sh NAME 9.Nm sh 10.Nd public domain Bourne shell 11.Sh SYNOPSIS 12.Nm sh 13.Bk -words 14.Op Fl +abCefhiklmnpruvXx 15.Op Fl +o Ar option 16.Op Fl c Ar string \*(Ba Fl s \*(Ba Ar file Op Ar argument ... 17.Ek 18.Sh DESCRIPTION 19.Nm 20is a reimplementation of the Bourne shell, a command interpreter for both 21interactive and script use. 22.Pp 23The options are as follows: 24.Bl -tag -width Ds 25.It Fl c Ar string 26.Nm 27will execute the command(s) contained in 28.Ar string . 29.It Fl i 30Interactive shell. 31A shell is 32.Dq interactive 33if this 34option is used or if both standard input and standard error are attached 35to a 36.Xr tty 4 . 37An interactive shell has job control enabled, ignores the 38.Dv SIGINT , 39.Dv SIGQUIT , 40and 41.Dv SIGTERM 42signals, and prints prompts before reading input (see the 43.Ev PS1 44and 45.Ev PS2 46parameters). 47For non-interactive shells, the 48.Ic trackall 49option is on by default (see the 50.Ic set 51command below). 52.It Fl l 53Login shell. 54If the basename the shell is called with (i.e. argv[0]) 55starts with 56.Ql - 57or if this option is used, 58the shell is assumed to be a login shell and the shell reads and executes 59the contents of 60.Pa /etc/profile 61and 62.Pa $HOME/.profile 63if they exist and are readable. 64.It Fl p 65Privileged shell. 66A shell is 67.Dq privileged 68if this option is used 69or if the real user ID or group ID does not match the 70effective user ID or group ID (see 71.Xr getuid 2 72and 73.Xr getgid 2 ) . 74A privileged shell does not process 75.Pa $HOME/.profile 76nor the 77.Ev ENV 78parameter (see below). 79Instead, the file 80.Pa /etc/suid_profile 81is processed. 82Clearing the privileged option causes the shell to set 83its effective user ID (group ID) to its real user ID (group ID). 84.It Fl r 85Restricted shell. 86A shell is 87.Dq restricted 88if this 89option is used; 90if the basename the shell was invoked with was 91.Dq rsh ; 92or if the 93.Ev SHELL 94parameter is set to 95.Dq rsh . 96The following restrictions come into effect after the shell processes any 97profile and 98.Ev ENV 99files: 100.Pp 101.Bl -bullet -compact 102.It 103The 104.Ic cd 105command is disabled. 106.It 107The 108.Ev SHELL , 109.Ev ENV , 110and 111.Ev PATH 112parameters cannot be changed. 113.It 114Command names can't be specified with absolute or relative paths. 115.It 116The 117.Fl p 118option of the built-in command 119.Ic command 120can't be used. 121.It 122Redirections that create files can't be used (i.e.\& 123.Ql \*(Gt , 124.Ql \*(Gt\*(Ba , 125.Ql \*(Gt\*(Gt , 126.Ql \*(Lt\*(Gt ) . 127.El 128.It Fl s 129The shell reads commands from standard input; all non-option arguments 130are positional parameters. 131.El 132.Pp 133In addition to the above, the options described in the 134.Ic set 135built-in command can also be used on the command line: 136both 137.Op Fl +abCefhkmnuvXx 138and 139.Op Fl +o Ar option 140can be used for single letter or long options, respectively. 141.Pp 142If neither the 143.Fl c 144nor the 145.Fl s 146option is specified, the first non-option argument specifies the name 147of a file the shell reads commands from. 148If there are no non-option 149arguments, the shell reads commands from the standard input. 150The name of the shell (i.e. the contents of $0) 151is determined as follows: if the 152.Fl c 153option is used and there is a non-option argument, it is used as the name; 154if commands are being read from a file, the file is used as the name; 155otherwise, the basename the shell was called with (i.e. argv[0]) is used. 156.Pp 157If the 158.Ev ENV 159parameter is set when an interactive shell starts (or, 160in the case of login shells, 161after any profiles are processed), its value is subjected to parameter, 162command, arithmetic, and tilde 163.Pq Sq ~ 164substitution and the resulting file 165(if any) is read and executed. 166.Pp 167The exit status of the shell is 127 if the command file specified on the 168command line could not be opened, or non-zero if a fatal syntax error 169occurred during the execution of a script. 170In the absence of fatal errors, 171the exit status is that of the last command executed, or zero, if no 172command is executed. 173.Ss Command syntax 174The shell begins parsing its input by breaking it into 175.Em words . 176Words, which are sequences of characters, are delimited by unquoted whitespace 177characters (space, tab, and newline) or meta-characters 178.Po 179.Ql \*(Lt , 180.Ql \*(Gt , 181.Ql \*(Ba , 182.Ql \&; , 183.Ql \&( , 184.Ql \&) , 185and 186.Ql & 187.Pc . 188Aside from delimiting words, spaces and tabs are ignored, while newlines 189usually delimit commands. 190The meta-characters are used in building the following 191.Em tokens : 192.Ql \*(Lt , 193.Ql \*(Lt& , 194.Ql \*(Lt\*(Lt , 195.Ql \*(Gt , 196.Ql \*(Gt& , 197.Ql \*(Gt\*(Gt , 198etc. are used to specify redirections (see 199.Sx Input/output redirection 200below); 201.Ql \*(Ba 202is used to create pipelines; 203.Ql \&; 204is used to separate commands; 205.Ql & 206is used to create asynchronous pipelines; 207.Ql && 208and 209.Ql || 210are used to specify conditional execution; 211.Ql ;; 212is used in 213.Ic case 214statements; 215and lastly, 216.Ql \&( .. )\& 217is used to create subshells. 218.Pp 219Whitespace and meta-characters can be quoted individually using a backslash 220.Pq Sq \e , 221or in groups using double 222.Pq Sq \&" 223or single 224.Pq Sq ' 225quotes. 226Note that the following characters are also treated specially by the 227shell and must be quoted if they are to represent themselves: 228.Ql \e , 229.Ql \&" , 230.Ql ' , 231.Ql # , 232.Ql $ , 233.Ql ` , 234.Ql ~ , 235.Ql { , 236.Ql } , 237.Ql * , 238.Ql \&? , 239and 240.Ql \&[ . 241The first three of these are the above mentioned quoting characters (see 242.Sx Quoting 243below); 244.Ql # , 245if used at the beginning of a word, introduces a comment \(em everything after 246the 247.Ql # 248up to the nearest newline is ignored; 249.Ql $ 250is used to introduce parameter, command, and arithmetic substitutions (see 251.Sx Substitution 252below); 253.Ql ` 254introduces an old-style command substitution (see 255.Sx Substitution 256below); 257.Ql ~ 258begins a directory expansion (see 259.Sx Tilde expansion 260below); 261and finally, 262.Ql * , 263.Ql \&? , 264and 265.Ql \&[ 266are used in file name generation (see 267.Sx File name patterns 268below). 269.Pp 270As words and tokens are parsed, the shell builds commands, of which there 271are two basic types: 272.Em simple-commands , 273typically programs that are executed, and 274.Em compound-commands , 275such as 276.Ic for 277and 278.Ic if 279statements, grouping constructs, and function definitions. 280.Pp 281A simple-command consists of some combination of parameter assignments 282(see 283.Sx Parameters 284below), 285input/output redirections (see 286.Sx Input/output redirections 287below), 288and command words; the only restriction is that parameter assignments come 289before any command words. 290The command words, if any, define the command 291that is to be executed and its arguments. 292The command may be a shell built-in command, a function, 293or an external command 294(i.e. a separate executable file that is located using the 295.Ev PATH 296parameter; see 297.Sx Command execution 298below). 299Note that all command constructs have an exit status: for external commands, 300this is related to the status returned by 301.Xr wait 2 302(if the command could not be found, the exit status is 127; if it could not 303be executed, the exit status is 126); the exit status of other command 304constructs (built-in commands, functions, compound-commands, pipelines, lists, 305etc.) are all well-defined and are described where the construct is 306described. 307The exit status of a command consisting only of parameter 308assignments is that of the last command substitution performed during the 309parameter assignment or 0 if there were no command substitutions. 310.Pp 311Commands can be chained together using the 312.Ql | 313token to form pipelines, in which the standard output of each command but the 314last is piped (see 315.Xr pipe 2 ) 316to the standard input of the following command. 317The exit status of a pipeline is that of its last command. 318A pipeline may be prefixed by the 319.Ql \&! 320reserved word, which causes the exit status of the pipeline to be logically 321complemented: if the original status was 0, the complemented status will be 1; 322if the original status was not 0, the complemented status will be 0. 323.Pp 324.Em Lists 325of commands can be created by separating pipelines by any of the following 326tokens: 327.Ql && , 328.Ql || , 329.Ql & , 330.Ql |& , 331and 332.Ql \&; . 333The first two are for conditional execution: 334.Dq Ar cmd1 No && Ar cmd2 335executes 336.Ar cmd2 337only if the exit status of 338.Ar cmd1 339is zero; 340.Ql || 341is the opposite \(em 342.Ar cmd2 343is executed only if the exit status of 344.Ar cmd1 345is non-zero. 346.Ql && 347and 348.Ql || 349have equal precedence which is higher than that of 350.Ql & , 351.Ql |& , 352and 353.Ql \&; , 354which also have equal precedence. 355Note that the 356.Ql && 357and 358.Ql || 359operators are 360.Qq left-associative . 361For example, both of these commands will print only 362.Qq bar : 363.Bd -literal -offset indent 364$ false && echo foo || echo bar 365$ true || echo foo && echo bar 366.Ed 367.Pp 368The 369.Ql & 370token causes the preceding command to be executed asynchronously; that is, 371the shell starts the command but does not wait for it to complete (the shell 372does keep track of the status of asynchronous commands; see 373.Sx Job control 374below). 375When an asynchronous command is started when job control is disabled 376(i.e. in most scripts), the command is started with signals 377.Dv SIGINT 378and 379.Dv SIGQUIT 380ignored and with input redirected from 381.Pa /dev/null 382(however, redirections specified in the asynchronous command have precedence). 383Note that a command must follow the 384.Ql && 385and 386.Ql || 387operators, while it need not follow 388.Ql & , 389.Ql |& , 390or 391.Ql \&; . 392The exit status of a list is that of the last command executed, with the 393exception of asynchronous lists, for which the exit status is 0. 394.Pp 395Compound commands are created using the following reserved words. 396These words 397are only recognized if they are unquoted and if they are used as the first 398word of a command (i.e. they can't be preceded by parameter assignments or 399redirections): 400.Bd -literal -offset indent 401case esac in while ]] 402do fi name ! { 403done for select ( } 404elif function then ) 405else if until [[ 406.Ed 407.Pp 408.Sy Note : 409Some shells (but not this one) execute control structure commands in a 410subshell when one or more of their file descriptors are redirected, so any 411environment changes inside them may fail. 412To be portable, the 413.Ic exec 414statement should be used instead to redirect file descriptors before the 415control structure. 416.Pp 417In the following compound command descriptions, command lists (denoted as 418.Em list ) 419that are followed by reserved words must end with a semicolon, a newline, or 420a (syntactically correct) reserved word. 421For example, the following are all valid: 422.Bd -literal -offset indent 423$ { echo foo; echo bar; } 424$ { echo foo; echo bar\*(Ltnewline\*(Gt } 425$ { { echo foo; echo bar; } } 426.Ed 427.Pp 428This is not valid: 429.Pp 430.Dl $ { echo foo; echo bar } 431.Bl -tag -width Ds 432.It Pq Ar list 433Execute 434.Ar list 435in a subshell. 436There is no implicit way to pass environment changes from a 437subshell back to its parent. 438.It { Ar list ; No } 439Compound construct; 440.Ar list 441is executed, but not in a subshell. 442Note that 443.Ql { 444and 445.Ql } 446are reserved words, not meta-characters. 447.It Xo case Ar word No in 448.Oo Op \&( 449.Ar \ pattern 450.Op \*(Ba Ar pattern 451.No ... No ) 452.Ar list No ;;\ \& Oc ... esac 453.Xc 454The 455.Ic case 456statement attempts to match 457.Ar word 458against a specified 459.Ar pattern ; 460the 461.Ar list 462associated with the first successfully matched pattern is executed. 463Patterns used in 464.Ic case 465statements are the same as those used for file name patterns except that the 466restrictions regarding 467.Ql \&. 468and 469.Ql / 470are dropped. 471Note that any unquoted space before and after a pattern is 472stripped; any space within a pattern must be quoted. 473Both the word and the 474patterns are subject to parameter, command, and arithmetic substitution, as 475well as tilde substitution. 476For historical reasons, open and close braces may be used instead of 477.Ic in 478and 479.Ic esac 480e.g.\& 481.Ic case $foo { *) echo bar; } . 482The exit status of a 483.Ic case 484statement is that of the executed 485.Ar list ; 486if no 487.Ar list 488is executed, the exit status is zero. 489.It Xo for Ar name 490.Oo in Ar word No ... Oc ; 491.No do Ar list ; No done 492.Xc 493For each 494.Ar word 495in the specified word list, the parameter 496.Ar name 497is set to the word and 498.Ar list 499is executed. 500If 501.Ic in 502is not used to specify a word list, the positional parameters 503($1, $2, etc.)\& 504are used instead. 505For historical reasons, open and close braces may be used instead of 506.Ic do 507and 508.Ic done 509e.g.\& 510.Ic for i; { echo $i; } . 511The exit status of a 512.Ic for 513statement is the last exit status of 514.Ar list ; 515if 516.Ar list 517is never executed, the exit status is zero. 518.It Xo if Ar list ; 519.No then Ar list ; 520.Oo elif Ar list ; 521.No then Ar list ; Oc 522.No ... 523.Oo else Ar list ; Oc 524.No fi 525.Xc 526If the exit status of the first 527.Ar list 528is zero, the second 529.Ar list 530is executed; otherwise, the 531.Ar list 532following the 533.Ic elif , 534if any, is executed with similar consequences. 535If all the lists following the 536.Ic if 537and 538.Ic elif Ns s 539fail (i.e. exit with non-zero status), the 540.Ar list 541following the 542.Ic else 543is executed. 544The exit status of an 545.Ic if 546statement is that of non-conditional 547.Ar list 548that is executed; if no non-conditional 549.Ar list 550is executed, the exit status is zero. 551.It Xo select Ar name 552.Oo in Ar word No ... Oc ; 553.No do Ar list ; No done 554.Xc 555The 556.Ic select 557statement provides an automatic method of presenting the user with a menu and 558selecting from it. 559An enumerated list of the specified 560.Ar word Ns (s) 561is printed on standard error, followed by a prompt 562.Po 563.Ev PS3: normally 564.Sq #?\ \& 565.Pc . 566A number corresponding to one of the enumerated words is then read from 567standard input, 568.Ar name 569is set to the selected word (or unset if the selection is not valid), 570.Ev REPLY 571is set to what was read (leading/trailing space is stripped), and 572.Ar list 573is executed. 574If a blank line (i.e. zero or more 575.Ev IFS 576characters) is entered, the menu is reprinted without executing 577.Ar list . 578.Pp 579When 580.Ar list 581completes, the enumerated list is printed if 582.Ev REPLY 583is 584.Dv NULL , 585the prompt is printed, and so on. 586This process continues until an end-of-file 587is read, an interrupt is received, or a 588.Ic break 589statement is executed inside the loop. 590If 591.Dq in word ... 592is omitted, the positional parameters are used 593(i.e. $1, $2, etc.). 594For historical reasons, open and close braces may be used instead of 595.Ic do 596and 597.Ic done 598e.g.\& 599.Ic select i; { echo $i; } . 600The exit status of a 601.Ic select 602statement is zero if a 603.Ic break 604statement is used to exit the loop, non-zero otherwise. 605.It Xo until Ar list ; 606.No do Ar list ; 607.No done 608.Xc 609This works like 610.Ic while , 611except that the body is executed only while the exit status of the first 612.Ar list 613is non-zero. 614.It Xo while Ar list ; 615.No do Ar list ; 616.No done 617.Xc 618A 619.Ic while 620is a pre-checked loop. 621Its body is executed as often as the exit status of the first 622.Ar list 623is zero. 624The exit status of a 625.Ic while 626statement is the last exit status of the 627.Ar list 628in the body of the loop; if the body is not executed, the exit status is zero. 629.It Xo function Ar name 630.No { Ar list ; No } 631.Xc 632Defines the function 633.Ar name 634(see 635.Sx Functions 636below). 637Note that redirections specified after a function definition are 638performed whenever the function is executed, not when the function definition 639is executed. 640.It Ar name Ns () Ar command 641Mostly the same as 642.Ic function 643(see 644.Sx Functions 645below). 646.It Bq Bq Ar \ \&expression\ \& 647Similar to the 648.Ic test 649and 650.Ic \&[ ... \&] 651commands (described later), with the following exceptions: 652.Bl -bullet -offset indent 653.It 654Field splitting and file name generation are not performed on arguments. 655.It 656The 657.Fl a 658.Pq AND 659and 660.Fl o 661.Pq OR 662operators are replaced with 663.Ql && 664and 665.Ql || , 666respectively. 667.It 668Operators (e.g.\& 669.Sq Fl f , 670.Sq = , 671.Sq \&! ) 672must be unquoted. 673.It 674The second operand of the 675.Sq != 676and 677.Sq = 678expressions are patterns (e.g. the comparison 679.Ic [[ foobar = f*r ]] 680succeeds). 681.It 682There are two additional binary operators, 683.Ql \*(Lt 684and 685.Ql \*(Gt , 686which return true if their first string operand is less than, or greater than, 687their second string operand, respectively. 688.It 689The single argument form of 690.Ic test , 691which tests if the argument has a non-zero length, is not valid; explicit 692operators must always be used e.g. instead of 693.No \&[ Ar str No \&] 694use 695.No \&[[ -n Ar str No \&]] . 696.It 697Parameter, command, and arithmetic substitutions are performed as expressions 698are evaluated and lazy expression evaluation is used for the 699.Ql && 700and 701.Ql || 702operators. 703This means that in the following statement, 704.Ic $(\*(Lt foo) 705is evaluated if and only if the file 706.Pa foo 707exists and is readable: 708.Bd -literal -offset indent 709$ [[ -r foo && $(\*(Lt foo) = b*r ]] 710.Ed 711.El 712.El 713.Ss Quoting 714Quoting is used to prevent the shell from treating characters or words 715specially. 716There are three methods of quoting. 717First, 718.Ql \e 719quotes the following character, unless it is at the end of a line, in which 720case both the 721.Ql \e 722and the newline are stripped. 723Second, a single quote 724.Pq Sq ' 725quotes everything up to the next single quote (this may span lines). 726Third, a double quote 727.Pq Sq \&" 728quotes all characters, except 729.Ql $ , 730.Ql ` 731and 732.Ql \e , 733up to the next unquoted double quote. 734.Ql $ 735and 736.Ql ` 737inside double quotes have their usual meaning (i.e. parameter, command, or 738arithmetic substitution) except no field splitting is carried out on the 739results of double-quoted substitutions. 740If a 741.Ql \e 742inside a double-quoted string is followed by 743.Ql \e , 744.Ql $ , 745.Ql ` , 746or 747.Ql \&" , 748it is replaced by the second character; if it is followed by a newline, both 749the 750.Ql \e 751and the newline are stripped; otherwise, both the 752.Ql \e 753and the character following are unchanged. 754.Pp 755.Sy Note : 756See 757.Sx POSIX mode 758below for a special rule regarding 759differences in quoting when the shell is in POSIX mode. 760.Ss Aliases 761There are two types of aliases: normal command aliases and tracked aliases. 762Command aliases are normally used as a short hand for a long or often used 763command. 764The shell expands command aliases (i.e. substitutes the alias name 765for its value) when it reads the first word of a command. 766An expanded alias is re-processed to check for more aliases. 767If a command alias ends in a 768space or tab, the following word is also checked for alias expansion. 769The alias expansion process stops when a word that is not an alias is found, 770when a quoted word is found, or when an alias word that is currently being 771expanded is found. 772.Pp 773The following command aliases are defined automatically by the shell: 774.Bd -literal -offset indent 775hash='alias -t' 776type='whence -v' 777.Ed 778.Pp 779Tracked aliases allow the shell to remember where it found a particular 780command. 781The first time the shell does a path search for a command that is 782marked as a tracked alias, it saves the full path of the command. 783The next 784time the command is executed, the shell checks the saved path to see that it 785is still valid, and if so, avoids repeating the path search. 786Tracked aliases can be listed and created using 787.Ic alias -t . 788Note that changing the 789.Ev PATH 790parameter clears the saved paths for all tracked aliases. 791If the 792.Ic trackall 793option is set (i.e.\& 794.Ic set -o Ic trackall 795or 796.Ic set -h ) , 797the shell tracks all commands. 798This option is set automatically for non-interactive shells. 799For interactive shells, only the following commands are 800automatically tracked: 801.Xr cat 1 , 802.Xr cc 1 , 803.Xr chmod 1 , 804.Xr cp 1 , 805.Xr date 1 , 806.Xr ed 1 , 807.Xr emacs 1 , 808.Xr grep 1 , 809.Xr ls 1 , 810.Xr mail 1 , 811.Xr make 1 , 812.Xr mv 1 , 813.Xr pr 1 , 814.Xr rm 1 , 815.Xr sed 1 , 816.Xr vi 1 , 817and 818.Xr who 1 . 819.Ss Substitution 820The first step the shell takes in executing a simple-command is to perform 821substitutions on the words of the command. 822There are three kinds of 823substitution: parameter, command, and arithmetic. 824Parameter substitutions, 825which are described in detail in the next section, take the form 826.Pf $ Ns Ar name 827or 828.Pf ${ Ns Ar ... Ns } ; 829command substitutions take the form 830.Pf $( Ns Ar command Ns \&) 831or 832.Pf ` Ns Ar command Ns ` ; 833and arithmetic substitutions take the form 834.Pf $(( Ns Ar expression Ns )) . 835.Pp 836If a substitution appears outside of double quotes, the results of the 837substitution are generally subject to word or field splitting according to 838the current value of the 839.Ev IFS 840parameter. 841The 842.Ev IFS 843parameter specifies a list of characters which are used to break a string up 844into several words; any characters from the set space, tab, and newline that 845appear in the 846.Ev IFS 847characters are called 848.Dq IFS whitespace . 849Sequences of one or more 850.Ev IFS 851whitespace characters, in combination with zero or one 852.Pf non- Ev IFS 853whitespace 854characters, delimit a field. 855As a special case, leading and trailing 856.Ev IFS 857whitespace is stripped (i.e. no leading or trailing empty field is created by 858it); leading 859.Pf non- Ev IFS 860whitespace does create an empty field. 861.Pp 862Example: If 863.Ev IFS 864is set to 865.Dq \*(Ltspace\*(Gt: , 866and VAR is set to 867.Dq \*(Ltspace\*(GtA\*(Ltspace\*(Gt:\*(Ltspace\*(Gt\*(Ltspace\*(GtB::D , 868the substitution for $VAR results in four fields: 869.Sq A , 870.Sq B , 871.Sq 872(an empty field), 873and 874.Sq D . 875Note that if the 876.Ev IFS 877parameter is set to the 878.Dv NULL 879string, no field splitting is done; if the parameter is unset, the default 880value of space, tab, and newline is used. 881.Pp 882Also, note that the field splitting applies only to the immediate result of 883the substitution. 884Using the previous example, the substitution for $VAR:E 885results in the fields: 886.Sq A , 887.Sq B , 888.Sq , 889and 890.Sq D:E , 891not 892.Sq A , 893.Sq B , 894.Sq , 895.Sq D , 896and 897.Sq E . 898This behavior is POSIX compliant, but incompatible with some other shell 899implementations which do field splitting on the word which contained the 900substitution or use 901.Dv IFS 902as a general whitespace delimiter. 903.Pp 904The results of substitution are, unless otherwise specified, also subject to 905file name expansion (see the relevant section below). 906.Pp 907A command substitution is replaced by the output generated by the specified 908command, which is run in a subshell. 909For 910.Pf $( Ns Ar command Ns \&) 911substitutions, normal quoting rules are used when 912.Ar command 913is parsed; however, for the 914.Pf ` Ns Ar command Ns ` 915form, a 916.Ql \e 917followed by any of 918.Ql $ , 919.Ql ` , 920or 921.Ql \e 922is stripped (a 923.Ql \e 924followed by any other character is unchanged). 925As a special case in command substitutions, a command of the form 926.Pf \*(Lt Ar file 927is interpreted to mean substitute the contents of 928.Ar file . 929Note that 930.Ic $(\*(Lt foo) 931has the same effect as 932.Ic $(cat foo) , 933but it is carried out more efficiently because no process is started. 934.Pp 935.Sy Note : 936.Pf $( Ns Ar command Ns \&) 937expressions are currently parsed by finding the matching parenthesis, 938regardless of quoting. 939This should be fixed soon. 940.Pp 941Arithmetic substitutions are replaced by the value of the specified expression. 942For example, the command 943.Ic echo $((2+3*4)) 944prints 14. 945See 946.Sx Arithmetic expressions 947for a description of an expression. 948.Ss Parameters 949Parameters are shell variables; they can be assigned values and their values 950can be accessed using a parameter substitution. 951A parameter name is either one 952of the special single punctuation or digit character parameters described 953below, or a letter followed by zero or more letters or digits 954.Po 955.Ql _ 956counts as a letter 957.Pc . 958Parameter substitutions take the form 959.Pf $ Ns Ar name , 960.Pf ${ Ns Ar name Ns } , 961or 962.Sm off 963.Pf ${ Ar name Oo Ar expr Oc } 964.Sm on 965where 966.Ar name 967is a parameter name. 968If substitution is performed on a parameter 969that is not set, a null string is substituted unless the 970.Ic nounset 971option 972.Po 973.Ic set Fl o Ic nounset 974or 975.Ic set Fl u 976.Pc 977is set, in which case an error occurs. 978.Pp 979Parameters can be assigned values in a number of ways. 980First, the shell implicitly sets some parameters like 981.Ql # , 982.Ql PWD , 983and 984.Ql $ ; 985this is the only way the special single character parameters are set. 986Second, parameters are imported from the shell's environment at startup. 987Third, parameters can be assigned values on the command line: for example, 988.Ic FOO=bar 989sets the parameter 990.Dq FOO 991to 992.Dq bar ; 993multiple parameter assignments can be given on a single command line and they 994can be followed by a simple-command, in which case the assignments are in 995effect only for the duration of the command (such assignments are also 996exported; see below for the implications of this). 997Note that both the parameter name and the 998.Ql = 999must be unquoted for the shell to recognize a parameter assignment. 1000The fourth way of setting a parameter is with the 1001.Ic export , 1002.Ic readonly , 1003and 1004.Ic typeset 1005commands; see their descriptions in the 1006.Sx Command execution 1007section. 1008Fifth, 1009.Ic for 1010loops set parameters as well as the 1011.Ic getopts , 1012.Ic read , 1013and 1014.Ic set -A 1015commands. 1016Lastly, parameters can be assigned values using assignment operators 1017inside arithmetic expressions (see 1018.Sx Arithmetic expressions 1019below) or using the 1020.Sm off 1021.Pf ${ Ar name No = Ar value No } 1022.Sm on 1023form of the parameter substitution (see below). 1024.Pp 1025Parameters with the export attribute (set using the 1026.Ic export 1027or 1028.Ic typeset Fl x 1029commands, or by parameter assignments followed by simple commands) are put in 1030the environment (see 1031.Xr environ 7 ) 1032of commands run by the shell as 1033.Ar name Ns = Ns Ar value 1034pairs. 1035The order in which parameters appear in the environment of a command is 1036unspecified. 1037When the shell starts up, it extracts parameters and their values 1038from its environment and automatically sets the export attribute for those 1039parameters. 1040.Pp 1041Modifiers can be applied to the 1042.Pf ${ Ns Ar name Ns } 1043form of parameter substitution: 1044.Bl -tag -width Ds 1045.Sm off 1046.It ${ Ar name No :- Ar word No } 1047.Sm on 1048If 1049.Ar name 1050is set and not 1051.Dv NULL , 1052it is substituted; otherwise, 1053.Ar word 1054is substituted. 1055.Sm off 1056.It ${ Ar name No :+ Ar word No } 1057.Sm on 1058If 1059.Ar name 1060is set and not 1061.Dv NULL , 1062.Ar word 1063is substituted; otherwise, nothing is substituted. 1064.Sm off 1065.It ${ Ar name No := Ar word No } 1066.Sm on 1067If 1068.Ar name 1069is set and not 1070.Dv NULL , 1071it is substituted; otherwise, it is assigned 1072.Ar word 1073and the resulting value of 1074.Ar name 1075is substituted. 1076.Sm off 1077.It ${ Ar name No :? Ar word No } 1078.Sm on 1079If 1080.Ar name 1081is set and not 1082.Dv NULL , 1083it is substituted; otherwise, 1084.Ar word 1085is printed on standard error (preceded by 1086.Ar name : ) 1087and an error occurs (normally causing termination of a shell script, function, 1088or script sourced using the 1089.Sq \&. 1090built-in). 1091If 1092.Ar word 1093is omitted, the string 1094.Dq parameter null or not set 1095is used instead. 1096.El 1097.Pp 1098In the above modifiers, the 1099.Ql \&: 1100can be omitted, in which case the conditions only depend on 1101.Ar name 1102being set (as opposed to set and not 1103.Dv NULL ) . 1104If 1105.Ar word 1106is needed, parameter, command, arithmetic, and tilde substitution are performed 1107on it; if 1108.Ar word 1109is not needed, it is not evaluated. 1110.Pp 1111The following forms of parameter substitution can also be used: 1112.Pp 1113.Bl -tag -width Ds -compact 1114.It Pf ${# Ns Ar name Ns \&} 1115The number of positional parameters if 1116.Ar name 1117is 1118.Ql * , 1119.Ql @ , 1120or not specified; otherwise the length of the string value of parameter 1121.Ar name . 1122.Pp 1123.It Pf ${# Ns Ar name Ns [*]} 1124.It Pf ${# Ns Ar name Ns [@]} 1125The number of elements in the array 1126.Ar name . 1127.Pp 1128.Sm off 1129.It Xo 1130.Pf ${ Ar name 1131.Pf # Ar pattern No } 1132.Xc 1133.It Xo 1134.Pf ${ Ar name 1135.Pf ## Ar pattern No } 1136.Xc 1137.Sm on 1138If 1139.Ar pattern 1140matches the beginning of the value of parameter 1141.Ar name , 1142the matched text is deleted from the result of substitution. 1143A single 1144.Ql # 1145results in the shortest match, and two 1146of them result in the longest match. 1147.Pp 1148.Sm off 1149.It Xo 1150.Pf ${ Ar name 1151.Pf % Ar pattern No } 1152.Xc 1153.It Xo 1154.Pf ${ Ar name 1155.Pf %% Ar pattern No } 1156.Xc 1157.Sm on 1158Like ${..#..} substitution, but it deletes from the end of the value. 1159.El 1160.Pp 1161The following special parameters are implicitly set by the shell and cannot be 1162set directly using assignments: 1163.Bl -tag -width "1 ... 9" 1164.It Ev \&! 1165Process ID of the last background process started. 1166If no background processes have been started, the parameter is not set. 1167.It Ev \&# 1168The number of positional parameters ($1, $2, etc.). 1169.It Ev \&$ 1170The PID of the shell, or the PID of the original shell if it is a subshell. 1171Do 1172.Em NOT 1173use this mechanism for generating temporary file names; see 1174.Xr mktemp 1 1175instead. 1176.It Ev - 1177The concatenation of the current single letter options (see the 1178.Ic set 1179command below for a list of options). 1180.It Ev \&? 1181The exit status of the last non-asynchronous command executed. 1182If the last command was killed by a signal, 1183.Ic $?\& 1184is set to 128 plus the signal number. 1185.It Ev 0 1186The name of the shell, determined as follows: 1187the first argument to 1188.Nm 1189if it was invoked with the 1190.Fl c 1191option and arguments were given; otherwise the 1192.Ar file 1193argument, if it was supplied; 1194or else the basename the shell was invoked with (i.e.\& 1195.Li argv[0] ) . 1196.Ev $0 1197is also set to the name of the current script or 1198the name of the current function, if it was defined with the 1199.Ic function 1200keyword (i.e. a Korn shell style function). 1201.It Ev 1 No ... Ev 9 1202The first nine positional parameters that were supplied to the shell, function, 1203or script sourced using the 1204.Sq \&. 1205built-in. 1206Further positional parameters may be accessed using 1207.Pf ${ Ar number Ns } . 1208.It Ev * 1209All positional parameters (except parameter 0) i.e. $1, $2, $3, ... 1210If used 1211outside of double quotes, parameters are separate words (which are subjected 1212to word splitting); if used within double quotes, parameters are separated 1213by the first character of the 1214.Ev IFS 1215parameter (or the empty string if 1216.Ev IFS 1217is 1218.Dv NULL ) . 1219.It Ev @ 1220Same as 1221.Ic $* , 1222unless it is used inside double quotes, in which case a separate word is 1223generated for each positional parameter. 1224If there are no positional parameters, no word is generated. 1225.Ic $@ 1226can be used to access arguments, verbatim, without losing 1227.Dv NULL 1228arguments or splitting arguments with spaces. 1229.El 1230.Pp 1231The following parameters are set and/or used by the shell: 1232.Bl -tag -width "EXECSHELL" 1233.It Ev CDPATH 1234Search path for the 1235.Ic cd 1236built-in command. 1237It works the same way as 1238.Ev PATH 1239for those directories not beginning with 1240.Ql / 1241in 1242.Ic cd 1243commands. 1244Note that if 1245.Ev CDPATH 1246is set and does not contain 1247.Sq \&. 1248or contains an empty path, the current directory is not searched. 1249Also, the 1250.Ic cd 1251built-in command will display the resulting directory when a match is found 1252in any search path other than the empty path. 1253.It Ev COLUMNS 1254Set to the number of columns on the terminal or window. 1255Currently set to the 1256.Dq cols 1257value as reported by 1258.Xr stty 1 1259if that value is non-zero. 1260This parameter is used by the 1261.Ic set -o 1262and 1263.Ic kill -l 1264commands to format information columns. 1265.It Ev ENV 1266If this parameter is found to be set after any profile files are executed, the 1267expanded value is used as a shell startup file. 1268It typically contains function and alias definitions. 1269.It Ev ERRNO 1270Integer value of the shell's 1271.Va errno 1272variable. 1273It indicates the reason the last system call failed. 1274Not yet implemented. 1275.It Ev EXECSHELL 1276If set, this parameter is assumed to contain the shell that is to be used to 1277execute commands that 1278.Xr execve 2 1279fails to execute and which do not start with a 1280.Dq #! Ns Ar shell 1281sequence. 1282.It Ev FCEDIT 1283The editor used by the 1284.Ic fc 1285command (see below). 1286.It Ev FPATH 1287Like 1288.Ev PATH , 1289but used when an undefined function is executed to locate the file defining the 1290function. 1291It is also searched when a command can't be found using 1292.Ev PATH . 1293See 1294.Sx Functions 1295below for more information. 1296.It Ev HOME 1297The default directory for the 1298.Ic cd 1299command and the value substituted for an unqualified 1300.Ic ~ 1301(see 1302.Sx Tilde expansion 1303below). 1304.It Ev IFS 1305Internal field separator, used during substitution and by the 1306.Ic read 1307command, to split values into distinct arguments; normally set to space, tab, 1308and newline. 1309See 1310.Sx Substitution 1311above for details. 1312.Pp 1313.Sy Note : 1314This parameter is not imported from the environment when the shell is 1315started. 1316.It Ev SH_VERSION 1317The version of shell and the date the version was created (read-only). 1318.It Ev LINENO 1319The line number of the function or shell script that is currently being 1320executed. 1321.It Ev LINES 1322Set to the number of lines on the terminal or window. 1323.It Ev OLDPWD 1324The previous working directory. 1325Unset if 1326.Ic cd 1327has not successfully changed directories since the shell started, or if the 1328shell doesn't know where it is. 1329.It Ev OPTARG 1330When using 1331.Ic getopts , 1332it contains the argument for a parsed option, if it requires one. 1333.It Ev OPTIND 1334The index of the next argument to be processed when using 1335.Ic getopts . 1336Assigning 1 to this parameter causes 1337.Ic getopts 1338to process arguments from the beginning the next time it is invoked. 1339.It Ev PATH 1340A colon separated list of directories that are searched when looking for 1341commands and files sourced using the 1342.Sq \&. 1343command (see below). 1344An empty string resulting from a leading or trailing 1345colon, or two adjacent colons, is treated as a 1346.Sq \&. 1347(the current directory). 1348.It Ev POSIXLY_CORRECT 1349If set, this parameter causes the 1350.Ic posix 1351option to be enabled. 1352See 1353.Sx POSIX mode 1354below. 1355.It Ev PPID 1356The process ID of the shell's parent (read-only). 1357.It Ev PS1 1358The primary prompt for interactive shells. 1359Parameter, command, and arithmetic 1360substitutions are performed. 1361.Ql \&! 1362is replaced with the current command number (see the 1363.Ic fc 1364command below). 1365A literal 1366.Ql \&! 1367can be put in the prompt by placing 1368.Ql !! 1369in 1370.Ev PS1 . 1371The default is 1372.Sq $\ \& 1373for non-root users, 1374.Sq #\ \& 1375for root. 1376.It Ev PS2 1377Secondary prompt string, by default 1378.Sq \*(Gt\ \& , 1379used when more input is needed to complete a command. 1380.It Ev PS4 1381Used to prefix commands that are printed during execution tracing (see the 1382.Ic set Fl x 1383command below). 1384Parameter, command, and arithmetic substitutions are performed 1385before it is printed. 1386The default is 1387.Sq +\ \& . 1388.It Ev PWD 1389The current working directory. 1390May be unset or 1391.Dv NULL 1392if the shell doesn't know where it is. 1393.It Ev REPLY 1394Default parameter for the 1395.Ic read 1396command if no names are given. 1397.It Ev TMPDIR 1398The directory temporary shell files are created in. 1399If this parameter is not 1400set, or does not contain the absolute path of a writable directory, temporary 1401files are created in 1402.Pa /tmp . 1403.El 1404.Ss Tilde expansion 1405Tilde expansion, which is done in parallel with parameter substitution, is done 1406on words starting with an unquoted 1407.Ql ~ . 1408The characters following the tilde, up to the first 1409.Ql / , 1410if any, are assumed to be a login name. 1411If the login name is empty, 1412.Ql + , 1413or 1414.Ql - , 1415the value of the 1416.Ev HOME , 1417.Ev PWD , 1418or 1419.Ev OLDPWD 1420parameter is substituted, respectively. 1421Otherwise, the password file is 1422searched for the login name, and the tilde expression is substituted with the 1423user's home directory. 1424If the login name is not found in the password file or 1425if any quoting or parameter substitution occurs in the login name, no 1426substitution is performed. 1427.Pp 1428In parameter assignments 1429(such as those preceding a simple-command or those occurring 1430in the arguments of 1431.Ic alias , 1432.Ic export , 1433.Ic readonly , 1434and 1435.Ic typeset ) , 1436tilde expansion is done after any assignment 1437(i.e. after the equals sign) 1438or after an unquoted colon 1439.Pq Sq \&: ; 1440login names are also delimited by colons. 1441.Pp 1442The home directory of previously expanded login names are cached and re-used. 1443The 1444.Ic alias -d 1445command may be used to list, change, and add to this cache (e.g.\& 1446.Ic alias -d fac=/usr/local/facilities; cd ~fac/bin ) . 1447.Ss File name patterns 1448A file name pattern is a word containing one or more unquoted 1449.Ql \&? , 1450.Ql * , 1451.Ql + , 1452.Ql @ , 1453or 1454.Ql \&! 1455characters or 1456.Dq [..] 1457sequences. 1458The shell replaces file 1459name patterns with the sorted names of all the files that match the pattern 1460(if no files match, the word is left unchanged). 1461The pattern elements have the following meaning: 1462.Bl -tag -width Ds 1463.It \&? 1464Matches any single character. 1465.It \&* 1466Matches any sequence of characters. 1467.It [..] 1468Matches any of the characters inside the brackets. 1469Ranges of characters can be 1470specified by separating two characters by a 1471.Ql - 1472(e.g.\& 1473.Dq [a0-9] 1474matches the letter 1475.Sq a 1476or any digit). 1477In order to represent itself, a 1478.Ql - 1479must either be quoted or the first or last character in the character list. 1480Similarly, a 1481.Ql \&] 1482must be quoted or the first character in the list if it is to represent itself 1483instead of the end of the list. 1484Also, a 1485.Ql \&! 1486appearing at the start of the list has special meaning (see below), so to 1487represent itself it must be quoted or appear later in the list. 1488.Pp 1489Within a bracket expression, the name of a 1490.Em character class 1491enclosed in 1492.Sq [: 1493and 1494.Sq :] 1495stands for the list of all characters belonging to that class. 1496Supported character classes: 1497.Bl -column "xdigit" "xdigit" "xdigit" -offset indent 1498.It Li "alnum" Ta "cntrl" Ta "lower" Ta "space" 1499.It Li "alpha" Ta "digit" Ta "print" Ta "upper" 1500.It Li "blank" Ta "graph" Ta "punct" Ta "xdigit" 1501.El 1502.Pp 1503These match characters using the macros specified in 1504.Xr ctype 3 . 1505A character class may not be used as an endpoint of a range. 1506.It [!..] 1507Like [..], 1508except it matches any character not inside the brackets. 1509.Sm off 1510.It *( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) 1511.Sm on 1512Matches any string of characters that matches zero or more occurrences of the 1513specified patterns. 1514Example: The pattern 1515.Ic *(foo|bar) 1516matches the strings 1517.Dq , 1518.Dq foo , 1519.Dq bar , 1520.Dq foobarfoo , 1521etc. 1522.Sm off 1523.It +( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) 1524.Sm on 1525Matches any string of characters that matches one or more occurrences of the 1526specified patterns. 1527Example: The pattern 1528.Ic +(foo|bar) 1529matches the strings 1530.Dq foo , 1531.Dq bar , 1532.Dq foobar , 1533etc. 1534.Sm off 1535.It ?( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) 1536.Sm on 1537Matches the empty string or a string that matches one of the specified 1538patterns. 1539Example: The pattern 1540.Ic ?(foo|bar) 1541only matches the strings 1542.Dq , 1543.Dq foo , 1544and 1545.Dq bar . 1546.Sm off 1547.It @( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) 1548.Sm on 1549Matches a string that matches one of the specified patterns. 1550Example: The pattern 1551.Ic @(foo|bar) 1552only matches the strings 1553.Dq foo 1554and 1555.Dq bar . 1556.Sm off 1557.It !( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) 1558.Sm on 1559Matches any string that does not match one of the specified patterns. 1560Examples: The pattern 1561.Ic !(foo|bar) 1562matches all strings except 1563.Dq foo 1564and 1565.Dq bar ; 1566the pattern 1567.Ic !(*) 1568matches no strings; the pattern 1569.Ic !(?)*\& 1570matches all strings (think about it). 1571.El 1572.Pp 1573Note that 1574.Nm pdksh 1575currently never matches 1576.Sq \&. 1577and 1578.Sq .. , 1579but the original 1580.Nm ksh , 1581Bourne 1582.Nm sh , 1583and bash do, so this may have to change (too bad). 1584.Pp 1585Note that none of the above pattern elements match either a period 1586.Pq Sq \&. 1587at the start of a file name or a slash 1588.Pq Sq / , 1589even if they are explicitly used in a [..] sequence; also, the names 1590.Sq \&. 1591and 1592.Sq .. 1593are never matched, even by the pattern 1594.Sq .* . 1595.Pp 1596If the 1597.Ic markdirs 1598option is set, any directories that result from file name generation are marked 1599with a trailing 1600.Ql / . 1601.Ss Input/output redirection 1602When a command is executed, its standard input, standard output, and standard 1603error (file descriptors 0, 1, and 2, respectively) are normally inherited from 1604the shell. 1605Three exceptions to this are commands in pipelines, for which 1606standard input and/or standard output are those set up by the pipeline, 1607asynchronous commands created when job control is disabled, for which standard 1608input is initially set to be from 1609.Pa /dev/null , 1610and commands for which any of the following redirections have been specified: 1611.Bl -tag -width Ds 1612.It \*(Gt Ar file 1613Standard output is redirected to 1614.Ar file . 1615If 1616.Ar file 1617does not exist, it is created; if it does exist, is a regular file, and the 1618.Ic noclobber 1619option is set, an error occurs; otherwise, the file is truncated. 1620Note that this means the command 1621.Ic cmd \*(Lt foo \*(Gt foo 1622will open 1623.Ar foo 1624for reading and then truncate it when it opens it for writing, before 1625.Ar cmd 1626gets a chance to actually read 1627.Ar foo . 1628.It \*(Gt\*(Ba Ar file 1629Same as 1630.Ic \*(Gt , 1631except the file is truncated, even if the 1632.Ic noclobber 1633option is set. 1634.It \*(Gt\*(Gt Ar file 1635Same as 1636.Ic \*(Gt , 1637except if 1638.Ar file 1639exists it is appended to instead of being truncated. 1640Also, the file is opened 1641in append mode, so writes always go to the end of the file (see 1642.Xr open 2 ) . 1643.It \*(Lt Ar file 1644Standard input is redirected from 1645.Ar file , 1646which is opened for reading. 1647.It \*(Lt\*(Gt Ar file 1648Same as 1649.Ic \*(Lt , 1650except the file is opened for reading and writing. 1651.It \*(Lt\*(Lt Ar marker 1652After reading the command line containing this kind of redirection (called a 1653.Dq here document ) , 1654the shell copies lines from the command source into a temporary file until a 1655line matching 1656.Ar marker 1657is read. 1658When the command is executed, standard input is redirected from the 1659temporary file. 1660If 1661.Ar marker 1662contains no quoted characters, the contents of the temporary file are processed 1663as if enclosed in double quotes each time the command is executed, so 1664parameter, command, and arithmetic substitutions are performed, along with 1665backslash 1666.Pq Sq \e 1667escapes for 1668.Ql $ , 1669.Ql ` , 1670.Ql \e , 1671and 1672.Ql \enewline . 1673If multiple here documents are used on the same command line, they are saved in 1674order. 1675.It \*(Lt\*(Lt- Ar marker 1676Same as 1677.Ic \*(Lt\*(Lt , 1678except leading tabs are stripped from lines in the here document. 1679.It \*(Lt& Ar fd 1680Standard input is duplicated from file descriptor 1681.Ar fd . 1682.Ar fd 1683can be a single digit, indicating the number of an existing file descriptor; 1684the letter 1685.Ql p , 1686indicating the file descriptor associated with the output of the current 1687co-process; or the character 1688.Ql - , 1689indicating standard input is to be closed. 1690.It \*(Gt& Ar fd 1691Same as 1692.Ic \*(Lt& , 1693except the operation is done on standard output. 1694.El 1695.Pp 1696In any of the above redirections, the file descriptor that is redirected 1697(i.e. standard input or standard output) 1698can be explicitly given by preceding the 1699redirection with a single digit. 1700Parameter, command, and arithmetic 1701substitutions, tilde substitutions, and (if the shell is interactive) 1702file name generation are all performed on the 1703.Ar file , 1704.Ar marker , 1705and 1706.Ar fd 1707arguments of redirections. 1708Note, however, that the results of any file name 1709generation are only used if a single file is matched; if multiple files match, 1710the word with the expanded file name generation characters is used. 1711Note 1712that in restricted shells, redirections which can create files cannot be used. 1713.Pp 1714For simple-commands, redirections may appear anywhere in the command; for 1715compound-commands 1716.Po 1717.Ic if 1718statements, etc. 1719.Pc , 1720any redirections must appear at the end. 1721Redirections are processed after 1722pipelines are created and in the order they are given, so the following 1723will print an error with a line number prepended to it: 1724.Pp 1725.D1 $ cat /foo/bar 2\*(Gt&1 \*(Gt /dev/null \*(Ba cat -n 1726.Ss Arithmetic expressions 1727Integer arithmetic expressions can be used with the 1728.Ic let 1729command, inside $((..)) expressions, inside array references (e.g.\& 1730.Ar name Ns Bq Ar expr ) , 1731as numeric arguments to the 1732.Ic test 1733command, and as the value of an assignment to an integer parameter. 1734.Pp 1735Expressions may contain alpha-numeric parameter identifiers, array references, 1736and integer constants and may be combined with the following C operators 1737(listed and grouped in increasing order of precedence): 1738.Pp 1739Unary operators: 1740.Bd -literal -offset indent 1741+ - ! ~ ++ -- 1742.Ed 1743.Pp 1744Binary operators: 1745.Bd -literal -offset indent 1746, 1747= *= /= %= += -= \*(Lt\*(Lt= \*(Gt\*(Gt= &= ^= \*(Ba= 1748\*(Ba\*(Ba 1749&& 1750\*(Ba 1751^ 1752& 1753== != 1754\*(Lt \*(Lt= \*(Gt= \*(Gt 1755\*(Lt\*(Lt \*(Gt\*(Gt 1756+ - 1757* / % 1758.Ed 1759.Pp 1760Ternary operators: 1761.Bd -literal -offset indent 1762?: (precedence is immediately higher than assignment) 1763.Ed 1764.Pp 1765Grouping operators: 1766.Bd -literal -offset indent 1767( ) 1768.Ed 1769.Pp 1770Integer constants may be specified with arbitrary bases using the notation 1771.Ar base Ns # Ns Ar number , 1772where 1773.Ar base 1774is a decimal integer specifying the base, and 1775.Ar number 1776is a number in the specified base. 1777Additionally, 1778integers may be prefixed with 1779.Sq 0X 1780or 1781.Sq 0x 1782(specifying base 16) 1783or 1784.Sq 0 1785(base 8) 1786in all forms of arithmetic expressions, 1787except as numeric arguments to the 1788.Ic test 1789command. 1790.Pp 1791The operators are evaluated as follows: 1792.Bl -tag -width Ds -offset indent 1793.It unary + 1794Result is the argument (included for completeness). 1795.It unary - 1796Negation. 1797.It \&! 1798Logical NOT; 1799the result is 1 if argument is zero, 0 if not. 1800.It ~ 1801Arithmetic (bit-wise) NOT. 1802.It ++ 1803Increment; must be applied to a parameter (not a literal or other expression). 1804The parameter is incremented by 1. 1805When used as a prefix operator, the result 1806is the incremented value of the parameter; when used as a postfix operator, the 1807result is the original value of the parameter. 1808.It -- 1809Similar to 1810.Ic ++ , 1811except the parameter is decremented by 1. 1812.It \&, 1813Separates two arithmetic expressions; the left-hand side is evaluated first, 1814then the right. 1815The result is the value of the expression on the right-hand side. 1816.It = 1817Assignment; the variable on the left is set to the value on the right. 1818.It Xo 1819.No *= /= += -= \*(Lt\*(Lt= 1820.No \*(Gt\*(Gt= &= ^= \*(Ba= 1821.Xc 1822Assignment operators. 1823.Sm off 1824.Ao Ar var Ac Xo 1825.Aq Ar op 1826.No = Aq Ar expr 1827.Xc 1828.Sm on 1829is the same as 1830.Sm off 1831.Ao Ar var Ac Xo 1832.No = Aq Ar var 1833.Aq Ar op 1834.Aq Ar expr , 1835.Xc 1836.Sm on 1837with any operator precedence in 1838.Aq Ar expr 1839preserved. 1840For example, 1841.Dq var1 *= 5 + 3 1842is the same as specifying 1843.Dq var1 = var1 * (5 + 3) . 1844.It \*(Ba\*(Ba 1845Logical OR; 1846the result is 1 if either argument is non-zero, 0 if not. 1847The right argument is evaluated only if the left argument is zero. 1848.It && 1849Logical AND; 1850the result is 1 if both arguments are non-zero, 0 if not. 1851The right argument is evaluated only if the left argument is non-zero. 1852.It \*(Ba 1853Arithmetic (bit-wise) OR. 1854.It ^ 1855Arithmetic (bit-wise) XOR 1856(exclusive-OR). 1857.It & 1858Arithmetic (bit-wise) AND. 1859.It == 1860Equal; the result is 1 if both arguments are equal, 0 if not. 1861.It != 1862Not equal; the result is 0 if both arguments are equal, 1 if not. 1863.It \*(Lt 1864Less than; the result is 1 if the left argument is less than the right, 0 if 1865not. 1866.It \*(Lt= \*(Gt= \*(Gt 1867Less than or equal, greater than or equal, greater than. 1868See 1869.Ic \*(Lt . 1870.It \*(Lt\*(Lt \*(Gt\*(Gt 1871Shift left (right); the result is the left argument with its bits shifted left 1872(right) by the amount given in the right argument. 1873.It + - * / 1874Addition, subtraction, multiplication, and division. 1875.It % 1876Remainder; the result is the remainder of the division of the left argument by 1877the right. 1878The sign of the result is unspecified if either argument is negative. 1879.It Xo 1880.Sm off 1881.Aq Ar arg1 ? 1882.Aq Ar arg2 : 1883.Aq Ar arg3 1884.Sm on 1885.Xc 1886If 1887.Aq Ar arg1 1888is non-zero, the result is 1889.Aq Ar arg2 ; 1890otherwise the result is 1891.Aq Ar arg3 . 1892.El 1893.Ss Functions 1894Functions are defined using either Korn shell 1895.Ic function Ar function-name 1896syntax or the Bourne/POSIX shell 1897.Ar function-name Ns () 1898syntax (see below for the difference between the two forms). 1899Functions are like 1900.Li .-scripts 1901(i.e. scripts sourced using the 1902.Sq \&. 1903built-in) 1904in that they are executed in the current environment. 1905However, unlike 1906.Li .-scripts , 1907shell arguments (i.e. positional parameters $1, $2, etc.)\& 1908are never visible inside them. 1909When the shell is determining the location of a command, functions 1910are searched after special built-in commands, before regular and 1911non-regular built-ins, and before the 1912.Ev PATH 1913is searched. 1914.Pp 1915An existing function may be deleted using 1916.Ic unset Fl f Ar function-name . 1917A list of functions can be obtained using 1918.Ic typeset +f 1919and the function definitions can be listed using 1920.Ic typeset -f . 1921The 1922.Ic autoload 1923command (which is an alias for 1924.Ic typeset -fu ) 1925may be used to create undefined functions: when an undefined function is 1926executed, the shell searches the path specified in the 1927.Ev FPATH 1928parameter for a file with the same name as the function, which, if found, is 1929read and executed. 1930If after executing the file the named function is found to 1931be defined, the function is executed; otherwise, the normal command search is 1932continued (i.e. the shell searches the regular built-in command table and 1933.Ev PATH ) . 1934Note that if a command is not found using 1935.Ev PATH , 1936an attempt is made to autoload a function using 1937.Ev FPATH 1938(this is an undocumented feature of the original Korn shell). 1939.Pp 1940Functions can have two attributes, 1941.Dq trace 1942and 1943.Dq export , 1944which can be set with 1945.Ic typeset -ft 1946and 1947.Ic typeset -fx , 1948respectively. 1949When a traced function is executed, the shell's 1950.Ic xtrace 1951option is turned on for the function's duration; otherwise, the 1952.Ic xtrace 1953option is turned off. 1954The 1955.Dq export 1956attribute of functions is currently not used. 1957In the original Korn shell, 1958exported functions are visible to shell scripts that are executed. 1959.Pp 1960Since functions are executed in the current shell environment, parameter 1961assignments made inside functions are visible after the function completes. 1962If this is not the desired effect, the 1963.Ic typeset 1964command can be used inside a function to create a local parameter. 1965Note that special parameters (e.g.\& 1966.Ic \&$$ , $! ) 1967can't be scoped in this way. 1968.Pp 1969The exit status of a function is that of the last command executed in the 1970function. 1971A function can be made to finish immediately using the 1972.Ic return 1973command; this may also be used to explicitly specify the exit status. 1974.Pp 1975Functions defined with the 1976.Ic function 1977reserved word are treated differently in the following ways from functions 1978defined with the 1979.Ic () 1980notation: 1981.Bl -bullet 1982.It 1983The $0 parameter is set to the name of the function 1984(Bourne-style functions leave $0 untouched). 1985.It 1986Parameter assignments preceding function calls are not kept in the shell 1987environment (executing Bourne-style functions will keep assignments). 1988.It 1989.Ev OPTIND 1990is saved/reset and restored on entry and exit from the function so 1991.Ic getopts 1992can be used properly both inside and outside the function (Bourne-style 1993functions leave 1994.Ev OPTIND 1995untouched, so using 1996.Ic getopts 1997inside a function interferes with using 1998.Ic getopts 1999outside the function). 2000.El 2001.Pp 2002In the future, the following differences will also be added: 2003.Bl -bullet 2004.It 2005A separate trap/signal environment will be used during the execution of 2006functions. 2007This will mean that traps set inside a function will not affect the 2008shell's traps and signals that are not ignored in the shell (but may be 2009trapped) will have their default effect in a function. 2010.It 2011The EXIT trap, if set in a function, will be executed after the function 2012returns. 2013.El 2014.Ss POSIX mode 2015The shell is intended to be POSIX compliant; 2016however, in some cases, POSIX behaviour is contrary either to 2017the original Korn shell behaviour or to user convenience. 2018How the shell behaves in these cases is determined by the state of the 2019.Ic posix 2020option 2021.Pq Ic set -o posix . 2022If it is on, the POSIX behaviour is followed; otherwise, it is not. 2023The 2024.Ic posix 2025option is set automatically when the shell starts up if the environment 2026contains the 2027.Ev POSIXLY_CORRECT 2028parameter. 2029The shell can also be compiled so that it is in POSIX mode by default; 2030however, this is usually not desirable. 2031.Pp 2032The following is a list of things that are affected by the state of the 2033.Ic posix 2034option: 2035.Bl -bullet 2036.It 2037Reading of 2038.Ev $ENV : 2039if not in 2040.Ic posix 2041mode, the 2042.Ev ENV 2043parameter is not expanded and included when the shell starts. 2044.It 2045Occurrences of 2046.Ic \e\&" 2047inside double quoted 2048.Ic `..` 2049command substitutions. 2050In POSIX mode, the 2051.Ic \e\&" 2052is interpreted when the command is interpreted; 2053in non-POSIX mode, 2054the backslash is stripped before the command substitution is interpreted. 2055For example, 2056.Ic echo \&"`echo \e\&"hi\e\&"`\&" 2057produces 2058.Dq \&"hi\&" 2059in POSIX mode, 2060.Dq hi 2061in non-POSIX mode. 2062To avoid problems, use the 2063.Ic $(...)\& 2064form of command substitution. 2065.It 2066.Ic kill -l 2067output. 2068In POSIX mode, only signal names are listed (in a single line); 2069in non-POSIX mode, 2070signal numbers, names, and descriptions are printed (in columns). 2071In the future, a new option 2072.Pq Fl v No perhaps 2073will be added to distinguish the two behaviours. 2074.It 2075.Ic echo 2076options. 2077In POSIX mode, 2078.Fl e 2079and 2080.Fl E 2081are not treated as options, but printed like other arguments; 2082in non-POSIX mode, these options control the interpretation 2083of backslash sequences. 2084.It 2085.Ic fg 2086exit status. 2087In POSIX mode, the exit status is 0 if no errors occur; 2088in non-POSIX mode, the exit status is that of the last foregrounded job. 2089.It 2090.Ic getopts . 2091In POSIX mode, options must start with a 2092.Ql - ; 2093in non-POSIX mode, options can start with either 2094.Ql - 2095or 2096.Ql + . 2097.It 2098.Ic set - . 2099In POSIX mode, this does not clear the 2100.Ic verbose 2101or 2102.Ic xtrace 2103options; in non-POSIX mode, it does. 2104.It 2105.Ic set 2106exit status. 2107In POSIX mode, the exit status of 2108.Ic set 2109is 0 if there are no errors; 2110in non-POSIX mode, the exit status is that of any 2111command substitutions performed in generating the 2112.Ic set 2113command. 2114For example, 2115.Ic set -- `false`; echo $?\& 2116prints 0 in POSIX mode, 1 in non-POSIX mode. 2117This construct is used in most shell scripts that use the old 2118.Xr getopt 1 2119command. 2120.It 2121Argument expansion of the 2122.Ic alias , 2123.Ic export , 2124.Ic readonly , 2125and 2126.Ic typeset 2127commands. 2128In POSIX mode, normal argument expansion is done; in non-POSIX mode, 2129field splitting, file globbing, and (normal) tilde expansion 2130are turned off, while assignment tilde expansion is turned on. 2131.It 2132Signal specification. 2133In POSIX mode, signals can be specified as digits, only 2134if signal numbers match POSIX values 2135(i.e. HUP=1, INT=2, QUIT=3, ABRT=6, KILL=9, ALRM=14, and TERM=15); 2136in non-POSIX mode, signals can always be digits. 2137.It 2138Alias expansion. 2139In POSIX mode, alias expansion is only carried out when reading command words; 2140in non-POSIX mode, alias expansion is carried out on any 2141word following an alias that ended in a space. 2142For example, the following 2143.Ic for 2144loop uses parameter 2145.Sq i 2146in POSIX mode and 2147.Sq j 2148in non-POSIX mode: 2149.Bd -literal -offset indent 2150alias a='for ' i='j' 2151a i in 1 2; do echo i=$i j=$j; done 2152.Ed 2153.Pp 2154.It 2155.Ic test . 2156In POSIX mode, the expression 2157.Sq Fl t 2158(preceded by some number of 2159.Sq \&! 2160arguments) is always true as it is a non-zero length string; 2161in non-POSIX mode, it tests if file descriptor 1 is a 2162.Xr tty 4 2163(i.e. the 2164.Ar fd 2165argument to the 2166.Fl t 2167test may be left out and defaults to 1). 2168.El 2169.Ss Command execution 2170After evaluation of command-line arguments, redirections, and parameter 2171assignments, the type of command is determined: a special built-in, a 2172function, a regular built-in, or the name of a file to execute found using the 2173.Ev PATH 2174parameter. 2175The checks are made in the above order. 2176Special built-in commands differ from other commands in that the 2177.Ev PATH 2178parameter is not used to find them, an error during their execution can 2179cause a non-interactive shell to exit, and parameter assignments that are 2180specified before the command are kept after the command completes. 2181Just to confuse things, if the 2182.Ic posix 2183option is turned off (see the 2184.Ic set 2185command below), some special commands are very special in that no field 2186splitting, file globbing, nor tilde expansion is performed 2187on arguments that look like assignments. 2188Regular built-in commands are different only in that the 2189.Ev PATH 2190parameter is not used to find them. 2191.Pp 2192The original 2193.Nm ksh 2194and POSIX differ somewhat in which commands are considered 2195special or regular: 2196.Pp 2197POSIX special commands 2198.Pp 2199.Ic \&. , \&: , break , continue , 2200.Ic eval , exec , exit , export , 2201.Ic readonly , return , set , shift , 2202.Ic trap , unset 2203.Pp 2204Additional 2205.Nm 2206special commands 2207.Pp 2208.Ic builtin , times , typeset 2209.Pp 2210Very special commands 2211.Pq non-POSIX 2212.Pp 2213.Ic alias , readonly , set , typeset 2214.Pp 2215POSIX regular commands 2216.Pp 2217.Ic alias , bg , cd , command , 2218.Ic false , fc , fg , getopts , 2219.Ic jobs , kill , read , true , 2220.Ic umask , unalias , wait 2221.Pp 2222Additional 2223.Nm 2224regular commands 2225.Pp 2226.Ic \&[ , echo , let , print , 2227.Ic pwd , test , ulimit , whence 2228.Pp 2229In the future, the additional 2230.Nm 2231special and regular commands may be treated 2232differently from the POSIX special and regular commands. 2233.Pp 2234Once the type of command has been determined, any command-line parameter 2235assignments are performed and exported for the duration of the command. 2236.Pp 2237The following describes the special and regular built-in commands: 2238.Pp 2239.Bl -tag -width Ds -compact 2240.It Ic \&. Ar file Op Ar arg ... 2241Execute the commands in 2242.Ar file 2243in the current environment. 2244The file is searched for in the directories of 2245.Ev PATH . 2246If arguments are given, the positional parameters may be used to access them 2247while 2248.Ar file 2249is being executed. 2250If no arguments are given, the positional parameters are 2251those of the environment the command is used in. 2252.Pp 2253.It Ic \&: Op Ar ... 2254The null command. 2255Exit status is set to zero. 2256.Pp 2257.It Xo Ic alias 2258.Oo Fl d \*(Ba t Oo Fl r Oc \*(Ba 2259.Cm +-x Oc 2260.Op Fl p 2261.Op Cm + 2262.Oo Ar name 2263.Op Ns = Ns Ar value 2264.Ar ... Oc 2265.Xc 2266Without arguments, 2267.Ic alias 2268lists all aliases. 2269For any name without a value, the existing alias is listed. 2270Any name with a value defines an alias (see 2271.Sx Aliases 2272above). 2273.Pp 2274When listing aliases, one of two formats is used. 2275Normally, aliases are listed as 2276.Ar name Ns = Ns Ar value , 2277where 2278.Ar value 2279is quoted. 2280If options were preceded with 2281.Ql + , 2282or a lone 2283.Ql + 2284is given on the command line, only 2285.Ar name 2286is printed. 2287.Pp 2288The 2289.Fl d 2290option causes directory aliases, which are used in tilde expansion, to be 2291listed or set (see 2292.Sx Tilde expansion 2293above). 2294.Pp 2295If the 2296.Fl p 2297option is used, each alias is prefixed with the string 2298.Dq alias\ \& . 2299.Pp 2300The 2301.Fl t 2302option indicates that tracked aliases are to be listed/set (values specified on 2303the command line are ignored for tracked aliases). 2304The 2305.Fl r 2306option indicates that all tracked aliases are to be reset. 2307.Pp 2308The 2309.Fl x 2310option sets 2311.Pq Ic +x No clears 2312the export attribute of an alias, or, if no names are given, lists the aliases 2313with the export attribute (exporting an alias has no effect). 2314.Pp 2315.It Ic bg Op Ar job ... 2316Resume the specified stopped job(s) in the background. 2317If no jobs are specified, 2318.Ic %+ 2319is assumed. 2320See 2321.Sx Job control 2322below for more information. 2323.Pp 2324.It Ic break Op Ar level 2325Exit the 2326.Ar level Ns th 2327inner-most 2328.Ic for , 2329.Ic until , 2330or 2331.Ic while 2332loop. 2333.Ar level 2334defaults to 1. 2335.Pp 2336.It Ic builtin Ar command Op Ar arg ... 2337Execute the built-in command 2338.Ar command . 2339.Pp 2340.It Xo 2341.Ic cd 2342.Op Fl LP 2343.Op Ar dir 2344.Xc 2345Set the working directory to 2346.Ar dir . 2347If the parameter 2348.Ev CDPATH 2349is set, it lists the search path for the directory containing 2350.Ar dir . 2351A 2352.Dv NULL 2353path means the current directory. 2354If 2355.Ar dir 2356is found in any component of the 2357.Ev CDPATH 2358search path other than the 2359.Dv NULL 2360path, the name of the new working directory will be written to standard output. 2361If 2362.Ar dir 2363is missing, the home directory 2364.Ev HOME 2365is used. 2366If 2367.Ar dir 2368is 2369.Ql - , 2370the previous working directory is used (see the 2371.Ev OLDPWD 2372parameter). 2373.Pp 2374If the 2375.Fl L 2376option (logical path) is used or if the 2377.Ic physical 2378option isn't set (see the 2379.Ic set 2380command below), references to 2381.Sq .. 2382in 2383.Ar dir 2384are relative to the path used to get to the directory. 2385If the 2386.Fl P 2387option (physical path) is used or if the 2388.Ic physical 2389option is set, 2390.Sq .. 2391is relative to the filesystem directory tree. 2392The 2393.Ev PWD 2394and 2395.Ev OLDPWD 2396parameters are updated to reflect the current and old working directory, 2397respectively. 2398.Pp 2399.It Xo 2400.Ic cd 2401.Op Fl LP 2402.Ar old new 2403.Xc 2404The string 2405.Ar new 2406is substituted for 2407.Ar old 2408in the current directory, and the shell attempts to change to the new 2409directory. 2410.Pp 2411.It Xo 2412.Ic command 2413.Op Fl p 2414.Ar cmd 2415.Op Ar arg ... 2416.Xc 2417.Ar cmd 2418is executed exactly as if 2419.Ic command 2420had not been specified, with two exceptions: 2421firstly, 2422.Ar cmd 2423cannot be a shell function; 2424and secondly, special built-in commands lose their specialness 2425(i.e. redirection and utility errors do not cause the shell to 2426exit, and command assignments are not permanent). 2427.Pp 2428If the 2429.Fl p 2430option is given, a default search path is used instead of the current value of 2431.Ev PATH 2432(the actual value of the default path is system dependent: on 2433POSIX-ish systems, it is the value returned by 2434.Ic getconf CS_PATH ) . 2435.Pp 2436.It Ic continue Op Ar level 2437Jumps to the beginning of the 2438.Ar level Ns th 2439inner-most 2440.Ic for , 2441.Ic until , 2442or 2443.Ic while 2444loop. 2445.Ar level 2446defaults to 1. 2447.Pp 2448.It Xo 2449.Ic echo 2450.Op Fl Een 2451.Op Ar arg ... 2452.Xc 2453Prints its arguments (separated by spaces) followed by a newline, to the 2454standard output. 2455The newline is suppressed if any of the arguments contain the 2456backslash sequence 2457.Ql \ec . 2458See the 2459.Ic print 2460command below for a list of other backslash sequences that are recognized. 2461.Pp 2462The options are provided for compatibility with 2463.Bx 2464shell scripts. 2465The 2466.Fl n 2467option suppresses the trailing newline, 2468.Fl e 2469enables backslash interpretation (a no-op, since this is normally done), and 2470.Fl E 2471suppresses backslash interpretation. 2472If the 2473.Ic posix 2474option is set, only the first argument is treated as an option, and only 2475if it is exactly 2476.Dq -n . 2477.Pp 2478.It Ic eval Ar command ... 2479The arguments are concatenated (with spaces between them) to form a single 2480string which the shell then parses and executes in the current environment. 2481.Pp 2482.It Xo 2483.Ic exec 2484.Op Ar command Op Ar arg ... 2485.Xc 2486The command is executed without forking, replacing the shell process. 2487.Pp 2488If no command is given except for I/O redirection, the I/O redirection is 2489permanent and the shell is 2490not replaced. 2491Any file descriptors which are opened or 2492.Xr dup 2 Ns 'd 2493in this way are made available to other executed commands (note that the Korn 2494shell differs here: it does not pass on file descriptors greater than 2). 2495.Pp 2496.It Ic exit Op Ar status 2497The shell exits with the specified exit status. 2498If 2499.Ar status 2500is not specified, the exit status is the current value of the 2501.Ic $?\& 2502parameter. 2503.Pp 2504.It Xo 2505.Ic export 2506.Op Fl p 2507.Op Ar parameter Ns Op = Ns Ar value 2508.Xc 2509Sets the export attribute of the named parameters. 2510Exported parameters are passed in the environment to executed commands. 2511If values are specified, the named parameters are also assigned. 2512.Pp 2513If no parameters are specified, the names of all parameters with the export 2514attribute are printed one per line, unless the 2515.Fl p 2516option is used, in which case 2517.Ic export 2518commands defining all exported parameters, including their values, are printed. 2519.Pp 2520.It Ic false 2521A command that exits with a non-zero status. 2522.Pp 2523.It Xo 2524.Ic fc 2525.Cm -e - \*(Ba Fl s 2526.Op Fl g 2527.Op Ar old Ns = Ns Ar new 2528.Op Ar prefix 2529.Xc 2530Re-execute the selected command (the previous command by default) after 2531performing the optional substitution of 2532.Ar old 2533with 2534.Ar new . 2535If 2536.Fl g 2537is specified, all occurrences of 2538.Ar old 2539are replaced with 2540.Ar new . 2541The meaning of 2542.Cm -e - 2543and 2544.Fl s 2545is identical: re-execute the selected command without invoking an editor. 2546This command is usually accessed with the predefined 2547.Ic alias r='fc -e -' . 2548.Pp 2549.It Ic fg Op Ar job ... 2550Resume the specified job(s) in the foreground. 2551If no jobs are specified, 2552.Ic %+ 2553is assumed. 2554See 2555.Sx Job control 2556below for more information. 2557.Pp 2558.It Xo 2559.Ic getopts 2560.Ar optstring name 2561.Op Ar arg ... 2562.Xc 2563Used by shell procedures to parse the specified arguments (or positional 2564parameters, if no arguments are given) and to check for legal options. 2565.Ar optstring 2566contains the option letters that 2567.Ic getopts 2568is to recognize. 2569If a letter is followed by a colon, the option is expected to 2570have an argument. 2571Options that do not take arguments may be grouped in a single argument. 2572If an option takes an argument and the option character is not the 2573last character of the argument it is found in, the remainder of the argument is 2574taken to be the option's argument; otherwise, the next argument is the option's 2575argument. 2576.Pp 2577Each time 2578.Ic getopts 2579is invoked, it places the next option in the shell parameter 2580.Ar name 2581and the index of the argument to be processed by the next call to 2582.Ic getopts 2583in the shell parameter 2584.Ev OPTIND . 2585If the option was introduced with a 2586.Ql + , 2587the option placed in 2588.Ar name 2589is prefixed with a 2590.Ql + . 2591When an option requires an argument, 2592.Ic getopts 2593places it in the shell parameter 2594.Ev OPTARG . 2595.Pp 2596When an illegal option or a missing option argument is encountered, a question 2597mark or a colon is placed in 2598.Ar name 2599(indicating an illegal option or missing argument, respectively) and 2600.Ev OPTARG 2601is set to the option character that caused the problem. 2602Furthermore, if 2603.Ar optstring 2604does not begin with a colon, a question mark is placed in 2605.Ar name , 2606.Ev OPTARG 2607is unset, and an error message is printed to standard error. 2608.Pp 2609When the end of the options is encountered, 2610.Ic getopts 2611exits with a non-zero exit status. 2612Options end at the first (non-option 2613argument) argument that does not start with a 2614.Ql - , 2615or when a 2616.Ql -- 2617argument is encountered. 2618.Pp 2619Option parsing can be reset by setting 2620.Ev OPTIND 2621to 1 (this is done automatically whenever the shell or a shell procedure is 2622invoked). 2623.Pp 2624Warning: Changing the value of the shell parameter 2625.Ev OPTIND 2626to a value other than 1, or parsing different sets of arguments without 2627resetting 2628.Ev OPTIND , 2629may lead to unexpected results. 2630.Pp 2631.It Xo 2632.Ic hash 2633.Op Fl r 2634.Op Ar name ... 2635.Xc 2636Without arguments, any hashed executable command pathnames are listed. 2637The 2638.Fl r 2639option causes all hashed commands to be removed from the hash table. 2640Each 2641.Ar name 2642is searched as if it were a command name and added to the hash table if it is 2643an executable command. 2644.Pp 2645.It Xo 2646.Ic jobs 2647.Op Fl lnp 2648.Op Ar job ... 2649.Xc 2650Display information about the specified job(s); if no jobs are specified, all 2651jobs are displayed. 2652The 2653.Fl n 2654option causes information to be displayed only for jobs that have changed 2655state since the last notification. 2656If the 2657.Fl l 2658option is used, the process ID of each process in a job is also listed. 2659The 2660.Fl p 2661option causes only the process group of each job to be printed. 2662See 2663.Sx Job control 2664below for the format of 2665.Ar job 2666and the displayed job. 2667.Pp 2668.It Xo 2669.Ic kill 2670.Oo Fl s Ar signame \*(Ba 2671.No - Ns Ar signum \*(Ba 2672.No - Ns Ar signame Oc 2673.No { Ar job \*(Ba pid \*(Ba pgrp No } 2674.Ar ... 2675.Xc 2676Send the specified signal to the specified jobs, process IDs, or process 2677groups. 2678If no signal is specified, the 2679.Dv TERM 2680signal is sent. 2681If a job is specified, the signal is sent to the job's process group. 2682See 2683.Sx Job control 2684below for the format of 2685.Ar job . 2686.Pp 2687.It Xo 2688.Ic kill 2689.Fl l 2690.Op Ar exit-status ... 2691.Xc 2692Print the signal name corresponding to 2693.Ar exit-status . 2694If no arguments are specified, a list of all the signals, their numbers, and 2695a short description of them are printed. 2696.Pp 2697.It Xo 2698.Ic print 2699.Oo 2700.Fl nrsu Ns Oo Ar n Oc \*(Ba 2701.Fl R Op Fl en 2702.Oc 2703.Op Ar argument ... 2704.Xc 2705.Ic print 2706prints its arguments on the standard output, separated by spaces and 2707terminated with a newline. 2708The 2709.Fl n 2710option suppresses the newline. 2711By default, certain C escapes are translated. 2712These include 2713.Ql \eb , 2714.Ql \ef , 2715.Ql \en , 2716.Ql \er , 2717.Ql \et , 2718.Ql \ev , 2719and 2720.Ql \e0### 2721.Po 2722.Ql # 2723is an octal digit, of which there may be 0 to 3 2724.Pc . 2725.Ql \ec 2726is equivalent to using the 2727.Fl n 2728option. 2729.Ql \e 2730expansion may be inhibited with the 2731.Fl r 2732option. 2733The 2734.Fl s 2735option prints to the history file instead of standard output; and the 2736.Fl u 2737option prints to file descriptor 2738.Ar n 2739.Po 2740.Ar n 2741defaults to 1 if omitted 2742.Pc . 2743.Pp 2744The 2745.Fl R 2746option is used to emulate, to some degree, the 2747.Bx 2748.Xr echo 1 2749command, which does not process 2750.Ql \e 2751sequences unless the 2752.Fl e 2753option is given. 2754As above, the 2755.Fl n 2756option suppresses the trailing newline. 2757.Pp 2758.It Ic pwd Op Fl LP 2759Print the present working directory. 2760If the 2761.Fl L 2762option is used or if the 2763.Ic physical 2764option isn't set (see the 2765.Ic set 2766command below), the logical path is printed (i.e. the path used to 2767.Ic cd 2768to the current directory). 2769If the 2770.Fl P 2771option (physical path) is used or if the 2772.Ic physical 2773option is set, the path determined from the filesystem (by following 2774.Sq .. 2775directories to the root directory) is printed. 2776.Pp 2777.It Xo 2778.Ic read 2779.Op Fl rsu Ns Op Ar n 2780.Op Ar parameter ... 2781.Xc 2782Reads a line of input from the standard input, separates the line into fields 2783using the 2784.Ev IFS 2785parameter (see 2786.Sx Substitution 2787above), and assigns each field to the specified parameters. 2788If there are more parameters than fields, the extra parameters are set to 2789.Dv NULL , 2790or alternatively, if there are more fields than parameters, the last parameter 2791is assigned the remaining fields (inclusive of any separating spaces). 2792If no parameters are specified, the 2793.Ev REPLY 2794parameter is used. 2795If the input line ends in a backslash and the 2796.Fl r 2797option was not used, the backslash and the newline are stripped and more input 2798is read. 2799If no input is read, 2800.Ic read 2801exits with a non-zero status. 2802.Pp 2803The first parameter may have a question mark and a string appended to it, in 2804which case the string is used as a prompt (printed to standard error before 2805any input is read) if the input is a 2806.Xr tty 4 2807(e.g.\& 2808.Ic read nfoo?'number of foos: ' ) . 2809.Pp 2810The 2811.Fl u Ns Ar n 2812option causes input to be read from file descriptor 2813.Ar n 2814.Pf ( Ar n 2815defaults to 0 if omitted). 2816If the 2817.Fl s 2818option is used, input is saved to the history file. 2819.Pp 2820.It Xo 2821.Ic readonly 2822.Op Fl p 2823.Oo Ar parameter 2824.Op Ns = Ns Ar value 2825.Ar ... Oc 2826.Xc 2827Sets the read-only attribute of the named parameters. 2828If values are given, 2829parameters are set to them before setting the attribute. 2830Once a parameter is 2831made read-only, it cannot be unset and its value cannot be changed. 2832.Pp 2833If no parameters are specified, the names of all parameters with the read-only 2834attribute are printed one per line, unless the 2835.Fl p 2836option is used, in which case 2837.Ic readonly 2838commands defining all read-only parameters, including their values, are 2839printed. 2840.Pp 2841.It Ic return Op Ar status 2842Returns from a function or 2843.Ic .\& 2844script, with exit status 2845.Ar status . 2846If no 2847.Ar status 2848is given, the exit status of the last executed command is used. 2849If used outside of a function or 2850.Ic .\& 2851script, it has the same effect as 2852.Ic exit . 2853Note that 2854.Nm pdksh 2855treats both profile and 2856.Ev ENV 2857files as 2858.Ic .\& 2859scripts, while the original Korn shell only treats profiles as 2860.Ic .\& 2861scripts. 2862.Pp 2863.It Xo 2864.Ic set Op Ic +-abCefhkmnpsuvXx 2865.Op Ic +-o Ar option 2866.Op Ic +-A Ar name 2867.Op Fl - 2868.Op Ar arg ... 2869.Xc 2870The 2871.Ic set 2872command can be used to set 2873.Pq Ic - 2874or clear 2875.Pq Ic + 2876shell options, set the positional parameters, or set an array parameter. 2877Options can be changed using the 2878.Cm +-o Ar option 2879syntax, where 2880.Ar option 2881is the long name of an option, or using the 2882.Cm +- Ns Ar letter 2883syntax, where 2884.Ar letter 2885is the option's single letter name (not all options have a single letter name). 2886The following table lists both option letters (if they exist) and long names 2887along with a description of what the option does: 2888.Bl -tag -width 15n 2889.It Fl A Ar name 2890Sets the elements of the array parameter 2891.Ar name 2892to 2893.Ar arg ... 2894If 2895.Fl A 2896is used, the array is reset (i.e. emptied) first; if 2897.Ic +A 2898is used, the first N elements are set (where N is the number of arguments); 2899the rest are left untouched. 2900.It Fl a \*(Ba Ic allexport 2901All new parameters are created with the export attribute. 2902.It Fl b \*(Ba Ic notify 2903Print job notification messages asynchronously, instead of just before the 2904prompt. 2905Only used if job control is enabled 2906.Pq Fl m . 2907.It Fl C \*(Ba Ic noclobber 2908Prevent \*(Gt redirection from overwriting existing files. 2909Instead, \*(Gt\*(Ba must be used to force an overwrite. 2910.It Fl e \*(Ba Ic errexit 2911Exit (after executing the 2912.Dv ERR 2913trap) as soon as an error occurs or a command fails (i.e. exits with a 2914non-zero status). 2915This does not apply to commands whose exit status is 2916explicitly tested by a shell construct such as 2917.Ic if , 2918.Ic until , 2919.Ic while , 2920.Ic && , 2921.Ic || , 2922or 2923.Ic !\& 2924statements. 2925.It Fl f \*(Ba Ic noglob 2926Do not expand file name patterns. 2927.It Fl h \*(Ba Ic trackall 2928Create tracked aliases for all executed commands (see 2929.Sx Aliases 2930above). 2931Enabled by default for non-interactive shells. 2932.It Fl k \*(Ba Ic keyword 2933Parameter assignments are recognized anywhere in a command. 2934.It Fl m \*(Ba Ic monitor 2935Enable job control (default for interactive shells). 2936.It Fl n \*(Ba Ic noexec 2937Do not execute any commands. 2938Useful for checking the syntax of scripts 2939(ignored if interactive). 2940.It Fl p \*(Ba Ic privileged 2941The shell is a privileged shell. 2942It is set automatically if, when the shell starts, 2943the real UID or GID does not match 2944the effective UID (EUID) or GID (EGID), respectively. 2945See above for a description of what this means. 2946.It Fl s \*(Ba Ic stdin 2947If used when the shell is invoked, commands are read from standard input. 2948Set automatically if the shell is invoked with no arguments. 2949.Pp 2950When 2951.Fl s 2952is used with the 2953.Ic set 2954command it causes the specified arguments to be sorted before assigning them to 2955the positional parameters (or to array 2956.Ar name , 2957if 2958.Fl A 2959is used). 2960.It Fl u \*(Ba Ic nounset 2961Referencing of an unset parameter is treated as an error, unless one of the 2962.Ql - , 2963.Ql + , 2964or 2965.Ql = 2966modifiers is used. 2967.It Fl v \*(Ba Ic verbose 2968Write shell input to standard error as it is read. 2969.It Fl X \*(Ba Ic markdirs 2970Mark directories with a trailing 2971.Ql / 2972during file name generation. 2973.It Fl x \*(Ba Ic xtrace 2974Print commands and parameter assignments when they are executed, preceded by 2975the value of 2976.Ev PS4 . 2977.It Ic bgnice 2978Background jobs are run with lower priority. 2979.It Ic ignoreeof 2980The shell will not exit when end-of-file is read; 2981.Ic exit 2982must be used. 2983.It Ic interactive 2984The shell is an interactive shell. 2985This option can only be used when the shell is invoked. 2986See above for a description of what this means. 2987.It Ic login 2988The shell is a login shell. 2989This option can only be used when the shell is invoked. 2990See above for a description of what this means. 2991.It Ic nohup 2992Do not kill running jobs with a 2993.Dv SIGHUP 2994signal when a login shell exits. 2995Currently set by default, but this will 2996change in the future to be compatible with the original Korn shell (which 2997doesn't have this option, but does send the 2998.Dv SIGHUP 2999signal). 3000.It Ic nolog 3001No effect. 3002In the original Korn shell, this prevents function definitions from 3003being stored in the history file. 3004.It Ic physical 3005Causes the 3006.Ic cd 3007and 3008.Ic pwd 3009commands to use 3010.Dq physical 3011(i.e. the filesystem's) 3012.Sq .. 3013directories instead of 3014.Dq logical 3015directories (i.e. the shell handles 3016.Sq .. , 3017which allows the user to be oblivious of symbolic links to directories). 3018Clear by default. 3019Note that setting this option does not affect the current value of the 3020.Ev PWD 3021parameter; only the 3022.Ic cd 3023command changes 3024.Ev PWD . 3025See the 3026.Ic cd 3027and 3028.Ic pwd 3029commands above for more details. 3030.It Ic posix 3031Enable POSIX mode. 3032See 3033.Sx POSIX mode 3034above. 3035.It Ic restricted 3036The shell is a restricted shell. 3037This option can only be used when the shell is invoked. 3038See above for a description of what this means. 3039.It Ic vi 3040Enable 3041.Xr vi 1 Ns -like 3042command-line editing (interactive shells only). 3043.It Ic vi-esccomplete 3044In vi command-line editing, do command and file name completion when escape 3045(^[) is entered in command mode. 3046.It Ic vi-show8 3047Prefix characters with the eighth bit set with 3048.Sq M- . 3049If this option is not set, characters in the range 128\-160 are printed as is, 3050which may cause problems. 3051.It Ic vi-tabcomplete 3052In vi command-line editing, do command and file name completion when tab (^I) 3053is entered in insert mode. 3054.It Ic viraw 3055No effect. 3056In the original Korn shell, unless 3057.Ic viraw 3058was set, the vi command-line mode would let the 3059.Xr tty 4 3060driver do the work until ESC (^[) was entered. 3061.Nm pdksh 3062is always in viraw mode. 3063.El 3064.Pp 3065These options can also be used upon invocation of the shell. 3066The current set of 3067options (with single letter names) can be found in the parameter 3068.Sq $- . 3069.Ic set Fl o 3070with no option name will list all the options and whether each is on or off; 3071.Ic set +o 3072will print the long names of all options that are currently on. 3073.Pp 3074Remaining arguments, if any, are positional parameters and are assigned, in 3075order, to the positional parameters (i.e. $1, $2, etc.). 3076If options end with 3077.Ql -- 3078and there are no remaining arguments, all positional parameters are cleared. 3079If no options or arguments are given, the values of all names are printed. 3080For unknown historical reasons, a lone 3081.Ql - 3082option is treated specially \- it clears both the 3083.Fl x 3084and 3085.Fl v 3086options. 3087.Pp 3088.It Ic shift Op Ar number 3089The positional parameters 3090.Ar number Ns +1 , 3091.Ar number Ns +2 , 3092etc. are renamed to 3093.Sq 1 , 3094.Sq 2 , 3095etc. 3096.Ar number 3097defaults to 1. 3098.Pp 3099.It Ic test Ar expression 3100.It Ic \&[ Ar expression Ic \&] 3101.Ic test 3102evaluates the 3103.Ar expression 3104and returns zero status if true, 1 if false, or greater than 1 if there 3105was an error. 3106It is normally used as the condition command of 3107.Ic if 3108and 3109.Ic while 3110statements. 3111Symbolic links are followed for all 3112.Ar file 3113expressions except 3114.Fl h 3115and 3116.Fl L . 3117.Pp 3118The following basic expressions are available: 3119.Bl -tag -width 17n 3120.It Fl a Ar file 3121.Ar file 3122exists. 3123.It Fl b Ar file 3124.Ar file 3125is a block special device. 3126.It Fl c Ar file 3127.Ar file 3128is a character special device. 3129.It Fl d Ar file 3130.Ar file 3131is a directory. 3132.It Fl e Ar file 3133.Ar file 3134exists. 3135.It Fl f Ar file 3136.Ar file 3137is a regular file. 3138.It Fl G Ar file 3139.Ar file Ns 's 3140group is the shell's effective group ID. 3141.It Fl g Ar file 3142.Ar file Ns 's 3143mode has the setgid bit set. 3144.It Fl h Ar file 3145.Ar file 3146is a symbolic link. 3147.It Fl k Ar file 3148.Ar file Ns 's 3149mode has the 3150.Xr sticky 8 3151bit set. 3152.It Fl L Ar file 3153.Ar file 3154is a symbolic link. 3155.It Fl O Ar file 3156.Ar file Ns 's 3157owner is the shell's effective user ID. 3158.It Fl o Ar option 3159Shell 3160.Ar option 3161is set (see the 3162.Ic set 3163command above for a list of options). 3164As a non-standard extension, if the option starts with a 3165.Ql \&! , 3166the test is negated; the test always fails if 3167.Ar option 3168doesn't exist (so [ -o foo -o -o !foo ] returns true if and only if option 3169.Ar foo 3170exists). 3171.It Fl p Ar file 3172.Ar file 3173is a named pipe. 3174.It Fl r Ar file 3175.Ar file 3176exists and is readable. 3177.It Fl S Ar file 3178.Ar file 3179is a 3180.Xr unix 4 Ns -domain 3181socket. 3182.It Fl s Ar file 3183.Ar file 3184is not empty. 3185.It Fl t Op Ar fd 3186File descriptor 3187.Ar fd 3188is a 3189.Xr tty 4 3190device. 3191If the 3192.Ic posix 3193option is not set, 3194.Ar fd 3195may be left out, in which case it is taken to be 1 (the behaviour differs due 3196to the special POSIX rules described above). 3197.It Fl u Ar file 3198.Ar file Ns 's 3199mode has the setuid bit set. 3200.It Fl w Ar file 3201.Ar file 3202exists and is writable. 3203.It Fl x Ar file 3204.Ar file 3205exists and is executable. 3206.It Ar file1 Fl nt Ar file2 3207.Ar file1 3208is newer than 3209.Ar file2 . 3210.It Ar file1 Fl ot Ar file2 3211.Ar file1 3212is older than 3213.Ar file2 . 3214.It Ar file1 Fl ef Ar file2 3215.Ar file1 3216is the same file as 3217.Ar file2 . 3218.It Ar string 3219.Ar string 3220has non-zero length. 3221.It Fl n Ar string 3222.Ar string 3223is not empty. 3224.It Fl z Ar string 3225.Ar string 3226is empty. 3227.It Ar string No = Ar string 3228Strings are equal. 3229.It Ar string No != Ar string 3230Strings are not equal. 3231.It Ar number Fl eq Ar number 3232Numbers compare equal. 3233.It Ar number Fl ne Ar number 3234Numbers compare not equal. 3235.It Ar number Fl ge Ar number 3236Numbers compare greater than or equal. 3237.It Ar number Fl gt Ar number 3238Numbers compare greater than. 3239.It Ar number Fl le Ar number 3240Numbers compare less than or equal. 3241.It Ar number Fl \< Ar number 3242Numbers compare less than. 3243.El 3244.Pp 3245The above basic expressions, in which unary operators have precedence over 3246binary operators, may be combined with the following operators (listed in 3247increasing order of precedence): 3248.Bd -literal -offset indent 3249expr -o expr Logical OR. 3250expr -a expr Logical AND. 3251! expr Logical NOT. 3252( expr ) Grouping. 3253.Ed 3254.Pp 3255On operating systems not supporting 3256.Pa /dev/fd/ Ns Ar n 3257devices (where 3258.Ar n 3259is a file descriptor number), the 3260.Ic test 3261command will attempt to fake it for all tests that operate on files (except the 3262.Fl e 3263test). 3264For example, 3265[ -w /dev/fd/2 ] tests if file descriptor 2 is writable. 3266.Pp 3267Note that some special rules are applied (courtesy of POSIX) 3268if the number of 3269arguments to 3270.Ic test 3271or 3272.Ic \&[ ... \&] 3273is less than five: if leading 3274.Ql \&! 3275arguments can be stripped such that only one argument remains then a string 3276length test is performed (again, even if the argument is a unary operator); if 3277leading 3278.Ql \&! 3279arguments can be stripped such that three arguments remain and the second 3280argument is a binary operator, then the binary operation is performed (even 3281if the first argument is a unary operator, including an unstripped 3282.Ql \&! ) . 3283.Pp 3284.Sy Note : 3285A common mistake is to use 3286.Dq if \&[ $foo = bar \&] , 3287which fails if parameter 3288.Dq foo 3289is 3290.Dv NULL 3291or unset, if it has embedded spaces (i.e.\& 3292.Ev IFS 3293characters), or if it is a unary operator like 3294.Sq \&! 3295or 3296.Sq Fl n . 3297Use tests like 3298.Dq if \&[ \&"X$foo\&" = Xbar \&] 3299instead. 3300.Pp 3301.It Ic times 3302Print the accumulated user and system times used both by the shell 3303and by processes that the shell started which have exited. 3304The format of the output is: 3305.Bd -literal -offset indent 33060m0.00s 0m0.00s 33070m0.00s 0m0.00s 3308.Ed 3309.Pp 3310.It Ic trap Op Ar handler signal ... 3311Sets a trap handler that is to be executed when any of the specified signals are 3312received. 3313.Ar handler 3314is either a 3315.Dv NULL 3316string, indicating the signals are to be ignored, a minus sign 3317.Pq Sq - , 3318indicating that the default action is to be taken for the signals (see 3319.Xr signal 3 ) , 3320or a string containing shell commands to be evaluated and executed at the first 3321opportunity (i.e. when the current command completes, or before printing the 3322next 3323.Ev PS1 3324prompt) after receipt of one of the signals. 3325.Ar signal 3326is the name of a signal (e.g.\& 3327.Dv PIPE 3328or 3329.Dv ALRM ) 3330or the number of the signal (see the 3331.Ic kill -l 3332command above). 3333.Pp 3334There are two special signals: 3335.Dv EXIT 3336(also known as 0), which is executed when the shell is about to exit, and 3337.Dv ERR , 3338which is executed after an error occurs (an error is something that would cause 3339the shell to exit if the 3340.Fl e 3341or 3342.Ic errexit 3343option were set \- see the 3344.Ic set 3345command above). 3346.Dv EXIT 3347handlers are executed in the environment of the last executed command. 3348Note 3349that for non-interactive shells, the trap handler cannot be changed for signals 3350that were ignored when the shell started. 3351.Pp 3352With no arguments, 3353.Ic trap 3354lists, as a series of 3355.Ic trap 3356commands, the current state of the traps that have been set since the shell 3357started. 3358Note that the output of 3359.Ic trap 3360cannot be usefully piped to another process (an artifact of the fact that 3361traps are cleared when subprocesses are created). 3362.Pp 3363The original Korn shell's 3364.Dv DEBUG 3365trap and the handling of 3366.Dv ERR 3367and 3368.Dv EXIT 3369traps in functions are not yet implemented. 3370.Pp 3371.It Ic true 3372A command that exits with a zero value. 3373.Pp 3374.It Xo 3375.Ic typeset 3376.Oo 3377.Op Ic +-lprtUux 3378.Op Fl L Ns Op Ar n 3379.Op Fl R Ns Op Ar n 3380.Op Fl Z Ns Op Ar n 3381.Op Fl i Ns Op Ar n 3382.No \*(Ba Fl f Op Fl tux 3383.Oc 3384.Oo 3385.Ar name 3386.Op Ns = Ns Ar value 3387.Ar ... 3388.Oc 3389.Xc 3390Display or set parameter attributes. 3391With no 3392.Ar name 3393arguments, parameter attributes are displayed; if no options are used, the 3394current attributes of all parameters are printed as 3395.Ic typeset 3396commands; if an option is given (or 3397.Ql - 3398with no option letter), all parameters and their values with the specified 3399attributes are printed; if options are introduced with 3400.Ql + , 3401parameter values are not printed. 3402.Pp 3403If 3404.Ar name 3405arguments are given, the attributes of the named parameters are set 3406.Pq Ic - 3407or cleared 3408.Pq Ic + . 3409Values for parameters may optionally be specified. 3410If 3411.Ic typeset 3412is used inside a function, any newly created parameters are local to the 3413function. 3414.Pp 3415When 3416.Fl f 3417is used, 3418.Ic typeset 3419operates on the attributes of functions. 3420As with parameters, if no 3421.Ar name 3422arguments are given, 3423functions are listed with their values (i.e. definitions) unless 3424options are introduced with 3425.Ql + , 3426in which case only the function names are reported. 3427.Bl -tag -width Ds 3428.It Fl f 3429Function mode. 3430Display or set functions and their attributes, instead of parameters. 3431.It Fl i Ns Op Ar n 3432Integer attribute. 3433.Ar n 3434specifies the base to use when displaying the integer (if not specified, the 3435base given in the first assignment is used). 3436Parameters with this attribute may 3437be assigned values containing arithmetic expressions. 3438.It Fl L Ns Op Ar n 3439Left justify attribute. 3440.Ar n 3441specifies the field width. 3442If 3443.Ar n 3444is not specified, the current width of a parameter (or the width of its first 3445assigned value) is used. 3446Leading whitespace (and zeros, if used with the 3447.Fl Z 3448option) is stripped. 3449If necessary, values are either truncated or space padded 3450to fit the field width. 3451.It Fl l 3452Lower case attribute. 3453All upper case characters in values are converted to lower case. 3454(In the original Korn shell, this parameter meant 3455.Dq long integer 3456when used with the 3457.Fl i 3458option.) 3459.It Fl p 3460Print complete 3461.Ic typeset 3462commands that can be used to re-create the attributes (but not the values) of 3463parameters. 3464This is the default action (option exists for ksh93 compatibility). 3465.It Fl R Ns Op Ar n 3466Right justify attribute. 3467.Ar n 3468specifies the field width. 3469If 3470.Ar n 3471is not specified, the current width of a parameter (or the width of its first 3472assigned value) is used. 3473Trailing whitespace is stripped. 3474If necessary, values are either stripped of leading characters or space 3475padded to make them fit the field width. 3476.It Fl r 3477Read-only attribute. 3478Parameters with this attribute may not be assigned to or unset. 3479Once this attribute is set, it cannot be turned off. 3480.It Fl t 3481Tag attribute. 3482Has no meaning to the shell; provided for application use. 3483.Pp 3484For functions, 3485.Fl t 3486is the trace attribute. 3487When functions with the trace attribute are executed, the 3488.Ic xtrace 3489.Pq Fl x 3490shell option is temporarily turned on. 3491.It Fl U 3492Unsigned integer attribute. 3493Integers are printed as unsigned values (only 3494useful when combined with the 3495.Fl i 3496option). 3497This option is not in the original Korn shell. 3498.It Fl u 3499Upper case attribute. 3500All lower case characters in values are converted to upper case. 3501(In the original Korn shell, this parameter meant 3502.Dq unsigned integer 3503when used with the 3504.Fl i 3505option, which meant upper case letters would never be used for bases greater 3506than 10. 3507See the 3508.Fl U 3509option.) 3510.Pp 3511For functions, 3512.Fl u 3513is the undefined attribute. 3514See 3515.Sx Functions 3516above for the implications of this. 3517.It Fl x 3518Export attribute. 3519Parameters (or functions) are placed in the environment of 3520any executed commands. 3521Exported functions are not yet implemented. 3522.It Fl Z Ns Op Ar n 3523Zero fill attribute. 3524If not combined with 3525.Fl L , 3526this is the same as 3527.Fl R , 3528except zero padding is used instead of space padding. 3529.El 3530.Pp 3531.It Xo 3532.Ic ulimit 3533.Op Fl acdfHlmnpSst Op Ar value 3534.Ar ... 3535.Xc 3536Display or set process limits. 3537If no options are used, the file size limit 3538.Pq Fl f 3539is assumed. 3540.Ar value , 3541if specified, may be either an arithmetic expression starting with a 3542number or the word 3543.Dq unlimited . 3544The limits affect the shell and any processes created by the shell after a 3545limit is imposed; limits may not be increased once they are set. 3546.Bl -tag -width 5n 3547.It Fl a 3548Display all limits; unless 3549.Fl H 3550is used, soft limits are displayed. 3551.It Fl c Ar n 3552Impose a size limit of 3553.Ar n 3554blocks on the size of core dumps. 3555.It Fl d Ar n 3556Impose a size limit of 3557.Ar n 3558kilobytes on the size of the data area. 3559.It Fl f Ar n 3560Impose a size limit of 3561.Ar n 3562blocks on files written by the shell and its child processes (files of any 3563size may be read). 3564.It Fl H 3565Set the hard limit only (the default is to set both hard and soft limits). 3566.It Fl l Ar n 3567Impose a limit of 3568.Ar n 3569kilobytes on the amount of locked (wired) physical memory. 3570.It Fl m Ar n 3571Impose a limit of 3572.Ar n 3573kilobytes on the amount of physical memory used. 3574.It Fl n Ar n 3575Impose a limit of 3576.Ar n 3577file descriptors that can be open at once. 3578.It Fl p Ar n 3579Impose a limit of 3580.Ar n 3581processes that can be run by the user at any one time. 3582.It Fl S 3583Set the soft limit only (the default is to set both hard and soft limits). 3584.It Fl s Ar n 3585Impose a size limit of 3586.Ar n 3587kilobytes on the size of the stack area. 3588.It Fl t Ar n 3589Impose a time limit of 3590.Ar n 3591CPU seconds spent in user mode to be used by each process. 3592.\".It Fl v Ar n 3593.\"Impose a limit of 3594.\".Ar n 3595.\"kilobytes on the amount of virtual memory used. 3596.El 3597.Pp 3598As far as 3599.Ic ulimit 3600is concerned, a block is 512 bytes. 3601.Pp 3602.It Xo 3603.Ic umask 3604.Op Fl S 3605.Op Ar mask 3606.Xc 3607Display or set the file permission creation mask, or umask (see 3608.Xr umask 2 ) . 3609If the 3610.Fl S 3611option is used, the mask displayed or set is symbolic; otherwise, it is an 3612octal number. 3613.Pp 3614Symbolic masks are like those used by 3615.Xr chmod 1 . 3616When used, they describe what permissions may be made available (as opposed to 3617octal masks in which a set bit means the corresponding bit is to be cleared). 3618For example, 3619.Dq ug=rwx,o= 3620sets the mask so files will not be readable, writable, or executable by 3621.Dq others , 3622and is equivalent (on most systems) to the octal mask 3623.Dq 007 . 3624.Pp 3625.It Xo 3626.Ic unalias 3627.Op Fl adt 3628.Op Ar name ... 3629.Xc 3630The aliases for the given names are removed. 3631If the 3632.Fl a 3633option is used, all aliases are removed. 3634If the 3635.Fl t 3636or 3637.Fl d 3638options are used, the indicated operations are carried out on tracked or 3639directory aliases, respectively. 3640.Pp 3641.It Xo 3642.Ic unset 3643.Op Fl fv 3644.Ar parameter ... 3645.Xc 3646Unset the named parameters 3647.Po 3648.Fl v , 3649the default 3650.Pc 3651or functions 3652.Pq Fl f . 3653The exit status is non-zero if any of the parameters have the read-only 3654attribute set, zero otherwise. 3655.Pp 3656.It Ic wait Op Ar job ... 3657Wait for the specified job(s) to finish. 3658The exit status of 3659.Ic wait 3660is that of the last specified job; if the last job is killed by a signal, the 3661exit status is 128 + the number of the signal (see 3662.Ic kill -l Ar exit-status 3663above); if the last specified job can't be found (because it never existed, or 3664had already finished), the exit status of 3665.Ic wait 3666is 127. 3667See 3668.Sx Job control 3669below for the format of 3670.Ar job . 3671.Ic wait 3672will return if a signal for which a trap has been set is received, or if a 3673.Dv SIGHUP , 3674.Dv SIGINT , 3675or 3676.Dv SIGQUIT 3677signal is received. 3678.Pp 3679If no jobs are specified, 3680.Ic wait 3681waits for all currently running jobs (if any) to finish and exits with a zero 3682status. 3683If job monitoring is enabled, the completion status of jobs is printed 3684(this is not the case when jobs are explicitly specified). 3685.Pp 3686.It Xo 3687.Ic whence 3688.Op Fl pv 3689.Op Ar name ... 3690.Xc 3691For each 3692.Ar name , 3693the type of command is listed (reserved word, built-in, alias, 3694function, tracked alias, or executable). 3695If the 3696.Fl p 3697option is used, a path search is performed even if 3698.Ar name 3699is a reserved word, alias, etc. 3700Without the 3701.Fl v 3702option, 3703.Ic whence 3704is similar to 3705.Ic command Fl v 3706except that 3707.Ic whence 3708will find reserved words and won't print aliases as alias commands. 3709With the 3710.Fl v 3711option, 3712.Ic whence 3713is the same as 3714.Ic command Fl V . 3715Note that for 3716.Ic whence , 3717the 3718.Fl p 3719option does not affect the search path used, as it does for 3720.Ic command . 3721If the type of one or more of the names could not be determined, the exit 3722status is non-zero. 3723.El 3724.Ss Job control 3725Job control refers to the shell's ability to monitor and control jobs, which 3726are processes or groups of processes created for commands or pipelines. 3727At a minimum, the shell keeps track of the status of the background (i.e.\& 3728asynchronous) jobs that currently exist; this information can be displayed 3729using the 3730.Ic jobs 3731commands. 3732If job control is fully enabled (using 3733.Ic set -m 3734or 3735.Ic set -o monitor ) , 3736as it is for interactive shells, the processes of a job are placed in their 3737own process group. 3738Foreground jobs can be stopped by typing the suspend 3739character from the terminal (normally ^Z), jobs can be restarted in either the 3740foreground or background using the 3741.Ic fg 3742and 3743.Ic bg 3744commands, and the state of the terminal is saved or restored when a foreground 3745job is stopped or restarted, respectively. 3746.Pp 3747Note that only commands that create processes (e.g. asynchronous commands, 3748subshell commands, and non-built-in, non-function commands) can be stopped; 3749commands like 3750.Ic read 3751cannot be. 3752.Pp 3753When a job is created, it is assigned a job number. 3754For interactive shells, this number is printed inside 3755.Dq [..] , 3756followed by the process IDs of the processes in the job when an asynchronous 3757command is run. 3758A job may be referred to in the 3759.Ic bg , 3760.Ic fg , 3761.Ic jobs , 3762.Ic kill , 3763and 3764.Ic wait 3765commands either by the process ID of the last process in the command pipeline 3766(as stored in the 3767.Ic $!\& 3768parameter) or by prefixing the job number with a percent 3769sign 3770.Pq Sq % . 3771Other percent sequences can also be used to refer to jobs: 3772.Bl -tag -width "%+ | %% | %XX" 3773.It %+ \*(Ba %% \*(Ba % 3774The most recently stopped job, or, if there are no stopped jobs, the oldest 3775running job. 3776.It %- 3777The job that would be the 3778.Ic %+ 3779job if the latter did not exist. 3780.It % Ns Ar n 3781The job with job number 3782.Ar n . 3783.It %? Ns Ar string 3784The job with its command containing the string 3785.Ar string 3786(an error occurs if multiple jobs are matched). 3787.It % Ns Ar string 3788The job with its command starting with the string 3789.Ar string 3790(an error occurs if multiple jobs are matched). 3791.El 3792.Pp 3793When a job changes state (e.g. a background job finishes or foreground job is 3794stopped), the shell prints the following status information: 3795.Pp 3796.D1 [ Ns Ar number ] Ar flag status command 3797.Pp 3798where... 3799.Bl -tag -width "command" 3800.It Ar number 3801is the job number of the job; 3802.It Ar flag 3803is the 3804.Ql + 3805or 3806.Ql - 3807character if the job is the 3808.Ic %+ 3809or 3810.Ic %- 3811job, respectively, or space if it is neither; 3812.It Ar status 3813indicates the current state of the job and can be: 3814.Bl -tag -width "RunningXX" 3815.It Done Op Ar number 3816The job exited. 3817.Ar number 3818is the exit status of the job, which is omitted if the status is zero. 3819.It Running 3820The job has neither stopped nor exited (note that running does not necessarily 3821mean consuming CPU time \- 3822the process could be blocked waiting for some event). 3823.It Stopped Op Ar signal 3824The job was stopped by the indicated 3825.Ar signal 3826(if no signal is given, the job was stopped by 3827.Dv SIGTSTP ) . 3828.It Ar signal-description Op Dq core dumped 3829The job was killed by a signal (e.g. memory fault, hangup); use 3830.Ic kill -l 3831for a list of signal descriptions. 3832The 3833.Dq core dumped 3834message indicates the process created a core file. 3835.El 3836.It Ar command 3837is the command that created the process. 3838If there are multiple processes in 3839the job, each process will have a line showing its 3840.Ar command 3841and possibly its 3842.Ar status , 3843if it is different from the status of the previous process. 3844.El 3845.Pp 3846When an attempt is made to exit the shell while there are jobs in the stopped 3847state, the shell warns the user that there are stopped jobs and does not exit. 3848If another attempt is immediately made to exit the shell, the stopped jobs are 3849sent a 3850.Dv SIGHUP 3851signal and the shell exits. 3852Similarly, if the 3853.Ic nohup 3854option is not set and there are running jobs when an attempt is made to exit 3855a login shell, the shell warns the user and does not exit. 3856If another attempt 3857is immediately made to exit the shell, the running jobs are sent a 3858.Dv SIGHUP 3859signal and the shell exits. 3860.Sh FILES 3861.Bl -tag -width "/etc/suid_profileXX" -compact 3862.It Pa ~/.profile 3863User's login profile. 3864.It Pa /etc/profile 3865System login profile. 3866.It Pa /etc/suid_profile 3867Privileged shell profile. 3868.It Pa /etc/shells 3869Shell database. 3870.El 3871.Sh SEE ALSO 3872.Xr csh 1 , 3873.Xr ed 1 , 3874.Xr ksh 1 , 3875.Xr mg 1 , 3876.Xr stty 1 , 3877.Xr vi 1 , 3878.Xr shells 5 , 3879.Xr environ 7 , 3880.Xr script 7 3881.Rs 3882.%A Morris Bolsky 3883.%A David Korn 3884.%T "The KornShell Command and Programming Language" 3885.%D 1983 3886.%O "ISBN 0-13-516972-0" 3887.Re 3888.Rs 3889.%A Stephen G. Kochan 3890.%A Patrick H. Wood 3891.%T "UNIX Shell Programming" 3892.%O "Hayden" 3893.Re 3894.Rs 3895.%A "IEEE Inc." 3896.%T "IEEE Standard for Information Technology \- Portable Operating " \ 3897 "System Interface (POSIX) \- Part 2: Shell and Utilities" 3898.%D 1993 3899.%O "ISBN 1-55937-266-9" 3900.Re 3901.Sh NOTES 3902.Nm 3903is implemented as a run-time option of 3904.Nm pdksh , 3905with only those 3906.Nm 3907features whose syntax or semantics are incompatible with a traditional Bourne 3908shell disabled. 3909Since this leaves some 3910.Nm 3911extensions exposed, caution should be used where backwards compatibility with 3912traditional Bourne or POSIX compliant shells is an issue. 3913.Sh AUTHORS 3914This shell is based on the public domain 7th edition Bourne shell clone by 3915Charles Forsyth and parts of the BRL shell by Doug A. Gwyn, Doug Kingston, 3916Ron Natalie, Arnold Robbins, Lou Salkind, and others. 3917The first release of 3918.Nm pdksh 3919was created by Eric Gisin, and it was subsequently maintained by John R.\& 3920MacMillan (change!john@sq.sq.com), Simon J. Gerraty (sjg@zen.void.oz.au), 3921and Michael Rendell (michael@cs.mun.ca). 3922The 3923.Pa CONTRIBUTORS 3924file in the source distribution contains a more complete list of people and 3925their part in the shell's development. 3926.\" .Sh BUGS 3927.\" Any bugs in 3928.\" .Nm pdksh 3929.\" should be reported to pdksh@cs.mun.ca. 3930.\" Please include the version of 3931.\" .Nm pdksh 3932.\" .Po 3933.\" .Ic echo $KSH_VERSION 3934.\" shows it 3935.\" .Pc , 3936.\" the machine, operating system, and compiler you are using and a description of 3937.\" how to repeat the bug (a small shell script that demonstrates the bug is best). 3938.\" The following, if relevant (if you are not sure, include them), can also be 3939.\" helpful: options you are using (both 3940.\" .Pa options.h 3941.\" and 3942.\" .Ic set Fl o Ic options ) 3943.\" and a copy of your 3944.\" .Pa config.h 3945.\" (the file generated by the 3946.\" .Pa configure 3947.\" script). 3948.\" New versions of 3949.\" .Nm pdksh 3950.\" can be obtained from ftp://ftp.cs.mun.ca/pub/pdksh. 3951.\" .Pp 3952.\" BTW, the most frequently reported bug is: 3953.\" .Bd -literal -offset indent 3954.\" $ echo hi | read a; echo $a # Does not print hi 3955.\" .Ed 3956.\" .Pp 3957.\" I'm aware of this and there is no need to report it. 3958