diff options
Diffstat (limited to 'src/mksh.1')
| -rw-r--r-- | src/mksh.1 | 1833 |
1 files changed, 979 insertions, 854 deletions
@@ -1,9 +1,9 @@ -.\" $MirOS: src/bin/mksh/mksh.1,v 1.463 2019/03/01 16:17:31 tg Exp $ +.\" $MirOS: src/bin/mksh/mksh.1,v 1.489 2020/04/14 22:45:21 tg Exp $ .\" $OpenBSD: ksh.1,v 1.160 2015/07/04 13:27:04 feinerer Exp $ .\"- .\" Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, .\" 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, -.\" 2018, 2019 +.\" 2018, 2019, 2020 .\" mirabilos <m@mirbsd.org> .\" .\" Provided that these terms and disclaimer and all copyright notices @@ -28,7 +28,8 @@ .\" thus use - for hyphens and \- for minus signs and option dashes .\" * ~ is size-reduced and placed atop in groff, so use \*(TI .\" * ^ is size-reduced and placed atop in groff, so use \*(ha -.\" * \(en does not work in nroff, so use \*(en +.\" * \(en does not work in nroff, so use \*(en for a solo en dash +.\" * and \*(EM for a correctly spaced em dash .\" * <>| are problematic, so redefine and use \*(Lt\*(Gt\*(Ba .\" Also make sure to use \& *before* a punctuation char that is to not .\" be interpreted as punctuation, and especially with two-letter words @@ -62,6 +63,12 @@ . ds ha ^ . ds en \(em .\} +.ie n \{\ +. ds EM \ \*(en\ \& +.\} +.el \{\ +. ds EM \f(TR\^\(em\^\fP +.\} .\" .\" Implement .Dd with the Mdocdate RCS keyword .\" @@ -77,7 +84,7 @@ .\" with -mandoc, it might implement .Mx itself, but we want to .\" use our own definition. And .Dd must come *first*, always. .\" -.Dd $Mdocdate: March 1 2019 $ +.Dd $Mdocdate: April 14 2020 $ .\" .\" Check which macro package we use, and do other -mdoc setup. .\" @@ -221,7 +228,8 @@ into account all information is first and foremost presented with .Nm in mind and should be taken as such. .Ss I use Android, OS/2, etc. so what...? -Please see the FAQ at the end of this document. +Please refer to: +.Pa http://www.mirbsd.org/mksh\-faq.htm#sowhatismksh .Ss Invocation Most builtins can be called directly, for example if a link points from its name to the shell; not all make sense, have been tested or work at all though. @@ -279,7 +287,7 @@ effective user ID or group ID (see and .Xr getgid 2 ) . Clearing the privileged option causes the shell to set -its effective user ID (group ID) to its real user ID (group ID). +its effective user ID (group ID) to its initial real user ID (group ID). For further implications, see .Sx Startup files . If the shell is privileged and this flag is not explicitly set, the @@ -289,8 +297,9 @@ option is cleared automatically after processing the startup files. Restricted shell. A shell is .Dq restricted -if this -option is used. +if the basename the shell is called with (i.e. argv[0]) starts with +.Ql r +or if this option is used. The following restrictions come into effect after the shell processes any profile and .Ev ENV @@ -481,8 +490,8 @@ The first three of these are the above mentioned quoting characters (see .Sx Quoting below); .Ql # , -if used at the beginning of a word, introduces a comment \*(en everything after -the +if used at the beginning of a word, +introduces a comment\*(EMeverything after the .Ql # up to the nearest newline is ignored; .Ql $ @@ -594,8 +603,7 @@ only if the exit status of .Ar cmd1 is zero; .Dq Li \*(Ba\*(Ba -is the opposite \*(en -.Ar cmd2 +.No is the opposite\*(EM Ns Ar cmd2 is executed only if the exit status of .Ar cmd1 is non-zero. @@ -681,29 +689,14 @@ This is not valid: .Pp .Dl $ { echo foo; echo bar } .Bl -tag -width 4n -.It Pq Ar list -Execute -.Ar list -in a subshell. -There is no implicit way to pass environment changes from a -subshell back to its parent. -.It { Ar list ; No } -Compound construct; -.Ar list -is executed, but not in a subshell. -Note that -.Dq Li { -and -.Dq Li } -are reserved words, not meta-characters. -.It Xo case Ar word No in +.It Xo Ic case Ar word Ic in .Oo Op \&( .Ar pattern .Op \*(Ba Ar pattern .No ... Ns ) .Ar list -.Ic terminator -.Oc No ... esac +.Aq terminator +.Oc No ... Ic esac .Xc The .Ic case @@ -731,12 +724,12 @@ well as tilde substitution. For historical reasons, open and close braces may be used instead of .Ic in and -.Ic esac -e.g.\& -.Ic case $foo { *) echo bar ;; } . +.Ic esac , +for example: +.Dq Li case $foo { (ba[rz]\*(Bablah) date ;; } .Pp The list -.Ic terminator Ns s +.Ao terminator Ac Ns s are: .Bl -tag -width 4n .It Dq Li ;; @@ -754,9 +747,9 @@ statement is that of the executed if no .Ar list is executed, the exit status is zero. -.It Xo for Ar name -.Oo in Ar word No ... Oc ; -.No do Ar list ; No done +.It Xo Ic for Ar name +.Oo Ic in Ar word ... Oc Ic ; +.Ic do Ar list ; Ic done .Xc For each .Ar word @@ -765,16 +758,6 @@ in the specified word list, the parameter is set to the word and .Ar list is executed. -If -.Ic in -is not used to specify a word list, the positional parameters ($1, $2, -etc.) are used instead. -For historical reasons, open and close braces may be used instead of -.Ic do -and -.Ic done -e.g.\& -.Ic for i; { echo $i; } . The exit status of a .Ic for statement is the last exit status of @@ -782,13 +765,52 @@ statement is the last exit status of if .Ar list is never executed, the exit status is zero. -.It Xo if Ar list ; -.No then Ar list ; -.Oo elif Ar list ; -.No then Ar list ; Oc +If +.Ic in +is not used to specify a word list, the positional parameters ($1, $2, +etc.) are used instead; in this case, use a newline instead of the semicolon +.Pq Sq Ic ;\& +for portability. +For historical reasons, open and close braces may be used instead of +.Ic do +and +.Ic done , +as in +.Dq Li for i; { echo $i; } +.Pq not portable . +.It Xo Ic function Ar name +.No { Ar list ; No } +.Xc +Defines the function +.Ar name +(see +.Sx Functions +below). +All redirections specified after a function definition are performed whenever +the function is executed, not when the function definition is executed. +.It Ar name Ns \&() Ar command +Mostly the same as +.Ic function +(see above and +.Sx Functions +below). +Most amounts of space and tab after +.Ar name +will be ignored. +.It Xo Ic function Ar name Ns \&() +.No { Ar list ; No } +.Xc +.Nm bash Ns ism for +.Ar name Ns Li ()\ { +.Ar list Ns Li ;\ } +.Pq the Ic function No keyword is ignored . +.It Xo Ic if Ar list ; +.Ic then Ar list ; +.Oo Ic elif Ar list ; +.Ic then Ar list ; Oc .No ... -.Oo else Ar list ; Oc -.No fi +.Oo Ic else Ar list ; Oc +.Ic fi .Xc If the exit status of the first .Ar list @@ -810,21 +832,22 @@ following the is executed. The exit status of an .Ic if -statement is that of non-conditional +statement is that of whatever non-conditional +.Pq not the first .Ar list that is executed; if no non-conditional .Ar list is executed, the exit status is zero. -.It Xo select Ar name -.Oo in Ar word No ... Oc ; -.No do Ar list ; No done +.It Xo Ic select Ar name +.Oo Ic in Ar word No ... Oc ; +.Ic do Ar list ; Ic done .Xc The .Ic select statement provides an automatic method of presenting the user with a menu and selecting from it. An enumerated list of the specified -.Ar word Ns (s) +.Ar word Ns s is printed on standard error, followed by a prompt .Po .Ev PS3 : @@ -836,7 +859,7 @@ standard input, .Ar name is set to the selected word (or unset if the selection is not valid), .Ev REPLY -is set to what was read (leading/trailing space is stripped), and +is set to what was read (leading and trailing space is stripped), and .Ar list is executed. If a blank line (i.e. zero or more @@ -853,38 +876,47 @@ This process continues until an end-of-file is read, an interrupt is received, or a .Ic break statement is executed inside the loop. -If -.Dq in Ar word ... -is omitted, the positional parameters are used -(i.e. $1, $2, etc.). -For historical reasons, open and close braces may be used instead of -.Ic do -and -.Ic done -e.g.\& -.Ic select i; { echo $i; } . The exit status of a .Ic select statement is zero if a .Ic break statement is used to exit the loop, non-zero otherwise. -.It Xo until Ar list ; -.No do Ar list ; -.No done +If +.Dq Ic in Ar word ... +is omitted, the positional parameters are used. +For historical reasons, open and close braces may be used instead of +.Ic do +and +.Ic done , +as in: +.Dq Li select i; { echo $i; } +.It Xo Ic time Op Fl p +.Op Ar pipeline +.Xc +The +.Sx Command execution +section describes the +.Ic time +reserved word. +.It Xo Ic until Ar list ; +.Ic do Ar list ; Ic done .Xc This works like -.Ic while , -except that the body is executed only while the exit status of the first +.Ic while Pq see below , +except that the body +.Ar list +is executed only while the exit status of the first .Ar list is non-zero. -.It Xo while Ar list ; -.No do Ar list ; -.No done +.It Xo Ic while Ar list ; +.Ic do Ar list ; Ic done .Xc A .Ic while is a pre-checked loop. -Its body is executed as often as the exit status of the first +Its body +.Ar list +is executed as often as the exit status of the first .Ar list is zero. The exit status of a @@ -892,53 +924,6 @@ The exit status of a statement is the last exit status of the .Ar list in the body of the loop; if the body is not executed, the exit status is zero. -.It Xo function Ar name -.No { Ar list ; No } -.Xc -Defines the function -.Ar name -(see -.Sx Functions -below). -Note that redirections specified after a function definition are -performed whenever the function is executed, not when the function definition -is executed. -.It Ar name Ns \&() Ar command -Mostly the same as -.Ic function -(see -.Sx Functions -below). -Whitespace (space or tab) after -.Ar name -will be ignored most of the time. -.It Xo function Ar name Ns \&() -.No { Ar list ; No } -.Xc -The same as -.Ar name Ns \&() -.Pq Nm bash Ns ism . -The -.Ic function -keyword is ignored. -.It Xo Ic time Op Fl p -.Op Ar pipeline -.Xc -The -.Sx Command execution -section describes the -.Ic time -reserved word. -.It \&(( Ar expression No )) -The arithmetic expression -.Ar expression -is evaluated; equivalent to -.Dq Li let \&" Ns Ar expression Ns \&" -(see -.Sx Arithmetic expressions -and the -.Ic let -command, below) in a compound construct. .It Bq Bq Ar \ \&expression\ \& Similar to the .Ic test @@ -947,7 +932,7 @@ and commands (described later), with the following exceptions: .Bl -bullet .It -Field splitting and file name generation are not performed on arguments. +Field splitting and globbing are not performed on arguments. .It The .Fl a @@ -955,23 +940,22 @@ The and .Fl o .Pq OR -operators are replaced with -.Dq Li && +operators are replaced, respectively, with +.Dq Ic && and -.Dq Li \*(Ba\*(Ba , -respectively. +.Dq Ic \*(Ba\*(Ba . .It Operators (e.g.\& -.Dq Li \-f , -.Dq Li = , -.Dq Li \&! ) +.Dq Ic \-f , +.Dq Ic = , +.Dq Ic \&! ) must be unquoted. .It Parameter, command and arithmetic substitutions are performed as expressions are evaluated and lazy expression evaluation is used for the -.Dq Li && +.Dq Ic && and -.Dq Li \*(Ba\*(Ba +.Dq Ic \*(Ba\*(Ba operators. This means that in the following statement, .Ic $(\*(Ltfoo) @@ -983,23 +967,47 @@ $ [[ \-r foo && $(\*(Ltfoo) = b*r ]] .Ed .It The second operand of the -.Dq Li != +.Dq Ic = and -.Dq Li = -expressions are a subset of patterns (e.g. the comparison +.Dq Ic != +expressions is a pattern (e.g. the comparison .Ic \&[[ foobar = f*r ]] succeeds). -This even works indirectly: +This even works indirectly, while quoting forces literal interpretation: .Bd -literal -offset indent -$ bar=foobar; baz=\*(aqf*r\*(aq -$ [[ $bar = $baz ]]; echo $? -$ [[ $bar = \&"$baz" ]]; echo $? +$ bar=foobar; baz=\*(aqf*r\*(aq # or: baz=\*(aqf+(o)b?r\*(aq +$ [[ $bar = $baz ]]; echo $? # 0 +$ [[ $bar = \&"$baz" ]]; echo $? # 1 .Ed -.Pp -Perhaps surprisingly, the first comparison succeeds, -whereas the second doesn't. -This does not apply to all extglob metacharacters, currently. .El +.It { Ar list ; No } +Compound construct; +.Ar list +is executed, but not in a subshell. +.br +Note that +.Dq Li { +and +.Dq Li } +are reserved words, not meta-characters. +.It Pq Ar list +Execute +.Ar list +in a subshell, forking. +There is no implicit way to pass environment changes from a +subshell back to its parent. +.It \&(( Ar expression No )) +The arithmetic expression +.Ar expression +is evaluated; equivalent to +.Sq Li let \&" Ns Ar expression Ns \&" +in a compound construct. +.br +See the +.Ic let +command and +.Sx Arithmetic expressions +below. .El .Ss Quoting Quoting is used to prevent the shell from treating characters or words @@ -1078,9 +1086,11 @@ For .Dq Li \eU######## and .Dq Li \eu#### , -.Dq # -means a hexadecimal digit, of which there may be none up to four or eight; -these escapes translate a Universal Coded Character Set codepoint to UTF-8. +.Sq Li # +means a hexadecimal digit (up to 4 or 8); these translate a +Universal Coded Character Set codepoint to UTF-8 (see +.Sx CAVEATS +on UCS limitations). Furthermore, .Dq Li \eE and @@ -1090,44 +1100,48 @@ expand to the escape character. In the .Ic print builtin mode, -.Dq Li \e" , -.Dq Li \e\*(aq -and -.Dq Li \e? -are explicitly excluded; -octal sequences must have the none up to three octal digits -.Dq # +octal sequences must have the optional up to three octal digits +.Sq Li # prefixed with the digit zero .Pq Dq Li \e0### ; hexadecimal sequences .Dq Li \ex## -are limited to none up to two hexadecimal digits -.Dq # ; +are limited to up to two hexadecimal digits +.Sq Li # ; both octal and hexadecimal sequences convert to raw octets; -.Dq Li \e# , -where # is none of the above, translates to \e# (backslashes are retained). +.Dq Li \e% , +where +.Sq Li % +is none of the above, translates to +.Li \e% +.Pq backslashes are retained . .Pp -Backslash expansion in the C style mode slightly differs: octal sequences +In C style mode, raw octet-yielding octal sequences .Dq Li \e### -must have no digit zero prefixing the one up to three octal digits -.Dq # -and yield raw octets; hexadecimal sequences -.Dq Li \ex#* +must not have the one up to three octal digits prefixed with the +digit zero; hexadecimal sequences +.Dq Li \ex## greedily eat up as many hexadecimal digits -.Dq # -as they can and terminate with the first non-hexadecimal digit; -these translate a Universal Coded Character Set codepoint to UTF-8. +.Sq Li # +as they can and terminate with the first non-xdigit; below +.Li \ex100 +these produce raw octets; above, they are equivalent to +.Dq Li \eU# . The sequence -.Dq Li \ec# , +.Dq Li \ec% , where -.Dq # -is any octet, translates to Ctrl-# (which basically means, +.Sq Li % +is any octet, translates to +.Ic Ctrl- Ns Li % , +that is, .Dq Li \ec? -becomes DEL, everything else is bitwise ANDed with 0x1F). -Finally, -.Dq Li \e# , -where # is none of the above, translates to # (has the backslash trimmed), -even if it is a newline. +becomes DEL, everything else is bitwise ANDed with 0x9F. +.Dq Li \e% , +where +.Sq Li % +is none of the above, translates to +.Li % : +backslashes are trimmed even before newlines. .Ss Aliases There are two types of aliases: normal command aliases and tracked aliases. Command aliases are normally used as a short hand for a long or often used @@ -1438,10 +1452,10 @@ Note that both the parameter name and the must be unquoted for the shell to recognise a parameter assignment. The construct .Ic FOO+=baz -is also recognised; the old and new values are immediately concatenated. +is also recognised; +the old and new values are string-concatenated with no separator. The fourth way of setting a parameter is with the .Ic export , -.Ic global , .Ic readonly and .Ic typeset @@ -1623,8 +1637,6 @@ A single .Ql # results in the shortest match, and two of them result in the longest match. -Cannot be applied to a vector -.Pq ${*} or ${@} or ${array[*]} or ${array[@]} . .Pp .Sm off .It Xo @@ -1636,8 +1648,7 @@ Cannot be applied to a vector .Pf %% Ar pattern No } .Xc .Sm on -Like ${...#...} substitution, but it deletes from the end of the value. -Cannot be applied to a vector. +Like ${...#...} but deletes from the end of the value. .Pp .Sm off .It Xo @@ -1680,8 +1691,7 @@ cause no replacement; a single leading slash or use of a that matches the empty string causes the replacement to happen only once; two leading slashes cause all occurrences of matches in the value to be replaced. -Cannot be applied to a vector. -Inefficiently implemented, may be slow. +May be slow on long strings. .Pp .Sm off .It Xo @@ -1701,6 +1711,8 @@ except that both and .Ar string are expanded anew for each iteration. +Use with +.Ev KSH_MATCH . .Pp .Sm off .It Xo @@ -1733,10 +1745,6 @@ Both and .Ar len are evaluated as arithmetic expressions. -Currently, -.Ar pos -must start with a space, opening parenthesis or digit to be recognised. -Cannot be applied to a vector. .Pp .It Pf ${ Ns Ar name Ns @#} The hash (using the BAFH algorithm) of the expansion of @@ -1924,9 +1932,7 @@ This is different from .It Ev HISTSIZE The number of commands normally stored for history. The default is 2047. -Do not set this value to insanely high values such as 1000000000 because -.Nm -can then not allocate enough memory for the history and will not start. +The maximum is 65535. .It Ev HOME The default directory for the .Ic cd @@ -1948,16 +1954,16 @@ above for details. This parameter is not imported from the environment when the shell is started. .It Ev KSHEGID -The effective group id of the shell. +The effective group id of the shell at startup. .It Ev KSHGID -The real group id of the shell. +The real group id of the shell at startup. .It Ev KSHUID -The real user id of the shell. +The real user id of the shell at startup. .It Ev KSH_MATCH The last matched string. In a future version, this will be an indexed array, with indexes 1 and up capturing matching groups. -Set by string comparisons (== and !=) in double-bracket test +Set by string comparisons (= and !=) in double-bracket test expressions when a match is found (when != returns false), by .Ic case when a match is encountered, and by the substitution operations @@ -2203,7 +2209,7 @@ set or does not contain the absolute path of a writable directory, temporary files are created in .Pa /tmp . .It Ev USER_ID -The effective user id of the shell. +The effective user id of the shell at startup. .El .Ss Tilde expansion Tilde expansion, which is done in parallel with parameter substitution, @@ -2699,16 +2705,16 @@ instead of is also supported. Note that NUL bytes (integral value of zero) cannot be used. An unset or empty parameter evaluates to 0 in integer context. -In UTF-8 mode, raw octets are mapped into the range EF80..EFFF as in -OPTU-8, which is in the PUA and has been assigned by CSUR for this use. -If more than one octet in ASCII mode, or a sequence of more than one -octet not forming a valid and minimal CESU-8 sequence is passed, the -behaviour is undefined (usually, the shell aborts with a parse error, -but rarely, it succeeds, e.g. on the sequence C2 20). -That's why you should always use ASCII mode unless you know that the -input is well-formed UTF-8 in the range of 0000..FFFD if you use this -feature, as opposed to -.Ic read Fl a . +If +.Sq Li x +isn't comprised of exactly one valid character, the behaviour is undefined +(usually, the shell aborts with a parse error, but rarely, it succeeds, +e.g. on the sequence C2 20); users of this feature (as opposed to +.Ic read Fl a ) +must validate the input first. +See +.Sx CAVEATS +for UTF-8 mode handling. .Pp The operators are evaluated as follows: .Bl -tag -width Ds -offset indent @@ -2965,7 +2971,7 @@ Note that when called in a subshell, will only exit that subshell and will not cause the original shell to exit a running function (see the .Ic while Ns Li \&... Ns Ic read -loop FAQ below). +loop FAQ). .Pp Functions defined with the .Ic function @@ -2978,9 +2984,6 @@ notation: The $0 parameter is set to the name of the function (Bourne-style functions leave $0 untouched). .It -Parameter assignments preceding function calls are not kept in the shell -environment (executing Bourne-style functions will keep assignments). -.It .Ev OPTIND is saved/reset and restored on entry and exit from the function so .Ic getopts @@ -3026,11 +3029,6 @@ Regular built-in commands are different only in that the .Ev PATH parameter is not used to find them. .Pp -The original -.Nm ksh -and POSIX differ somewhat in which commands are considered -special or regular. -.Pp POSIX special built-in utilities: .Pp .Ic \&. , \&: , break , continue , @@ -3042,11 +3040,11 @@ Additional .Nm commands keeping assignments: .Pp -.Ic global , source , typeset +.Ic source , typeset .Pp -Builtins that are not special: +All other builtins are not special; these are at least: .Pp -.Ic [ , alias , bg , bind , +.Ic [\& , alias , bg , bind , .Ic builtin , cat , cd , command , .Ic echo , false , fc , fg , .Ic getopts , jobs , kill , let , @@ -3059,10 +3057,11 @@ Once the type of command has been determined, any command-line parameter assignments are performed and exported for the duration of the command. .Pp The following describes the special and regular built-in commands and -builtin-like reserved words: +builtin-like reserved words, as well as some optional utilities: .Pp .Bl -tag -width false -compact .It Ic \&. Ar file Op Ar arg ... +.Pq keeps assignments , special This is called the .Dq dot command. @@ -3079,22 +3078,62 @@ If no arguments are given, the positional parameters are those of the environment the command is used in. .Pp .It Ic \&: Op Ar ... +.Pq keeps assignments , special The null command. +.br Exit status is set to zero. .Pp +.It Ic Lb64decode Op Ar string +.Pq Li dot.mkshrc No function +Decode +.Ar string +or standard input to binary. +.Pp +.It Ic Lb64encode Op Ar string +.Pq Li dot.mkshrc No function +Encode +.Ar string +or standard input as base64. +.Pp +.It Ic Lbafh_init +.It Ic Lbafh_add Op Ar string +.It Ic Lbafh_finish +.Pq Li dot.mkshrc No functions +Implement the Better Avalance for the Jenkins Hash. +This is the same hash +.Nm +currently uses internally. +.No "After calling" Ic Lbafh_init , No call Ic Lbafh_add +multiple times until all input is read, then call +.Ic Lbafh_finish , +which writes the result to the unsigned integer +.Va Lbafh_v +variable for your consumption. +.Pp +.It Ic Lstripcom Op Ar +.Pq Li dot.mkshrc No function +Same as +.Ic cat +but strips any empty lines and comments (from any +.Sq # +character onwards, no escapes) +and reduces any amount of whitespace to one space character. +.Pp .It Ic \&[ Ar expression Ic \&] +.Pq regular See .Ic test . .Pp .It Xo Ic alias .Oo Fl d \*(Ba t Oo Fl r Oc \*(Ba -.Cm +\-x Oc +.Fl +x Oc .Op Fl p .Op Cm + .Oo Ar name .Op Ns = Ns Ar value .Ar ... Oc .Xc +.Pq regular Without arguments, .Ic alias lists all aliases. @@ -3102,8 +3141,8 @@ For any name without a value, the existing alias is listed. Any name with a value defines an alias; see .Sx Aliases above. -.Li \&[][A\-Za\-z0\-9_!%,.@:\-] -are valid in names, except they may not begin with a hyphen-minus, and +.Li \&[][A\-Za\-z0\-9_!%+,.@:\-] +are valid in names, except they may not begin with a plus or hyphen-minus, and .Ic \&[[ is not a valid alias name. .Pp @@ -3112,7 +3151,7 @@ Normally, aliases are listed as .Ar name Ns = Ns Ar value , where .Ar value -is quoted. +is quoted as necessary. If options were preceded with .Ql + , or a lone @@ -3128,15 +3167,17 @@ listed or set (see .Sx Tilde expansion above). .Pp -If the -.Fl p -option is used, each alias is prefixed with the string -.Dq Li alias\ \& . +With +.Fl p , +each alias is listed with the string +.Dq Li alias\ \& +prefixed. .Pp The .Fl t -option indicates that tracked aliases are to be listed/set (values specified on -the command line are ignored for tracked aliases). +option indicates that tracked aliases are to be listed/set (values given +with the command are ignored for tracked aliases). +.Pp The .Fl r option indicates that all tracked aliases are to be reset. @@ -3148,7 +3189,14 @@ option sets the export attribute of an alias, or, if no names are given, lists the aliases with the export attribute (exporting an alias has no effect). .Pp +.It Ic autoload +.Pq built-in alias +See +.Sx Functions +above. +.Pp .It Ic bg Op Ar job ... +.Pq regular , needs job control Resume the specified stopped job(s) in the background. If no jobs are specified, .Ic %+ @@ -3157,70 +3205,62 @@ See .Sx Job control below for more information. .Pp -.It Ic bind Op Fl l -The current bindings are listed. -If the -.Fl l -flag is given, -.Ic bind -instead lists the names of the functions to which keys may be bound. +.It Ic bind Fl l +.Pq regular +The names of editing commands strings can be bound to are listed. See .Sx Emacs editing mode for more information. .Pp -.It Xo Ic bind Op Fl m -.Ar string Ns = Ns Op Ar substitute -.Ar ... -.Xc +.It Ic bind Op Ar string ... +The current bindings, for +.Ar string , +if given, else all, are listed. +.Em Note: +Default prefix bindings +.Pq 1=Esc , 2=\*(haX , 3=NUL +assumed. +.Pp .It Xo Ic bind .Ar string Ns = Ns Op Ar editing-command -.Ar ... +.Op Ar ... .Xc -The specified editing command is bound to the given +.It Xo Ic bind Fl m +.Ar string Ns = Ns Ar substitute +.Op Ar ... +.Xc +To .Ar string , which should consist of a control character -optionally preceded by one of the two prefix characters -and optionally succeeded by a tilde character. -Future input of the +optionally preceded by one of the three prefix characters +and optionally succeeded by a tilde character, the +.Ar editing-command +is bound so that future input of the .Ar string -will cause the editing command to be immediately invoked. -If the +will immediately invoke that editing command. +If a tilde postfix is given, a tilde trailing the control character is ignored. +If .Fl m -flag is given, the specified input +.Pq macro +is given, future input of the .Ar string -will afterwards be immediately replaced by the given +will be replaced by the given NUL-terminated .Ar substitute -string which may contain editing commands but not other macros. -If a tilde postfix is given, a tilde trailing the one or -two prefices and the control character is ignored, any -other trailing character will be processed afterwards. -.Pp -Control characters may be written using caret notation -i.e. \*(haX represents Ctrl-X. -The caret itself can be escaped by a backslash, which also escapes itself. -Note that although only three prefix characters (usually ESC, \*(haX and NUL) +string, wherein prefix/control/tilde characters mapped to editing commands +.Pq but not those mapped to other macros +will be processed. +.Pp +Prefix and control characters may be written using caret notation, i.e.\& +.No \*(ha Ns Li Z +represents +.No Ctrl- Ns Li Z . +Use a backslash to escape the caret, an equals sign or another backslash. +Note that, although only three prefix characters +.Pq usually Esc, \*(haX and NUL are supported, some multi-character sequences can be supported. .Pp -The following default bindings show how the arrow keys, the home, end and -delete key on a BSD wsvt25, xterm\-xfree86 or GNU screen terminal are bound -(of course some escape sequences won't work out quite this nicely): -.Bd -literal -offset indent -bind \*(aq\*(haX\*(aq=prefix\-2 -bind \*(aq\*(ha[[\*(aq=prefix\-2 -bind \*(aq\*(haXA\*(aq=up\-history -bind \*(aq\*(haXB\*(aq=down\-history -bind \*(aq\*(haXC\*(aq=forward\-char -bind \*(aq\*(haXD\*(aq=backward\-char -bind \*(aq\*(haX1\*(TI\*(aq=beginning\-of\-line -bind \*(aq\*(haX7\*(TI\*(aq=beginning\-of\-line -bind \*(aq\*(haXH\*(aq=beginning\-of\-line -bind \*(aq\*(haX4\*(TI\*(aq=end\-of\-line -bind \*(aq\*(haX8\*(TI\*(aq=end\-of\-line -bind \*(aq\*(haXF\*(aq=end\-of\-line -bind \*(aq\*(haX3\*(TI\*(aq=delete\-char\-forward -.Ed -.Pp .It Ic break Op Ar level +.Pq keeps assignments , special Exit the .Ar level Ns th inner-most @@ -3238,6 +3278,7 @@ defaults to 1. .Op Fl \- .Ar command Op Ar arg ... .Xc +.Pq regular Execute the built-in command .Ar command . .Pp @@ -3245,6 +3286,7 @@ Execute the built-in command .Ic \ebuiltin .Ar command Op Ar arg ... .Xc +.Pq regular , decl-forwarder Same as .Ic builtin . Additionally acts as declaration utility forwarder, i.e. this is a @@ -3258,8 +3300,8 @@ is a declaration utility. .Op Fl u .Op Ar .Xc -Read files sequentially, in command line order, and write them to -standard output. +.Pq defer with flags +Copy files in command line order to standard output. If a .Ar file is a single dash @@ -3288,6 +3330,7 @@ utility is preferred over the builtin. .Op Fl eLP .Op Ar dir .Xc +.Pq regular Set the working directory to .Ar dir . If the parameter @@ -3355,6 +3398,7 @@ error occurred, 0 otherwise. .Op Fl eLP .Ar old new .Xc +.Pq regular The string .Ar new is substituted for @@ -3362,12 +3406,17 @@ is substituted for in the current directory, and the shell attempts to change to the new directory. .Pp +.It Ic cls +.Pq Li dot.mkshrc No alias +Reinitialise the display (hard reset). +.Pp .It Xo .Ic command .Op Fl pVv .Ar cmd .Op Ar arg ... .Xc +.Pq regular , decl-forwarder If neither the .Fl v nor @@ -3383,20 +3432,18 @@ cannot be a shell function; and secondly, special built-in commands lose their specialness (i.e. redirection and utility errors do not cause the shell to exit, and command assignments are not permanent). -The declaration utility property is not reset. .Pp If the .Fl p -option is given, a default search path is used instead of the current value of -.Ev PATH , -the actual value of which is system dependent. +option is given, a default search path, whose actual value is +system-dependent, is used instead of the current +.Ev PATH . .Pp If the .Fl v option is given, instead of executing .Ar cmd , -information about what would be executed is given (and the same is done for -.Ar arg ... ) . +information about what would be executed is given for each argument. For builtins, functions and keywords, their names are simply printed; for aliases, a command that defines them is printed; for utilities found by searching the @@ -3410,9 +3457,10 @@ The .Fl V option is like the .Fl v -option, except it is more verbose. +option, but more verbose. .Pp .It Ic continue Op Ar level +.Pq keeps assignments , special Jumps to the beginning of the .Ar level Ns th inner-most @@ -3425,17 +3473,33 @@ loop. .Ar level defaults to 1. .Pp +.It Ic dirs Op Fl lnv +.Pq Li dot.mkshrc No function +Print the directory stack. +.Fl l +causes tilde expansion to occur in the output. +.Fl n +causes line wrapping before 80 columns, whereas +.Fl v +causes numbered vertical output. +.Pp +.It Ic doch +.Pq Li dot.mkshrc No alias +Execute the last command with +.Xr sudo 8 . +.Pp .It Xo .Ic echo .Op Fl Een .Op Ar arg ... .Xc +.Pq regular .Em Warning: -this utility is not portable; use the Korn shell builtin +this utility is not portable; use the standard Korn shell built-in utility .Ic print -instead. +in new code instead. .Pp -Prints its arguments (separated by spaces) followed by a newline, to the +Print arguments, separated by spaces, followed by a newline, to standard output. The newline is suppressed if any of the arguments contain the backslash sequence @@ -3448,12 +3512,13 @@ The options are provided for compatibility with .Bx shell scripts. The -.Fl n -option suppresses the trailing newline, -.Fl e -enables backslash interpretation (a no-op, since this is normally done), and .Fl E -suppresses backslash interpretation. +option suppresses backslash interpretation, +.Fl e +enables it (normally default), +.Fl n +suppresses the trailing newline, +and anything else causes the word to be printed as argument instead. .Pp If the .Ic posix @@ -3466,9 +3531,40 @@ only the first argument is treated as an option, and only if it is exactly .Dq Li \-n . Backslash interpretation is disabled. .Pp +.It Xo +.Ic enable +.Op Fl anps +.Op Ar name ... +.Xc +.Pq Li dot.mkshrc No function +Hide and unhide built-in utilities, aliases and functions and those defined in +.Li dot.mkshrc . +.Pp +If no +.Ar name +is given or the +.Fl p +option is used, builtins are printed (behind the string +.Dq Li enable\ \& , +followed by +.Dq Li \-n\ \& +if the builtin is currently disabled), otherwise, they are disabled (if +.Fl n +is given) or re-enabled. +.Pp +When printing, only enabled builtins are printed by default; the +.Fl a +options prints all builtins, while +.Fl n +prints only disabled builtins instead; +.Fl s +limits the list to POSIX special builtins. +.Pp .It Ic eval Ar command ... -The arguments are concatenated (with spaces between them) to form a single -string which the shell then parses and executes in the current environment. +.Pq keeps assignments , special +The arguments are concatenated, with a space between each, +to form a single string which the shell then parses +and executes in the current execution environment. .Pp .It Xo .Ic exec @@ -3476,8 +3572,9 @@ string which the shell then parses and executes in the current environment. .Op Fl c .Op Ar command Op Ar arg ... .Xc -The command is executed without forking, replacing the shell process. -This is currently absolute, i.e.\& +.Pq keeps assignments , special +The command (with arguments) is executed without forking, +fully replacing the shell process; this is absolute, i.e.\& .Ic exec never returns, even if the .Ar command @@ -3490,7 +3587,7 @@ value, and .Fl c clears the environment before executing the child process, except for the .Ev _ -variable and direct assignments. +parameter and direct assignments. .Pp If no command is given except for I/O redirection, the I/O redirection is permanent and the shell is @@ -3503,32 +3600,38 @@ Note that the Bourne shell differs here; it does pass these file descriptors on. .Pp .It Ic exit Op Ar status -The shell or subshell exits with the specified exit status. -If -.Ar status -is not specified, the exit status is the current value of the -.Ic \&$? -parameter. +.Pq keeps assignments , special +The shell or subshell exits with the specified errorlevel +(or the current value of the +.Va $?\& +parameter). .Pp .It Xo .Ic export .Op Fl p .Op Ar parameter Ns Op = Ns Ar value .Xc +.Pq keeps assignments , special, decl-util Sets the export attribute of the named parameters. Exported parameters are passed in the environment to executed commands. If values are specified, the named parameters are also assigned. This is a declaration utility. .Pp If no parameters are specified, all parameters with the export attribute -set are printed one per line; either their names, or, if a +set are printed one per line: either their names, or, if a .Dq Li \- -with no option letter is specified, name=value pairs, or, with -.Fl p , +with no option letter is specified, name=value pairs, or, with the +.Fl p +option, .Ic export commands suitable for re-entry. .Pp +.It Ic extproc +.Pq OS/2 +Null command required for shebang-like functionality. +.Pp .It Ic false +.Pq regular A command that exits with a non-zero status. .Pp .It Xo @@ -3538,6 +3641,7 @@ A command that exits with a non-zero status. .Op Fl r .Op Ar first Op Ar last .Xc +.Pq regular .Ar first and .Ar last @@ -3563,7 +3667,7 @@ is specified, the editor specified by the .Ev FCEDIT parameter (if this parameter is not set, .Pa /bin/ed -is used), and then executed by the shell. +is used), and the result is executed by the shell. .Pp .It Xo .Ic fc @@ -3572,6 +3676,7 @@ is used), and then executed by the shell. .Op Ar old Ns = Ns Ar new .Op Ar prefix .Xc +.Pq regular Re-execute the selected command (the previous command by default) after performing the optional substitution of .Ar old @@ -3592,71 +3697,73 @@ This command is usually accessed with the predefined: .Ic alias r=\*(aqfc \-e \-\*(aq .Pp .It Ic fg Op Ar job ... +.Pq regular , needs job control Resume the specified job(s) in the foreground. If no jobs are specified, .Ic %+ is assumed. +.br See .Sx Job control below for more information. .Pp +.It Ic functions Op Ar name ... +.Pq built-in alias +Display the function definition commands corresponding to the listed, +or all defined, functions. +.Pp .It Xo .Ic getopts .Ar optstring name .Op Ar arg ... .Xc +.Pq regular Used by shell procedures to parse the specified arguments (or positional parameters, if no arguments are given) and to check for legal options. -.Ar optstring -contains the option letters that -.Ic getopts -is to recognise. -If a letter is followed by a colon, the option is expected to -have an argument. Options that do not take arguments may be grouped in a single argument. -If an option takes an argument and the option character is not the -last character of the argument it is found in, the remainder of the argument is -taken to be the option's argument; otherwise, the next argument is the option's -argument. +If an option takes an argument and the option character is not the last +character of the word it is found in, the remainder of the word is taken to +be the option's argument; otherwise, the next word is the option's argument. +.Pp +.Ar optstring +contains the option letters to be recognised. +If a letter is followed by a colon, the option takes an argument. .Pp Each time .Ic getopts is invoked, it places the next option in the shell parameter -.Ar name -and the index of the argument to be processed by the next call to -.Ic getopts -in the shell parameter -.Ev OPTIND . +.Ar name . If the option was introduced with a .Ql + , -the option placed in +the character placed in .Ar name is prefixed with a .Ql + . -When an option requires an argument, -.Ic getopts -places it in the shell parameter -.Ev OPTARG . +If the option takes an argument, it is placed in the shell parameter +.Ev OPTARG. .Pp When an illegal option or a missing option argument is encountered, a question mark or a colon is placed in .Ar name (indicating an illegal option or missing argument, respectively) and .Ev OPTARG -is set to the option character that caused the problem. -Furthermore, if +is set to the option letter that caused the problem. +Furthermore, unless .Ar optstring -does not begin with a colon, a question mark is placed in +begins with a colon, a question mark is placed in .Ar name , .Ev OPTARG -is unset, and an error message is printed to standard error. +is unset and a diagnostic is shown on standard error. .Pp +.Ic getopts +records the index of the argument to be processed by the next call in +.Ev OPTIND . When the end of the options is encountered, .Ic getopts -exits with a non-zero exit status. -Options end at the first (non-option -argument) argument that does not start with a -.Ql \- , +returns a non-zero exit status. +Options end at the first argument that does not start with a +.Ql \- +.Pq non-option argument or when a .Dq Li \-\- argument is encountered. @@ -3666,7 +3773,8 @@ Option parsing can be reset by setting to 1 (this is done automatically whenever the shell or a shell procedure is invoked). .Pp -Warning: Changing the value of the shell parameter +.Em Warning: +Changing the value of the shell parameter .Ev OPTIND to a value other than 1 or parsing different sets of arguments without resetting @@ -3674,41 +3782,50 @@ resetting may lead to unexpected results. .Pp .It Xo -.Ic global -.Op Ic +\-aglpnrtUux -.Oo Fl L Ns Op Ar n -.No \*(Ba Fl R Ns Op Ar n -.No \*(Ba Fl Z Ns Op Ar n Oc -.Op Fl i Ns Op Ar n -.Oo Ar name -.Op Ns = Ns Ar value -.Ar ... Oc -.Xc -See -.Ic typeset Fl g . -.No Deprecated , Em will -be removed from a future version of -.Nm . -.Pp -.It Xo .Ic hash .Op Fl r .Op Ar name ... .Xc -Without arguments, any hashed executable command pathnames are listed. +.Pq built-in alias +Without arguments, any hashed executable command paths are listed. The .Fl r -option causes all hashed commands to be removed from the hash table. +option causes all hashed commands to be removed from the cache. Each .Ar name -is searched as if it were a command name and added to the hash table if it is -an executable command. +is searched as if it were a command name +and added to the cache if it is an executable command. +.Pp +.It Ic hd Op Ar +.Pq Li dot.mkshrc No alias or function +Hexdump stdin or arguments legibly. +.Pp +.It Xo +.Ic history +.Op Fl nr +.Op Ar first Op Ar last +.Xc +.Pq built-in alias +Same as +.Ic fc Fl l Pq see above . +.Pp +.It Xo +.Ic integer +.Op flags +.Oo Ar name +.Op Ns = Ns Ar value +.Ar ... Oc +.Xc +.Pq built-in alias +Same as +.Ic typeset Fl i Pq see below . .Pp .It Xo .Ic jobs .Op Fl lnp .Op Ar job ... .Xc +.Pq regular Display information about the specified job(s); if no jobs are specified, all jobs are displayed. The @@ -3735,6 +3852,7 @@ and the displayed job. .No { Ar job \*(Ba pid \*(Ba pgrp No } .Ar ... .Xc +.Pq regular Send the specified signal to the specified jobs, process IDs or process groups. If no signal is specified, the @@ -3751,23 +3869,36 @@ below for the format of .Fl l .Op Ar exit-status ... .Xc +.Pq regular Print the signal name corresponding to .Ar exit-status . If no arguments are specified, a list of all the signals with their numbers and a short description of each are printed. .Pp .It Ic let Op Ar expression ... +.Pq regular Each expression is evaluated (see .Sx Arithmetic expressions above). -If all expressions are successfully evaluated, the exit status is 0 (1) -if the last expression evaluated to non-zero (zero). +If all expressions evaluate successfully, the exit status is +0 (1) if the last expression evaluated to non-zero (zero). If an error occurs during the parsing or evaluation of an expression, the exit status is greater than 1. Since expressions may need to be quoted, -.No \&(( Ar expr No )) +.Li \&(( Ar expr Li )) is syntactic sugar for: -.Dl "{ \e\ebuiltin let \*(aq" Ns Ar expr Ns "\*(aq; }" +.Dl "{ \e\ebuiltin let \*(aq" Ns Ar expr Ns Li "\*(aq; }" +.Pp +.It Xo +.Ic local +.Op flags +.Oo Ar name +.Op Ns = Ns Ar value +.Ar ... Oc +.Xc +.Pq built-in alias +Same as +.Ic typeset Pq see below . .Pp .It Xo .Ic mknod @@ -3782,8 +3913,9 @@ is syntactic sugar for: .Ar name .Cm p .Xc +.Pq optional Create a device special file. -The file type may be +The file type may be one of .Cm b (block type device), .Cm c @@ -3806,11 +3938,36 @@ This is not normally part of however, distributors may have added this as builtin as a speed hack. .Pp .It Xo +.Ic nameref +.Op flags +.Oo Ar name +.Op Ns = Ns Ar value +.Ar ... Oc +.Xc +.Pq built-in alias +Same as +.Ic typeset Fl n Pq see below . +.Pp +.It Xo +.Ic popd +.Op Fl lnv +.Op Ic + Ns Ar n +.Xc +.Pq Li dot.mkshrc No function +Pops the directory stack and returns to the new top directory. +The flags are as in +.Ic dirs Pq see above . +A numeric argument +.Ic + Ns Ar n +selects the entry in the stack to discard. +.Pp +.It Xo .Ic print .Oo Fl AcelNnprsu Ns Oo Ar n Oc \*(Ba .Fl R Op Fl n Oc .Op Ar argument ... .Xc +.Pq regular Print the specified argument(s) on the standard output, separated by spaces, terminated with a newline. The escapes mentioned in @@ -3822,7 +3979,7 @@ which is equivalent to using the option, are interpreted. .Pp The options are as follows: -.Bl -tag -width Ds +.Bl -tag -width XuXnX .It Fl A Each .Ar argument @@ -3872,24 +4029,73 @@ its first argument as option only if it is exactly .Dq Li \-n .Pq to suppress the trailing newline . .Pp +.It Ic printf Ar format Op Ar arguments ... +.Pq optional , defer always +If compiled in, format and print the arguments, supporting the bare +.Tn POSIX Ns -mandated +minimum. +If an external utility of the same name is found, it is deferred to, +unless run as direct builtin call or from the +.Ic builtin +utility. +.Pp +.It Ic pushd Op Fl lnv +.Pq Li dot.mkshrc No function +Rotate the top two elements of the directory stack. +The options are the same as for +.Ic dirs Pq see above , +and +.Ic pushd +changes to the topmost directory stack entry after acting. +.Pp +.It Xo +.Ic pushd +.Op Fl lnv +.Ic + Ns Ar n +.Xc +.Pq Li dot.mkshrc No function +Rotate the element number +.Ar n +to the top. +.Pp +.It Xo +.Ic pushd +.Op Fl lnv +.Ar name +.Xc +.Pq Li dot.mkshrc No function +Push +.Ar name +on top of the stack. +.Pp .It Ic pwd Op Fl LP +.Pq regular Print the present working directory. -If the -.Fl L -option is used or if the -.Ic physical -option isn't set (see the -.Ic set -command below), the logical path is printed (i.e. the path used to -.Ic cd -to the current directory). -If the +If no options are given, +.Ic pwd +behaves as if the .Fl P -option (physical path) is used or if the +option (print physical path) was used if the .Ic physical -option is set, the path determined from the filesystem (by following -.Dq Li .. -directories to the root directory) is printed. +shell option is set, the +.Fl L +option (print logical path) otherwise. +The logical path is the path used to +.Ic cd +to the current directory; +the physical path is determined from the filesystem (by following +.Dq Li ..\& +directories to the root directory). +.Pp +.It Xo +.Ic r +.Op Fl g +.Op Ar old Ns = Ns Ar new +.Op Ar prefix +.Xc +.Pq built-in alias +Same as +.Ic fc Fl e \& Pq see above . .Pp .It Xo .Ic read @@ -3903,20 +4109,17 @@ directories to the root directory) is printed. .Op Fl rs .Op Ar p ... .Xc +.Pq regular Reads a line of input, separates the input into fields using the .Ev IFS parameter (see .Sx Substitution -above), and assigns each field to the specified parameters +above) or other specified means, +and assigns each field to the specified parameters .Ar p . If no parameters are specified, the .Ev REPLY parameter is used to store the result. -With the -.Fl A -and -.Fl a -options, only no or one parameter is accepted. If there are more parameters than fields, the extra parameters are set to the empty string or 0; if there are more fields than parameters, the last parameter is assigned the remaining fields (including the word separators). @@ -3929,8 +4132,9 @@ Store the result into the parameter (or .Ev REPLY ) as array of words. +Only no or one parameter is accepted. .It Fl a -Store the result without word splitting into the parameter +Store the result, without applying IFS word splitting, into the parameter .Ar p (or .Ev REPLY ) @@ -3938,11 +4142,12 @@ as array of characters (wide characters if the .Ic utf8\-mode option is enacted, octets otherwise); the codepoints are encoded as decimal numbers by default. +Only no or one parameter is accepted. .It Fl d Ar x Use the first byte of .Ar x , .Dv NUL -if empty, instead of the ASCII newline character as input line delimiter. +if empty, instead of the ASCII newline character to delimit input lines. .It Fl N Ar z Instead of reading till end-of-line, read exactly .Ar z @@ -3957,13 +4162,14 @@ Instead of reading till end-of-line, read up to bytes but return as soon as any bytes are read, e.g.\& from a slow terminal device, or if EOF or a timeout occurs. .It Fl p -Read from the currently active co-process, see +Read from the currently active co-process (see .Sx Co-processes -above for details on this. +above for details) instead of from a file descriptor. .It Fl u Ns Op Ar n -Read from the file descriptor +Read from the file descriptor number .Ar n (defaults to 0, i.e.\& standard input). +.br The argument must immediately follow the option character. .It Fl t Ar n Interrupt reading after @@ -3975,12 +4181,10 @@ is the same as if .Dv SIGALRM were caught if the timeout occurred, but partial reads may still be returned. .It Fl r -Normally, the ASCII backslash character escapes the special -meaning of the following character and is stripped from the input; +Normally, .Ic read -does not stop when encountering a backslash-newline sequence and -does not store that newline in the result. -This option enables raw mode, in which backslashes are not processed. +strips backslash-newline sequences and any remaining backslashes from input. +This option enables raw mode, in which backslashes are retained and ignored. .It Fl s The input line is saved to the history. .El @@ -4012,12 +4216,12 @@ exits with a non-zero status. .Op Ns = Ns Ar value .Ar ... Oc .Xc +.Pq keeps assignments , special, decl-util Sets the read-only attribute of the named parameters. -This is a declaration utility. If values are given, -parameters are set to them before setting the attribute. -Once a parameter is -made read-only, it cannot be unset and its value cannot be changed. +parameters are assigned these before disallowing writes. +Once a parameter is made read-only, +it cannot be unset and its value cannot be changed. .Pp If no parameters are specified, the names of all parameters with the read-only attribute are printed one per line, unless the @@ -4032,40 +4236,40 @@ printed. .Op Fl \- .Ar name .Xc -Prints the resolved absolute pathname corresponding to +.Pq defer with flags +Resolves an absolute pathname corresponding to .Ar name . +If the resolved pathname either exists or can be created immediately, +.Ic realpath +returns 0 and prints the resolved pathname, +otherwise or if an error occurs, it issues a diagnostic and returns nonzero. If .Ar name ends with a slash .Pq Ql / , -it's also checked for existence and whether it is a directory; otherwise, -.Ic realpath -returns 0 if the pathname either exists or can be created immediately, -i.e. all but the last component exist and are directories. -For calls from the shell, if any options are given, an external -.Xr realpath 1 -utility is preferred over the builtin. +resolving to an extant non-directory is also treated as error. .Pp .It Xo .Ic rename .Op Fl \- .Ar from to .Xc +.Pq defer always Renames the file .Ar from to .Ar to . Both must be complete pathnames and on the same device. -An external utility is preferred over this builtin, -which is intended for emergency situations -.Pq where Pa /bin/mv No becomes unusable -and directly calls +Intended for emergency situations +.Pq where Pa /bin/mv No becomes unusable ; +directly calls .Xr rename 2 . .Pp .It Ic return Op Ar status +.Pq keeps assignments , special Returns from a function or .Ic \&. -script, with exit status +script with errorlevel .Ar status . If no .Ar status @@ -4080,50 +4284,65 @@ treats both profile and .Ev ENV files as .Ic \&. -scripts, while the original Korn shell only treats profiles as +scripts, while the original Korn shell only treated profiles as .Ic \&. scripts. .Pp +.It Ic rot13 +.Pq Li dot.mkshrc No alias +ROT13-encrypts/-decrypts stdin to stdout. +.Pp .It Xo -.Ic set Op Ic +\-abCefhiklmnprsUuvXx -.Op Ic +\-o Ar option -.Op Ic +\-A Ar name +.Ic set Op Fl +abCefhiklmnprsUuvXx +.Op Fl +o Ar option +.Op Fl +A Ar name .Op Fl \- .Op Ar arg ... .Xc +.Pq keeps assignments , special The .Ic set -command can be used to set +command can be used to show all shell parameters +.Pq like Ic typeset \- , +set .Pq Ic \- or clear .Pq Ic + -shell options, set the positional parameters, or set an array parameter. +shell options, set an array parameter or the positional parameters. +.Pp Options can be changed using the -.Cm +\-o Ar option +.Fl +o Ar option syntax, where .Ar option is the long name of an option, or using the -.Cm +\- Ns Ar letter +.Fl + Ns Ar letter syntax, where .Ar letter is the option's single letter name (not all options have a single letter name). -The following table lists both option letters (if they exist) and long names -along with a description of what the option does: +The following table lists short (if extant) and long names +along with a description of what each option does: .Bl -tag -width 3n .It Fl A Ar name Sets the elements of the array parameter .Ar name to .Ar arg ... +.Pp If .Fl A is used, the array is reset (i.e. emptied) first; if .Ic +A is used, the first N elements are set (where N is the number of arguments); the rest are left untouched. +If +.Ar name +ends with a +.Sq + , +the array is appended to instead. .Pp An alternative syntax for the command -.Ic set \-A foo \-\- a b c +.Ic set \-A foo \-\- a b c; +.Ic set \-A foo+ \-\- d e which is compatible to .Tn GNU .Nm bash @@ -4135,14 +4354,15 @@ is: .It Fl a \*(Ba Fl o Ic allexport All new parameters are created with the export attribute. .It Fl b \*(Ba Fl o Ic notify -Print job notification messages asynchronously, instead of just before the +Print job notification messages asynchronously instead of just before the prompt. -Only used if job control is enabled +Only used with job control .Pq Fl m . .It Fl C \*(Ba Fl o Ic noclobber Prevent \*(Gt redirection from overwriting existing files. Instead, \*(Gt\*(Ba must be used to force an overwrite. -Note that this is not safe to use for creation of temporary files or +.Em Note: +This is not safe to use for creation of temporary files or lockfiles due to a TOCTOU in a check allowing one to redirect output to .Pa /dev/null or other device files even in @@ -4155,16 +4375,17 @@ trap) as soon as an error occurs or a command fails (i.e. exits with a non-zero status). This does not apply to commands whose exit status is explicitly tested by a shell construct such as +.Ic !\& , .Ic if , -.Ic until , -.Ic while +.Ic until or -.Ic \&! +.Ic while statements. For -.Ic && -or -.Ic \*(Ba\*(Ba , +.Ic && , +.Ic \*(Ba\*(Ba +and pipelines (but mind +.Fl o Ic pipefail ) , only the status of the last command is tested. .It Fl f \*(Ba Fl o Ic noglob Do not expand file name patterns. @@ -4176,29 +4397,34 @@ Enabled by default for non-interactive shells. .It Fl i \*(Ba Fl o Ic interactive The shell is an interactive shell. This option can only be used when the shell is invoked. -See above for a description of what this means. +See above for details. .It Fl k \*(Ba Fl o Ic keyword Parameter assignments are recognised anywhere in a command. .It Fl l \*(Ba Fl o Ic login The shell is a login shell. This option can only be used when the shell is invoked. -See above for a description of what this means. +See above for what this means. .It Fl m \*(Ba Fl o Ic monitor Enable job control (default for interactive shells). .It Fl n \*(Ba Fl o Ic noexec Do not execute any commands. -Useful for checking the syntax of scripts -(ignored if interactive). +Useful for checking the syntax of scripts. +Ignored if reading commands from a tty. .It Fl p \*(Ba Fl o Ic privileged The shell is a privileged shell. It is set automatically if, when the shell starts, the real UID or GID does not match the effective UID (EUID) or GID (EGID), respectively. See above for a description of what this means. +.Pp +If the shell is privileged, setting this flag after startup files +have been processed let it go full setuid and/or setgid. +Clearing this flag makes the shell drop privileges. +Changing this flag resets the groups vector. .It Fl r \*(Ba Fl o Ic restricted The shell is a restricted shell. This option can only be used when the shell is invoked. -See above for a description of what this means. +See above for what this means. .It Fl s \*(Ba Fl o Ic stdin If used when the shell is invoked, commands are read from standard input. Set automatically if the shell is invoked with no arguments. @@ -4207,12 +4433,11 @@ When .Fl s is used with the .Ic set -command it causes the specified arguments to be sorted before assigning them to -the positional parameters (or to array +command it causes the specified arguments to be sorted ASCIIbetically +before assigning them to the positional parameters (or to array .Ar name , -if -.Fl A -is used). +with +.Fl A ) . .It Fl U \*(Ba Fl o Ic utf8\-mode Enable UTF-8 support in the .Sx Emacs editing mode @@ -4258,23 +4483,24 @@ Write shell input to standard error as it is read. .It Fl X \*(Ba Fl o Ic markdirs Mark directories with a trailing .Ql / -during file name generation. +during globbing. .It Fl x \*(Ba Fl o Ic xtrace -Print command trees when they are executed, preceded by -the value of +Print commands when they are executed, preceded by .Ev PS4 . .It Fl o Ic bgnice Background jobs are run with lower priority. .It Fl o Ic braceexpand -Enable brace expansion (a.k.a. alternation). +Enable brace expansion. This is enabled by default. .It Fl o Ic emacs Enable BRL emacs-like command-line editing (interactive shells only); see .Sx Emacs editing mode . +Enabled by default. .It Fl o Ic gmacs Enable gmacs-like command-line editing (interactive shells only). -Currently identical to emacs editing except that transpose\-chars (\*(haT) acts -slightly differently. +Currently identical to emacs editing except that +.Li transpose\-chars Pq \*(haT +acts slightly differently. .It Fl o Ic ignoreeof The shell will not (easily) exit when end-of-file is read; .Ic exit @@ -4285,8 +4511,7 @@ is read 13 times in a row. .It Fl o Ic inherit\-xtrace Do not reset .Fl o Ic xtrace -upon entering functions. -This is enabled by default. +upon entering functions (default). .It Fl o Ic nohup Do not kill running jobs with a .Dv SIGHUP @@ -4301,7 +4526,7 @@ doesn't have this option, but does send the signal. .It Fl o Ic nolog No effect. -In the original Korn shell, this prevents function definitions from +In the original Korn shell, this prevented function definitions from being stored in the history file. .It Fl o Ic physical Causes the @@ -4324,14 +4549,14 @@ parameter; only the .Ic cd command changes .Ev PWD . -See the +See .Ic cd and .Ic pwd -commands above for more details. +above for more details. .It Fl o Ic pipefail -Make the exit status of a pipeline (before logically complementing) the -rightmost non-zero errorlevel, or zero if all commands exited with zero. +Make the exit status of a pipeline the rightmost non-zero errorlevel, +or zero if all commands exited with zero. .It Fl o Ic posix Behave closer to the standards (see @@ -4339,15 +4564,17 @@ Behave closer to the standards for details). Automatically enabled if the basename of the shell invocation begins with .Dq sh -and this autodetection feature is compiled in -.Pq not in MirBSD . +and this autodetection feature is compiled in (not in MirBSD; commonly used for +.Nm lksh +only). As a side effect, setting this flag turns off the .Ic braceexpand and .Ic utf8\-mode flags, which can be turned back on manually, and +.Pq unless both are enabled at the same time .Ic sh -mode (unless both are enabled at the same time). +mode. .It Fl o Ic sh Enable .Pa /bin/sh @@ -4357,7 +4584,7 @@ mode (see Automatically enabled if the basename of the shell invocation begins with .Dq sh and this autodetection feature is compiled in -.Pq not in MirBSD . +.Pq rather uncommon . As a side effect, setting this flag turns off .Ic braceexpand mode, which can be turned back on manually, and @@ -4371,19 +4598,20 @@ See .Sx Vi editing mode for documentation and limitations. .It Fl o Ic vi\-esccomplete -In vi command-line editing, do command and file name completion when escape -(\*(ha[) is entered in command mode. +In vi command-line editing, do command and file name completion when Esc +.Pq \*(ha[ +is entered in command mode. .It Fl o Ic vi\-tabcomplete -In vi command-line editing, do command and file name completion when tab (\*(haI) -is entered in insert mode. -This is the default. +In vi command-line editing, do command and file name completion when Tab +.Pq \*(haI +is entered in insert mode (default). .It Fl o Ic viraw No effect. In the original Korn shell, unless .Ic viraw was set, the vi command-line mode would let the .Xr tty 4 -driver do the work until ESC (\*(ha[) was entered. +driver do the work until Esc was entered. .Nm is always in viraw mode. .El @@ -4407,40 +4635,65 @@ order, to the positional parameters (i.e. $1, $2, etc.). If options end with .Dq Li \-\- and there are no remaining arguments, all positional parameters are cleared. -If no options or arguments are given, the values of all names are printed. For unknown historical reasons, a lone .Dq Li \- -option is treated specially \*(en it clears both the +option is treated specially\*(EMit clears both the .Fl v and .Fl x options. +If no options or arguments are given, the values of all parameters are printed +.Pq suitably quoted . +.Pp +.It Xo +.Ic setenv +.Op Ar name Op Ar value +.Xc +.Pq Li dot.mkshrc No function +Without arguments, display the names and values of all exported parameters. +Otherwise, set +.Ar name Ns 's +export attribute, and its value to +.Ar value Pq empty string if none given . .Pp .It Ic shift Op Ar number +.Pq keeps assignments , special The positional parameters .Ar number Ns +1 , .Ar number Ns +2 , -etc. are renamed to 1, 2, etc. -.Ar number -defaults to 1. +etc. +.Pq Ar number No defaults to 1 +are renamed to 1, 2, etc. .Pp .It Ic sleep Ar seconds +.Pq regular , needs Xr select 2 Suspends execution for a minimum of the .Ar seconds -specified as positive decimal value with an optional fractional part. +(specified as positive decimal value with an optional fractional part). Signal delivery may continue execution earlier. .Pp +.It Ic smores Op Ar +.Pq Li dot.mkshrc No function +Simple pager: +.Aq Enter +next; +.So q Sc Ns + Ns Aq Enter +quit +.Pp .It Ic source Ar file Op Ar arg ... +.Pq keeps assignments Like -.Ic \&. Po Do dot Dc Pc , +.Ic \&. +.Pq Dq dot , except that the current working directory is appended to the -search path (GNU -.Nm bash -extension). +search path. +.Pq GNU Nm bash No extension .Pp .It Ic suspend +.Pq needs job control and Xr getsid 2 Stops the shell as if it had received the suspend character from the terminal. +.Pp It is not possible to suspend a login shell unless the parent process is a member of the same terminal session but is a member of a different process group. @@ -4450,22 +4703,24 @@ it can be suspended. .Pp .It Ic test Ar expression .It Ic \&[ Ar expression Ic \&] +.Pq regular .Ic test evaluates the .Ar expression -and returns zero status if true, 1 if false, or greater than 1 if there -was an error. -It is normally used as the condition command of +and exits with status code 0 if true, 1 if false, +or greater than 1 if there was an error. +It is often used as the condition command of .Ic if and .Ic while statements. -Symbolic links are followed for all +All .Ar file -expressions except +expressions, except .Fl h and -.Fl L . +.Fl L , +follow symbolic links. .Pp The following basic expressions are available: .Bl -tag -width 17n @@ -4502,7 +4757,7 @@ is a symbolic link. .It Fl k Ar file .Ar file Ns 's mode has the -.Xr sticky 8 +.Xr sticky 7 bit set. .It Fl L Ar file .Ar file @@ -4592,7 +4847,7 @@ The same can be achieved with [ \-o ?foo ] like in .At .Nm ksh93 . .Ar option -can also be the short flag led by either +can also be the short flag prefixed with either .Ql \- or .Ql + @@ -4605,14 +4860,22 @@ instead of .Dq Li xtrace . .It Ar string No = Ar string Strings are equal. +In double brackets, pattern matching +.Pq R59+ using extglobs +occurs if the right-hand string isn't quoted. .It Ar string No == Ar string -Strings are equal. +Same as +.Sq = +.Pq deprecated . +.It Ar string No != Ar string +Strings are not equal. +See +.Sq = +regarding pattern matching. .It Ar string No \*(Gt Ar string First string operand is greater than second string operand. .It Ar string No \*(Lt Ar string First string operand is less than second string operand. -.It Ar string No != Ar string -Strings are not equal. .It Ar number Fl eq Ar number Numbers compare equal. .It Ar number Fl ne Ar number @@ -4659,6 +4922,7 @@ respectively; three-argument forms ultimately prefer binary operations, followed by negation and parenthesis lowering; two- and four-argument forms prefer negation followed by parenthesis; the one-argument form always implies .Fl n . +To assume this is not necessarily portable. .Pp .Sy Note : A common mistake is to use @@ -4673,14 +4937,13 @@ or .Dq Li \-n . Use tests like .Dq Li if \&[ x\&"$foo\&" = x"bar" \&] -instead, or the double-bracket operator -.Dq Li if \&[[ $foo = bar \&]] -or, to avoid pattern matching (see +instead, or the double-bracket operator (see .Ic \&[[ above): -.Dq Li if \&[[ $foo = \&"$bar" \&]] -.Pp -The +.Dq Li if \&[[ $foo = bar \&]] +or, to avoid pattern matching, +.Dq Li if \&[[ $foo = \&"$bar" \&]] ; +the .Ic \&[[ ... \&]] construct is not only more secure to use but also often faster. .Pp @@ -4689,37 +4952,35 @@ construct is not only more secure to use but also often faster. .Op Fl p .Op Ar pipeline .Xc +.Pq reserved word If a .Ar pipeline is given, the times used to execute the pipeline are reported. If no pipeline is given, then the user and system time used by the shell itself, and all the commands it has run since it was started, are reported. +.Pp The times reported are the real time (elapsed time from start to finish), the user CPU time (time spent running in user mode), and the system CPU time (time spent running in kernel mode). +.Pp Times are reported to standard error; the format of the output is: .Pp .Dl "0m0.03s real 0m0.02s user 0m0.01s system" .Pp If the .Fl p -option is given the output is slightly longer: +option is given (which is only permitted if +.Ar pipeline +is a simple command), the output is slightly longer: .Bd -literal -offset indent real 0.03 user 0.02 sys 0.01 .Ed .Pp -It is an error to specify the -.Fl p -option unless -.Ar pipeline -is a simple command. -.Pp -Simple redirections of standard error do not affect the output of the -.Ic time -command: +Simple redirections of standard error do not affect +.Ic time Ns 's output : .Pp .Dl $ time sleep 1 2\*(Gtafile .Dl $ { time sleep 1; } 2\*(Gtafile @@ -4729,8 +4990,9 @@ Times for the first command do not go to but those of the second command do. .Pp .It Ic times -Print the accumulated user and system times used both by the shell -and by processes that the shell started which have exited. +.Pq keeps assignments , special +Print the accumulated user and system times (see above) used both +by the shell and by processes that the shell started which have exited. The format of the output is: .Bd -literal -offset indent 0m0.01s 0m0.00s @@ -4738,6 +5000,7 @@ The format of the output is: .Ed .Pp .It Ic trap Ar n Op Ar signal ... +.Pq keeps assignments , special If the first operand is a decimal unsigned integer, this resets all specified signals to the default action, i.e. is the same as calling .Ic trap @@ -4745,11 +5008,10 @@ with a dash .Pq Dq Li \- as .Ar handler , -followed by the arguments -.Pq Ar n Op Ar signal ... , -all of which are treated as signals. +followed by the arguments (interpreted as signals). .Pp .It Ic trap Op Ar handler signal ... +.Pq keeps assignments , special Sets a trap handler that is to be executed when any of the specified .Ar signal Ns s are received. @@ -4758,13 +5020,21 @@ is either an empty string, indicating the signals are to be ignored, a dash .Pq Dq Li \- , indicating that the default action is to be taken for the signals .Pq see Xr signal 3 , -or a string containing shell commands to be executed at the first opportunity +or a string comprised of shell commands to be executed at the first opportunity (i.e. when the current command completes or before printing the next .Ev PS1 prompt) after receipt of one of the signals. .Ar signal -is the name of a signal -.Pq e.g.\& Dv PIPE or Dv ALRM +is the name, possibly prefixed with +.Dq Li SIG , +of a signal +.Po +e.g.\& +.Dv PIPE , +.Dv ALRM +or +.Dv SIGINT +.Pc or the number of the signal (see the .Ic kill Fl l command above). @@ -4782,6 +5052,13 @@ or option were set. .Dv EXIT handlers are executed in the environment of the last executed command. +The original Korn shell's +.Dv DEBUG +trap and handling of +.Dv ERR +and +.Dv EXIT +in functions are not yet implemented. .Pp Note that, for non-interactive shells, the trap handler cannot be changed for signals that were ignored when the shell started. @@ -4792,23 +5069,22 @@ the shell started is shown as a series of commands. Note that the output of .Ic trap -cannot be usefully piped to another process (an artifact of the fact that -traps are cleared when subprocesses are created). -.Pp -The original Korn shell's -.Dv DEBUG -trap and the handling of -.Dv ERR -and -.Dv EXIT -traps in functions are not yet implemented. +cannot be usefully captured or piped to another process (an artifact +of the fact that traps are cleared when subprocesses are created). .Pp .It Ic true -A command that exits with a zero value. +.Pq regular +A command that exits with a zero status. +.Pp +.It Ic type Ar name ... +.Pq built-in alias +Reveal how +.Ar name +would be interpreted as command. .Pp .It Xo .Ic typeset -.Op Ic +\-aglpnrtUux +.Op Fl +aglpnrtUux .Oo Fl L Ns Op Ar n .No \*(Ba Fl R Ns Op Ar n .No \*(Ba Fl Z Ns Op Ar n Oc @@ -4822,29 +5098,35 @@ A command that exits with a zero value. .Fl f Op Fl tux .Op Ar name ... .Xc -Display or set parameter attributes. -This is a declaration utility. +.Pq keeps assignments , decl-util +Display or set attributes of shell parameters or functions. With no .Ar name -arguments, parameter attributes are displayed; if no options are used, the -current attributes of all parameters are printed as +arguments, parameter attributes are shown; +if no options are used, the current attributes of all parameters are printed as .Ic typeset commands; if an option is given (or .Dq Li \- with no option letter), all parameters and their values with the specified attributes are printed; if options are introduced with -.Ql + , -parameter values are not printed. +.Ql + +.Po +or +.Dq Li + +alone +.Pc , +only names are printed. .Pp -If +If any .Ar name -arguments are given, the attributes of the named parameters are set +arguments are given, the attributes of the so named parameters are set .Pq Ic \&\- or cleared .Pq Ic \&+ ; -inside a function, this will cause the parameters to be created -(with no value) in the local scope (but see -.Fl g ) . +inside a function, this will cause the parameters to be created (and set to +.Dq +if no value is given) in the local scope +.Pq except if Fl g No is used . Values for parameters may optionally be specified. For .Ar name Ns \&[*] , @@ -4861,36 +5143,39 @@ arguments are given, functions are listed with their values (i.e. definitions) unless options are introduced with .Ql + , -in which case only the function names are reported. +in which case only the names are displayed. .Bl -tag -width Ds .It Fl a Indexed array attribute. .It Fl f Function mode. -Display or set functions and their attributes, instead of parameters. +Display or set shell functions and their attributes, +instead of shell parameters. .It Fl g +.Dq global +mode. Do not cause named parameters to be created in the local scope when called inside a function. .It Fl i Ns Op Ar n Integer attribute. .Ar n -specifies the base to use when displaying the integer (if not specified, the -base given in the first assignment is used). -Parameters with this attribute may -be assigned values containing arithmetic expressions. +specifies the base to use when stringifying the integer +(if not specified, the base given in the first assignment is used). +Parameters with this attribute +may be assigned arithmetic expressions for values. .It Fl L Ns Op Ar n Left justify attribute. .Ar n specifies the field width. If .Ar n -is not specified, the current width of a parameter (or the width of its first -assigned value) is used. -Leading whitespace (and zeros, if used with the +is not specified, the current width of the parameter +(or the width of its first assigned value) is used. +Leading whitespace (and digit zeros, if used with the .Fl Z option) is stripped. -If necessary, values are either truncated or space padded -to fit the field width. +If necessary, values are either truncated +or padded with space to fit the field width. .It Fl l Lower case attribute. All upper case ASCII characters in values are converted to lower case. @@ -4917,7 +5202,7 @@ is lazily evaluated at the time .Ar name is accessed. This can be used by functions to access variables whose names are -passed as parameters, instead of using +passed as parameters, instead of resorting to .Ic eval . .It Fl p Print complete @@ -4930,32 +5215,32 @@ Right justify attribute. specifies the field width. If .Ar n -is not specified, the current width of a parameter (or the width of its first -assigned value) is used. +is not specified, the current width of the parameter +(or the width of its first assigned value) is used. Trailing whitespace is stripped. -If necessary, values are either stripped of leading characters or space -padded to make them fit the field width. +If necessary, values are either stripped of leading characters +or padded with space to fit the field width. .It Fl r Read-only attribute. Parameters with this attribute may not be assigned to or unset. Once this attribute is set, it cannot be turned off. .It Fl t Tag attribute. -Has no meaning to the shell; provided for application use. +This attribute has no meaning to the shell for parameters +and is provided for application use. .Pp For functions, .Fl t is the trace attribute. When functions with the trace attribute are executed, the -.Ic xtrace +.Fl o Ic xtrace .Pq Fl x shell option is temporarily turned on. .It Fl U Unsigned integer attribute. -Integers are printed as unsigned values (combine with the +Integers are printed as unsigned values (combined with the .Fl i option). -This option is not in the original Korn shell. .It Fl u Upper case attribute. All lower case ASCII characters in values are converted to upper case. @@ -4971,7 +5256,8 @@ above.) .Pp For functions, .Fl u -is the undefined attribute. +is the undefined attribute, used with +.Ev FPATH . See .Sx Functions above for the implications of this. @@ -5005,29 +5291,30 @@ unless they are also given on the same command line. .Pp .It Xo .Ic ulimit -.Op Fl aBCcdefHilMmnOPpqrSsTtVvw +.Op Fl aBCcdefHilMmnOPpqrSsTtVvwx .Op Ar value .Xc +.Pq regular Display or set process limits. If no options are used, the file size limit .Pq Fl f is assumed. .Ar value , if specified, may be either an arithmetic expression or the word -.Dq unlimited . +.Dq Li unlimited . The limits affect the shell and any processes created by the shell after a limit is imposed. -Note that some systems may not allow limits to be increased +Note that systems may not allow some limits to be increased once they are set. Also note that the types of limits available are system -dependent \*(en some systems have only the +dependent\*(EMsome systems have only the .Fl f -limit, or not even that, or can set only the soft limits +limit, or not even that, or can set only the soft limits, etc. .Bl -tag -width 5n .It Fl a -Display all limits; unless +Display all limits (soft limits unless .Fl H -is used, soft limits are displayed. +is used). .It Fl B Ar n Set the socket buffer size to .Ar n @@ -5040,19 +5327,22 @@ Impose a size limit of .Ar n blocks on the size of core dumps. .It Fl d Ar n -Impose a size limit of +Limit the size of the data area to .Ar n -kibibytes on the size of the data area. +kibibytes. .It Fl e Ar n Set the maximum niceness to .Ar n . .It Fl f Ar n Impose a size limit of .Ar n -blocks on files written by the shell and its child processes (files of any -size may be read). +blocks on files written by the shell and its child processes +.Pq any size may be read . .It Fl H Set the hard limit only (the default is to set both hard and soft limits). +With +.Fl a , +display all hard limits. .It Fl i Ar n Set the number of pending signals to .Ar n . @@ -5078,10 +5368,23 @@ Set the number of AIO operations to .It Fl P Ar n Limit the number of threads per process to .Ar n . +.Pp +This option mostly matches +.At +.Nm ksh93 Ns 's +.Fl T ; +.br +on +.Tn AIX , +see +.Fl r +as used by its +.Nm ksh +though. .It Fl p Ar n Impose a limit of .Ar n -processes that can be run by the user at any one time. +processes that can be run by the user (uid) at any one time. .It Fl q Ar n Limit the size of .Tn POSIX @@ -5089,18 +5392,28 @@ message queues to .Ar n bytes. .It Fl r Ar n +.Pq Cm AIX +Limit the number of threads per process to +.Ar n . +.br +.Pq Cm Linux Set the maximum real-time priority to .Ar n . .It Fl S Set the soft limit only (the default is to set both hard and soft limits). +With +.Fl a , +display soft limits (default). .It Fl s Ar n -Impose a size limit of +Limit the size of the stack area to .Ar n -kibibytes on the size of the stack area. +kibibytes. .It Fl T Ar n Impose a time limit of .Ar n -real seconds to be used by each process. +real seconds +.Pq Dq humantime +to be used by each process. .It Fl t Ar n Impose a time limit of .Ar n @@ -5113,9 +5426,12 @@ Impose a limit of .Ar n kibibytes on the amount of virtual memory (address space) used. .It Fl w Ar n -Impose a limit of +Limit the amount of swap space used to at most .Ar n -kibibytes on the amount of swap space used. +kibibytes. +.It Fl x Ar n +Set the maximum number of file locks to +.Ar n . .El .Pp As far as @@ -5127,6 +5443,7 @@ is concerned, a block is 512 bytes. .Op Fl S .Op Ar mask .Xc +.Pq regular Display or set the file permission creation mask or umask (see .Xr umask 2 ) . If the @@ -5150,6 +5467,7 @@ and is equivalent (on most systems) to the octal mask .Op Fl adt .Op Ar name ... .Xc +.Pq regular The aliases for the given names are removed. If the .Fl a @@ -5166,31 +5484,27 @@ directory aliases, respectively. .Op Fl fv .Ar parameter ... .Xc +.Pq keeps assignments , special Unset the named parameters -.Po -.Fl v , -the default -.Pc +.Pq Fl v , No the default or functions .Pq Fl f . With .Ar parameter Ns \&[*] , -attributes are kept, only values are unset. -.Pp -The exit status is non-zero if any of the parameters have the read-only -attribute set, zero otherwise. +attributes are retained, only values are unset. +The exit status is non-zero if any of the parameters are read-only, +zero otherwise (not portable). .Pp .It Ic wait Op Ar job ... +.Pq regular Wait for the specified job(s) to finish. The exit status of .Ic wait is that of the last specified job; if the last job is killed by a signal, the -exit status is 128 + the number of the signal (see +exit status is 128 + the signal number (see .Ic kill Fl l Ar exit-status -above); if the last specified job can't be found (because it never existed or -had already finished), the exit status of -.Ic wait -is 127. +above); if the last specified job cannot be found (because it never existed +or had already finished), the exit status is 127. See .Sx Job control below for the format of @@ -5215,20 +5529,44 @@ If job monitoring is enabled, the completion status of jobs is printed .Op Fl pv .Op Ar name ... .Xc +.Pq regular Without the .Fl v option, it is the same as .Ic command Fl v , -except aliases are not printed as alias command. +except aliases are printed as their definition only. With the .Fl v -option, it is exactly the same as +option, it is exactly identical to .Ic command Fl V . -In either case, the +In either case, with the .Fl p -option differs: the search path is not affected in -.Ic whence , -but the search is restricted to the path. +option the search is restricted to the (current) +.Ev PATH . +.Pp +.It Xo Ic which +.Op Fl a +.Op Ar name ... +.Xc +.Pq Li dot.mkshrc No function +Without +.Fl a , +behaves like +.Ic whence Fl p +(does a +.Ev PATH +search for each +.Ar name +printing the resulting pathname if found); with +.Fl a , +matches in all +.Ev PATH +components are printed, i.e. the search is not stopped after a match. +If no +.Ar name +was matched, the exit status is 2; if every name was matched, it is zero, +otherwise it is 1. +No diagnostics are produced on failure to match. .El .Ss Job control Job control refers to the shell's ability to monitor and control jobs which @@ -5323,9 +5661,9 @@ The job exited. .Ar number is the exit status of the job which is omitted if the status is zero. .It Running -The job has neither stopped nor exited (note that running does not necessarily -mean consuming CPU time \*(en -the process could be blocked waiting for some event). +The job has neither stopped nor exited (note that running does not +necessarily mean consuming CPU time\*(EMthe process could be blocked +waiting for some event). .It Stopped Op Ar signal The job was stopped by the indicated .Ar signal @@ -5560,7 +5898,7 @@ an .Op Ar n (if the command can be prefixed with a count); and any keys the command is bound to by default, written using caret notation -e.g. the ASCII ESC character is written as \*(ha[. +e.g. the ASCII Esc character is written as \*(ha[. These control sequences are not case sensitive. A count prefix for a command is entered using the sequence .Pf \*(ha[ Ns Ar n , @@ -5660,7 +5998,7 @@ If only one completion is possible, match as in the .Ic complete command above. -Note that \*(haI is usually generated by the TAB (tabulator) key. +Note that \*(haI is usually generated by the Tab (tabulator) key. .It Xo delete\-char\-backward: .Op Ar n .No ERASE Pq \*(haH , @@ -5833,6 +6171,10 @@ third-last, etc.) command is inserted at the cursor. Use of this editing command trashes the mark. .It quote: \*(ha\*(ha , \*(haV The following character is taken literally rather than as an editing command. +.It quote\-region: \*(ha[Q +Escapes the text between the mark and the cursor position +.Pq the entire line if no mark is set +into a shell command argument. .It redraw: \*(haL Reprints the last line of the prompt string and the current input line on a new line. @@ -5926,11 +6268,12 @@ replaces the inserted text string with the next previously killed text string. .Pp The tab completion escapes characters the same way as the following code: .Bd -literal -print \-nr \-\- "${x@/[\e"\-\e$\e&\-*:\-?[\e\e\e\`{\-\e}${IFS\-$\*(aq \et\en\*(aq}]/\e\e$KSH_MATCH}" +print \-nr \-\- "${x@/[\e"\-\e$\e&\-*:\-?[\e\e\e`\e{\-\e}${IFS\-$\*(aq \et\en\*(aq}]/\e\e$KSH_MATCH}" .Ed .Ss Vi editing mode .Em Note: -The vi command-line editing mode is orphaned, yet still functional. +The vi command-line editing mode has not yet been brought up to the +same quality and feature set as the emacs mode. It is 8-bit clean but specifically does not support UTF-8 or MBCS. .Pp The vi command-line editor in @@ -5944,9 +6287,9 @@ You start out in insert mode. .It There are file name and command completion commands: =, \e, *, \*(haX, \*(haE, \*(haF and, optionally, -.Aq tab +.Aq Tab and -.Aq esc . +.Aq Esc . .It The .Ic _ @@ -6010,9 +6353,9 @@ The next character typed is not treated specially (can be used to insert the characters being described here). .It \*(haX Command and file name expansion (see below). -.It Aq esc +.It Aq Esc Puts the editor in command mode (see below). -.It Aq tab +.It Aq Tab Optional file name and command completion (see .Ic \*(haF above), enabled with @@ -6089,7 +6432,7 @@ The actual command executed is Command or file name expansion is applied to the current big-word (with an appended .Ql * -if the word contains no file globbing characters) \*(en the big-word is replaced +if the word contains no file globbing characters)\*(EMthe big-word is replaced with the resulting words. If the current big-word is the first on the line or follows one of the characters @@ -6114,18 +6457,18 @@ word and the editor is in insert mode. .It Xo .Oo Ar n Oc Ns \e , .Oo Ar n Oc Ns \*(haF , -.Oo Ar n Oc Ns Aq tab , +.Oo Ar n Oc Ns Aq Tab , .No and -.Oo Ar n Oc Ns Aq esc +.Oo Ar n Oc Ns Aq Esc .Xc Command/file name completion. Replace the current big-word with the longest unique match obtained after performing command and file name expansion. -.Aq tab +.Aq Tab is only recognised if the .Ic vi\-tabcomplete option is set, while -.Aq esc +.Aq Esc is only recognised if the .Ic vi\-esccomplete option is set (see @@ -6147,7 +6490,7 @@ The restoring keypress is ignored. .It @ Ns Ar c Macro expansion. Execute the commands found in the alias -.Ar c . +.Li _ Ns Ar c . .El .Pp Intra-line movement commands: @@ -6334,7 +6677,12 @@ occurrence of the last search string; the direction of the search is the opposite of the last search. .It Ar ANSI-CurUp , PC-PgUp Take the characters from the beginning of the line to the current -cursor position as search string and do a backwards history search +cursor position as search string and do a history search, backwards, +for lines beginning with this string; keep the cursor position. +This works only in insert mode and keeps it enabled. +.It Ar ANSI-CurDown , PC-PgDn +Take the characters from the beginning of the line to the current +cursor position as search string and do a history search, forwards, for lines beginning with this string; keep the cursor position. This works only in insert mode and keeps it enabled. .El @@ -6349,7 +6697,7 @@ Append text times; goes into insert mode just after the current position. The append is only replicated if command mode is re-entered i.e.\& -.Aq esc +.Aq Esc is used. .It Xo .Oo Ar n Oc Ns A @@ -6365,7 +6713,7 @@ Insert text times; goes into insert mode at the current position. The insertion is only replicated if command mode is re-entered i.e.\& -.Aq esc +.Aq Esc is used. .It Xo .Oo Ar n Oc Ns I @@ -6494,7 +6842,7 @@ removed to the history and a new prompt to be printed. .It Pa \*(TI/.mkshrc User mkshrc profile (non-privileged interactive shells); see .Sx Startup files. -The location can be changed at compile time (for embedded systems); +The location can be changed at compile time (e.g. for embedded systems); AOSP Android builds use .Pa /system/etc/mkshrc . .It Pa \*(TI/.profile @@ -6507,7 +6855,7 @@ System profile (login shells); see .It Pa /etc/shells Shell database. .It Pa /etc/suid_profile -Suid profile (privileged shells); see +Privileged shells' profile (sugid); see .Sx Startup files. .El .Pp @@ -6545,6 +6893,12 @@ contains the system and suid profile. .Xr utf\-8 7 , .Xr mknod 8 .Pp +The FAQ at +.Pa http://www.mirbsd.org/mksh\-faq.htm +or in the +.Pa mksh.faq +file. +.Pp .Pa http://www.mirbsd.org/ksh\-chan.htm .Rs .%A Morris Bolsky @@ -6575,7 +6929,7 @@ contains the system and suid profile. .Re .Rs .%A "IEEE Inc." -.%T "\\*(tNIEEE\\*(sP Standard for Information Technology \*(en Portable Operating System Interface (POSIX)" +.%T "\\*(tNIEEE\\*(sP Standard for Information Technology\*(EMPortable Operating System Interface (POSIX)" .%V "Part 2: Shell and Utilities" .%D 1993 .%I "IEEE Press" @@ -6669,70 +7023,25 @@ The complete legalese is at: .\" .Sh CAVEATS .Nm mksh -provides a consistent 32-bit integer arithmetic implementation, both -signed and unsigned, with sign of the result of a remainder operation -and wraparound defined, even (defying POSIX) on 36-bit and 64-bit systems. -.Pp -.Nm mksh provides a consistent, clear interface normally. This may deviate from POSIX in historic or opinionated places. .Ic set Fl o Ic posix (see .Sx POSIX mode for details) -will cause the shell to behave more conformant. -.Pp -For the purpose of -.Tn POSIX , +will make the shell more conformant, but mind the FAQ (see +.Sx SEE ALSO ) , +especially regarding locales. .Nm mksh -supports only the -.Dq C -locale. -.Nm mksh Ns 's -.Ic utf8\-mode -.Em must -be disabled in POSIX mode, and it -only supports the BMP (Basic Multilingual Plane) of UCS and maps -raw octets into the U+EF80..U+EFFF wide character range; compare -.Sx Arithmetic expressions . -The following -.Tn POSIX -.Nm sh Ns -compatible -code toggles the -.Ic utf8\-mode -option dependent on the current -.Tn POSIX -locale for mksh to allow using the UTF-8 mode, within the constraints -outlined above, in code portable across various shell implementations: -.Bd -literal -offset indent -case ${KSH_VERSION:\-} in -*MIRBSD\ KSH*\*(Ba*LEGACY\ KSH*) - case ${LC_ALL:\-${LC_CTYPE:\-${LANG:\-}}} in - *[Uu][Tt][Ff]8*\*(Ba*[Uu][Tt][Ff]\-8*) set \-U ;; - *) set +U ;; - esac ;; -esac -.Ed -In near future, (UTF-8) locale tracking will be implemented though. +.Pq but not Nm lksh +provides a consistent 32-bit integer arithmetic implementation, both +signed and unsigned, with sign of the result of a remainder operation +and wraparound defined, even (defying POSIX) on 36-bit and 64-bit systems. .Pp -Using -.Ic set Fl o Ic pipefail -makes the following construct error out: -.Bd -literal -offset indent -set -e -for x in 1 2; do - false && echo $x -done \*(Ba cat -.Ed -This is because, while the -.Dq Li &&\& -ensures that the inner command's failure is not taken, it sets -the entire for..done loop's errorlevel, which is passed on by -.Fl o Ic pipefail . -Invert the inner command: -.Li true \*(Ba\*(Ba echo $x -.Pp -See also the FAQ below. +.Nm mksh +currently uses OPTU-16 internally, which is the same as UTF-8 and CESU-8 +with 0000..FFFD being valid codepoints; raw octets are mapped into the +PUA range EF80..EFFF, which is assigned by CSUR for this purpose. .Sh BUGS Suspending (using \*(haZ) pipelines like the one below will only suspend the currently running part of the pipeline; in this example, @@ -6756,7 +7065,7 @@ for the in-memory portion of the history is slow, should use .Xr memmove 3 . .Pp This document attempts to describe -.Nm mksh\ R57 +.Nm mksh\ R59 and up, .\" with vendor patches from insert-your-name-here, compiled without any options impacting functionality, such as @@ -6784,187 +7093,3 @@ IRC channel at .Pq Port 6697 SSL, 6667 unencrypted , or at: .Pa https://launchpad.net/mksh -.Sh FREQUENTLY ASKED QUESTIONS -This FAQ attempts to document some of the questions users of -.Nm -or readers of this manual page may encounter. -.Ss I'm an Android user, so what's mksh? -.Nm mksh -is a -.Ux -shell / command interpreter, similar to -.Nm COMMAND.COM -or -.Nm CMD.EXE , -which has been included with -.Tn Android Open Source Project -for a while now. -Basically, it's a program that runs in a terminal (console window), -takes user input and runs commands or scripts, which it can also -be asked to do by other programs, even in the background. -Any privilege pop-ups you might be encountering are thus not -.Nm mksh -issues but questions by some other program utilising it. -.Ss "I'm an OS/2 user, what do I need to know?" -Unlike the native command prompt, the current working directory is, -for security reasons common on Unix systems which the shell is designed for, -not in the search path at all; if you really need this, run the command -.Li PATH=.$PATHSEP$PATH -or add that to a suitable initialisation file. -.Pp -There are two different newline modes for mksh-os2: standard (Unix) mode, -in which only LF (0A hex) is supported as line separator, and "textmode", -which also accepts ASCII newlines (CR+LF), like most other tools on OS/2, -but creating an incompatibility with standard -.Nm . -If you compiled mksh from source, you will get the standard Unix mode unless -.Fl T -is added during compilation; you will most likely have gotten this shell -through komh's port on Hobbes, or from his OS/2 Factory on eComStation -Korea, which uses "textmode", though. -Most OS/2 users will want to use "textmode" unless they need absolute -compatibility with Unix -.Nm . -.Ss "How do I start mksh on a specific terminal?" -Normally: -.Dl mksh \-T/dev/tty2 -.Pp -However, if you want for it to return (e.g. for an embedded -system rescue shell), use this on your real console device instead: -.Dl mksh \-T!/dev/ttyACM0 -.Pp -.Nm -can also daemonise (send to the background): -.Dl mksh \-T\- \-c \*(aqexec cdio lock\*(aq -.Ss "POSIX says..." -Run the shell in POSIX mode (and possibly -.Nm lksh -instead of -.Nm mksh ) : -.Dl set \-o posix -.Ss "I forbid stat(2) in my SELinux policy, and some things do not work!" -Don't break Unix. -Read up on the GIGO principle. -Duh. -.Ss "My prompt from <some other shell> does not work!" -Contact us on the mailing list or on IRC, we'll convert it for you. -.Ss "Something is going wrong with my while...read loop" -Most likely, you've encountered the problem in which the shell runs -all parts of a pipeline as subshell. -The inner loop will be executed in a subshell and variable changes -cannot be propagated if run in a pipeline: -.Bd -literal -offset indent -bar \*(Ba baz \*(Ba while read foo; do ...; done -.Ed -.Pp -Note that -.Ic exit -in the inner loop will only exit the subshell and not the original shell. -Likewise, if the code is inside a function, -.Ic return -in the inner loop will only exit the subshell and won't terminate the function. -.Pp -Use co-processes instead: -.Bd -literal -offset indent -bar \*(Ba baz \*(Ba& -while read \-p foo; do ...; done -exec 3\*(Gt&p; exec 3\*(Gt&\- -.Ed -.Pp -If -.Ic read -is run in a loop such as -.Ic while read foo; do ...; done -then leading whitespace will be removed (IFS) and backslashes processed. -You might want to use -.Ic while IFS= read \-r foo; do ...; done -for pristine I/O. -Similarly, when using the -.Fl a -option, use of the -.Fl r -option might be prudent -.Pq Dq Li read \-raN\-1 arr \*(Ltfile ; -the same applies for NUL-terminated lines: -.Bd -literal -offset indent -find . \-type f \-print0 \*(Ba& \e - while IFS= read \-d \*(aq\*(aq \-pr filename; do - print \-r \-\- "found \*(Lt${filename#./}\*(Gt" -done -.Ed -.Pp -.Ss "What differences in function-local scopes are there?" -.Nm -has a different scope model from -.At -.Nm ksh , -which leads to subtle differences in semantics for identical builtins. -This can cause issues with a -.Ic nameref -to suddenly point to a local variable by accident. -.Pp -.Tn GNU -.Nm bash -allows unsetting local variables; in -.Nm , -doing so in a function allows back access to the global variable -(actually the one in the next scope up) with the same name. -The following code, when run before the function definitions, changes -the behaviour of -.Ic unset -to behave like other shells (the alias can be removed after the definitions): -.Bd -literal -offset indent -case ${KSH_VERSION:\-} in -*MIRBSD\ KSH*\*(Ba*LEGACY\ KSH*) - function unset_compat { - \e\ebuiltin typeset unset_compat_x - - for unset_compat_x in "$@"; do - eval "\e\e\e\ebuiltin unset $unset_compat_x[*]" - done - } - \e\ebuiltin alias unset=unset_compat - ;; -esac -.Ed -.Pp -When a local variable is created (e.g. using -.Ic local , -.Ic typeset , -.Ic integer , -.Ic \e\ebuiltin typeset ) -it does not, like in other shells, inherit the value from the global -(next scope up) variable with the same name; it is rather created -without any value (unset but defined). -.Ss "I get an error in this regex comparison" -Use extglobs instead of regexes: -.Dl "[[ foo =~ (foo\*(Babar).*baz ]] # becomes" -.Dl "[[ foo = *@(foo\*(Babar)*baz* ]] # instead" -.Ss "Are there any extensions to avoid?" -.Tn GNU -.Nm bash -supports -.Dq Li &\*(Gt -.Pq and Dq Li \*(Ba& -to redirect both stdout and stderr in one go, but this breaks POSIX -and Korn Shell syntax; use POSIX redirections instead: -.Dl "foo \*(Ba& bar \*(Ba& baz &\*(Gtlog # GNU bash" -.Dl "foo 2\*(Gt&1 \*(Ba bar 2\*(Gt&1 \*(Ba baz \*(Gtlog 2\*(Gt&1 # POSIX" -.Ss "\*(haL (Ctrl-L) does not clear the screen" -Use \*(ha[\*(haL (Escape+Ctrl-L) or rebind it: -.Dl bind \*(aq\*(haL=clear-screen\*(aq -.Ss "\*(haU (Ctrl-U) clears the entire line" -If it should only delete the line up to the cursor, use: -.Dl bind \-m \*(haU=\*(aq\*(ha[0\*(haK\*(aq -.Ss "Cursor Up behaves differently from zsh" -Some shells make Cursor Up search in the history only for -commands starting with what was already entered. -.Nm -separates the shortcuts: Cursor Up goes up one command -and PgUp searches the history as described above. -.Ss "My question is not answered here!" -Check -.Pa http://www.mirbsd.org/mksh\-faq.htm -which contains a collection of frequently asked questions about -.Nm -in general, for packagers, etc. while these above are in user scope. |