-.\" $MirOS: src/bin/mksh/mksh.1,v 1.451 2017/08/16 21:40:14 tg Exp $
+.\" $MirOS: src/bin/mksh/mksh.1,v 1.463 2019/03/01 16:17:31 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
+.\" 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017,
+.\" 2018, 2019
.\" mirabilos <m@mirbsd.org>
.\"
.\" Provided that these terms and disclaimer and all copyright notices
.\" with -mandoc, it might implement .Mx itself, but we want to
.\" use our own definition. And .Dd must come *first*, always.
.\"
-.Dd $Mdocdate: August 16 2017 $
+.Dd $Mdocdate: March 1 2019 $
.\"
.\" Check which macro package we use, and do other -mdoc setup.
.\"
. if \ 1\*[.T]\ 1utf8\ 1 .tr \[la]\*(Lt
. if \ 1\*[.T]\ 1utf8\ 1 .tr \[ra]\*(Gt
. ie d volume-ds-1 .ds tT gnu
+. el .ie d doc-volume-ds-1 .ds tT gnp
. el .ds tT bsd
.\}
.el .ds tT ucb
. nr curr-font \n[.f]
. nr curr-size \n[.ps]
. ds str-Mx \f[\n[curr-font]]\s[\n[curr-size]u]
-. ds str-Mx1 \*[Tn-font-size]\%MirOS\*[str-Mx]
+. ds str-Mx1 \*[Tn-font-size]\%MirBSD\*[str-Mx]
. if !\n[arg-limit] \
. if \n[.$] \{\
. ds macro-name Mx
. ds sP \s0
. ds tN \*[Tn-font-size]
.\}
+.el .ie "\*(tT"gnp" \{\
+. eo
+. de Mx
+. nr doc-curr-font \n[.f]
+. nr doc-curr-size \n[.ps]
+. ds doc-str-Mx \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]
+. ds doc-str-Mx1 \*[doc-Tn-font-size]\%MirBSD\*[doc-str-Mx]
+. if !\n[doc-arg-limit] \
+. if \n[.$] \{\
+. ds doc-macro-name Mx
+. doc-parse-args \$@
+. \}
+. if (\n[doc-arg-limit] > \n[doc-arg-ptr]) \{\
+. nr doc-arg-ptr +1
+. ie (\n[doc-type\n[doc-arg-ptr]] == 2) \
+. as doc-str-Mx1 \~\*[doc-arg\n[doc-arg-ptr]]
+. el \
+. nr doc-arg-ptr -1
+. \}
+. ds doc-arg\n[doc-arg-ptr] "\*[doc-str-Mx1]
+. nr doc-type\n[doc-arg-ptr] 2
+. ds doc-space\n[doc-arg-ptr] "\*[doc-space]
+. nr doc-num-args (\n[doc-arg-limit] - \n[doc-arg-ptr])
+. nr doc-arg-limit \n[doc-arg-ptr]
+. if \n[doc-num-args] \
+. doc-parse-space-vector
+. doc-print-recursive
+..
+. ec
+. ds sP \s0
+. ds tN \*[doc-Tn-font-size]
+.\}
.el \{\
. de Mx
. nr cF \\n(.f
. nr cZ \\n(.s
. ds aa \&\f\\n(cF\s\\n(cZ
. if \\n(aC==0 \{\
-. ie \\n(.$==0 \&MirOS\\*(aa
+. ie \\n(.$==0 \&MirBSD\\*(aa
. el .aV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
. \}
. if \\n(aC>\\n(aP \{\
. nr aP \\n(aP+1
. ie \\n(C\\n(aP==2 \{\
-. as b1 \&MirOS\ #\&\\*(A\\n(aP\\*(aa
+. as b1 \&MirBSD\ #\&\\*(A\\n(aP\\*(aa
. ie \\n(aC>\\n(aP \{\
. nr aP \\n(aP+1
. nR
. el .aZ
. \}
. el \{\
-. as b1 \&MirOS\\*(aa
+. as b1 \&MirBSD\\*(aa
. nR
. \}
. \}
.Dq Li \eu#### ,
.Dq #
means a hexadecimal digit, of which there may be none up to four or eight;
-these escapes translate a Unicode codepoint to UTF-8.
+these escapes translate a Universal Coded Character Set codepoint to UTF-8.
Furthermore,
.Dq Li \eE
and
greedily eat up as many hexadecimal digits
.Dq #
as they can and terminate with the first non-hexadecimal digit;
-these translate a Unicode codepoint to UTF-8.
+these translate a Universal Coded Character Set codepoint to UTF-8.
The sequence
.Dq Li \ec# ,
where
where
.Ar name
is a parameter name.
+Substitutions of an an array in scalar context, i.e. without an
+.Ar expr
+in the latter form mentioned above, expand the element with the key
+.Dq 0 .
Substitution of all array elements with
.Pf ${ Ns Ar name Ns \&[*]}
and
.Ar word
is not needed, it is not evaluated.
.Pp
-The following forms of parameter substitution can also be used (if
-.Ar name
-is an array, the element with the key
-.Dq 0
-will be substituted in scalar context):
+The following forms of parameter substitution can also be used:
.Pp
.Bl -tag -width Ds -compact
.It Pf ${# Ns Ar name Ns \&}
in any search path other than the empty path.
.It Ev COLUMNS
Set to the number of columns on the terminal or window.
-Always set, defaults to 80, unless the
-value as reported by
+If never unset and not imported, always set dynamically;
+unless the value as reported by
.Xr stty 1
-is non-zero and sane enough (minimum is 12x3); similar for
+is non-zero and sane enough (minimum is 12x3), defaults to 80; similar for
.Ev LINES .
This parameter is used by the interactive line editing modes and by the
.Ic select ,
executed.
.It Ev LINES
Set to the number of lines on the terminal or window.
-Always set, defaults to 24.
+Defaults to 24; always set, unless imported or unset.
See
.Ev COLUMNS .
.It Ev OLDPWD
As a special
.Nm mksh
extension, numbers to the base of one are treated as either (8-bit
-transparent) ASCII or Unicode codepoints, depending on the shell's
+transparent) ASCII or Universal Coded Character Set codepoints,
+depending on the shell's
.Ic utf8\-mode
flag (current setting).
The
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 Unicode mode, raw octets are mapped into the range EF80..EFFF as in
+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
The
.Dq export
attribute of functions is currently not used.
-In the original Korn shell,
-exported functions are visible to shell scripts that are executed.
.Pp
Since functions are executed in the current shell environment, parameter
assignments made inside functions are visible after the function completes.
(time spent running in kernel mode).
Times are reported to standard error; the format of the output is:
.Pp
-.Dl "0m0.00s real 0m0.00s user 0m0.00s system"
+.Dl "0m0.03s real 0m0.02s user 0m0.01s system"
.Pp
If the
.Fl p
option is given the output is slightly longer:
.Bd -literal -offset indent
-real 0.00
-user 0.00
-sys 0.00
+real 0.03
+user 0.02
+sys 0.01
.Ed
.Pp
It is an error to specify the
and by processes that the shell started which have exited.
The format of the output is:
.Bd -literal -offset indent
-0m0.00s 0m0.00s
-0m0.00s 0m0.00s
+0m0.01s 0m0.00s
+0m0.04s 0m0.02s
.Ed
.Pp
.It Ic trap Ar n Op Ar signal ...
.Fl i
option which meant upper case letters would never be used for bases greater
than 10.
-See the
+See
.Fl U
-option.)
+above.)
.Pp
For functions,
.Fl u
above for the implications of this.
.It Fl x
Export attribute.
-Parameters (or functions) are placed in the environment of
-any executed commands.
-Exported functions are not yet implemented.
+Parameters are placed in the environment of any executed commands.
+Functions cannot be exported for security reasons
+.Pq Dq shellshock .
.It Fl Z Ns Op Ar n
Zero fill attribute.
If not combined with
this is the same as
.Fl R ,
except zero padding is used instead of space padding.
-For integers, the number instead of the base is padded.
+For integers, the number is padded, not the base.
.El
.Pp
If any of the
.Ic set Fl o Ic monitor ) ,
as it is for interactive shells, the processes of a job are placed in their
own process group.
-Foreground jobs can be stopped by typing the suspend
-character from the terminal (normally \*(haZ), jobs can be restarted in either the
-foreground or background using the
+Foreground jobs can be stopped by typing the suspend character from
+the terminal (normally \*(haZ); jobs can be restarted in either the
+foreground or background using the commands
.Ic fg
and
-.Ic bg
-commands, and the state of the terminal is saved or restored when a foreground
-job is stopped or restarted, respectively.
+.Ic bg .
.Pp
Note that only commands that create processes (e.g. asynchronous commands,
subshell commands and non-built-in, non-function commands) can be stopped;
is immediately made to exit the shell, the running jobs are sent a
.Dv SIGHUP
signal and the shell exits.
+.Ss Terminal state
+The state of the controlling terminal can be modified by a command
+executed in the foreground, whether or not job control is enabled, but
+the modified terminal state is only kept past the job's lifetime and used
+for later command invocations if the command exits successfully (i.e.\&
+with an exit status of 0).
+When such a job is momentarily stopped or restarted, the terminal state
+is saved and restored, respectively, but it will not be kept afterwards.
+In interactive mode, when line editing is enabled, the terminal state is
+saved before being reconfigured by the shell for the line editor, then
+restored before running a command.
.Ss POSIX mode
Entering
.Ic set Fl o Ic posix
.Ic utf8\-mode
.Em must
be disabled in POSIX mode, and it
-only supports the Unicode BMP (Basic Multilingual Plane) and maps
+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
esac ;;
esac
.Ed
-In near future, (Unicode) locale tracking will be implemented though.
+In near future, (UTF-8) locale tracking will be implemented though.
+.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.
.Sh BUGS
.Xr memmove 3 .
.Pp
This document attempts to describe
-.Nm mksh\ R56
+.Nm mksh\ R57
and up,
.\" with vendor patches from insert-your-name-here,
compiled without any options impacting functionality, such as
.Pp
Please report bugs in
.Nm
-to the
+to the public development mailing list at
.Aq Mt miros\-mksh@mirbsd.org
-mailing list
-or in the
+(please note the EU-DSGVO/GDPR notice on
+.Pa http://www.mirbsd.org/rss.htm#lists
+and in the SMTP banner!) or in the
.Li \&#\&!/bin/mksh
.Pq or Li \&#ksh
IRC channel at
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"