-.\" $MirOS: src/bin/mksh/mksh.1,v 1.275 2011/10/07 19:51:29 tg Exp $
-.\" $OpenBSD: ksh.1,v 1.141 2011/09/03 22:59:08 jmc Exp $
+.\" $MirOS: src/bin/mksh/mksh.1,v 1.305 2013/02/19 18:45:20 tg Exp $
+.\" $OpenBSD: ksh.1,v 1.145 2013/01/17 21:20:25 jmc Exp $
.\"-
.\" Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-.\" 2010, 2011
+.\" 2010, 2011, 2012, 2013
.\" Thorsten Glaser <tg@mirbsd.org>
.\"
.\" Provided that these terms and disclaimer and all copyright notices
.\" * ~ 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
+.\" * <>| are problematic, so redefine and use \*(Lt\*(Gt\*(Ba
+.\" Also make sure to use \& especially with two-letter words.
.\" The section after the "doc" macropackage has been loaded contains
.\" additional code to convene between the UCB mdoc macropackage (and
.\" its variant as BSD mdoc in groff) and the GNU mdoc macropackage.
.\" with -mandoc, it might implement .Mx itself, but we want to
.\" use our own definition. And .Dd must come *first*, always.
.\"
-.Dd $Mdocdate: October 7 2011 $
+.Dd $Mdocdate: February 19 2013 $
.\"
-.\" Check which macro package we use
+.\" Check which macro package we use, and do other -mdoc setup.
.\"
.ie \n(.g \{\
+. 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 .ds tT bsd
.\}
.Nm
.Bk -words
.Op Fl +abCefhiklmnprUuvXx
-.Op Fl T Ar /dev/ttyCn | \-
+.Op Fl T Ar /dev/ttyCn \*(Ba \-
.Op Fl +o Ar option
.Oo
.Fl c Ar string \*(Ba
Its command language is a superset of the
.Xr sh C
shell language and largely compatible to the original Korn shell.
-.Pp
+.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 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.
.Pp
.Bd -literal -offset indent
$ bar=foobar; baz=\*(aqf*r\*(aq
$ [[ $bar = $baz ]]; echo $?
-$ [[ $bar = "$baz" ]]; echo $?
+$ [[ $bar = \&"$baz" ]]; echo $?
.Ed
.Pp
Perhaps surprisingly, the first comparison succeeds,
The alias expansion process stops when a word that is not an alias is found,
when a quoted word is found, or when an alias word that is currently being
expanded is found.
+Aliases are specifically an interactive feature: while they do happen
+to work in scripts and on the command line in some cases, aliases are
+expanded during lexing, so their use must be in a separate command tree
+from their definition; otherwise, the alias will not be found.
+Noticeably, command lists (separated by semicolon, in command substitutions
+also by newline) may be one same parse tree.
.Pp
The following command aliases are defined automatically by the shell:
.Bd -literal -offset indent
command substitutions take the form
.Pf $( Ns Ar command Ns \&)
or (deprecated)
-.Pf \` Ns Ar command Ns \` ;
+.Pf \` Ns Ar command Ns \`
+or (executed in the current environment)
+.Pf ${\ \& Ar command Ns \&;}
+and strip trailing newlines;
and arithmetic substitutions take the form
.Pf $(( Ns Ar expression Ns )) .
+Parsing the current-environment command substitution requires a space,
+tab or newline after the opening brace and that the closing brace be
+recognised as a keyword (i.e. is preceded by a newline or semicolon).
+They are also called funsubs (function substitutions) and behave like
+functions in that
+.Ic local
+and
+.Ic return
+work, and in that
+.Ic exit
+terminates the parent shell.
.Pp
If a substitution appears outside of double quotes, the results of the
substitution are generally subject to word or field splitting according to
command which is run in a subshell.
For
.Pf $( Ns Ar command Ns \&)
+and
+.Pf ${\ \& Ar command Ns \&;}
substitutions, normal quoting rules are used when
.Ar command
is parsed; however, for the deprecated
it is anchored at the beginning of the value; if it begins with
.Ql % ,
it is anchored at the end.
+Patterns that are empty or consist only of wildcards are invalid.
A single
.Ql /
replaces the first occurence of the search
.Ar pattern
is replaced by the empty string, i.e. deleted.
Cannot be applied to a vector.
-Inefficiently implemented.
+Inefficiently implemented, may be slow.
.Pp
.Sm off
.It Xo
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 @#}
+.It Xo
+.Pf ${ Ar name
+.Pf @# Ns Oo Ar seed Oc Ns }
+.Xc
The internal hash of the expansion of
-.Ar name .
-At the moment, this is NZAT (a never-zero 32-bit hash based on
+.Ar name ,
+with an optional (defaulting to zero)
+.Op Ar seed .
+At the moment, this is NZAAT (a 32-bit hash based on
Bob Jenkins' one-at-a-time hash), but this is not set.
This is the hash the shell uses internally for its associative arrays.
+.Pp
+.It Pf ${ Ns Ar name Ns @Q}
+A quoted expression safe for re-entry, whose value is the value of the
+.Ar name
+parameter, is substituted.
.El
.Pp
Note that
environment of the new process to the path of the executed command.
In interactive use, this parameter is also set in the parent shell to the last
word of the previous command.
+.It Ev BASHPID
+The PID of the shell or subshell.
.It Ev CDPATH
Search path for the
.Ic cd
Always set, defaults to 80, unless the
value as reported by
.Xr stty 1
-is non-zero and sane enough; similar for
+is non-zero and sane enough (minimum is 12x3); similar for
.Ev LINES .
This parameter is used by the interactive line editing modes, and by the
.Ic select ,
and
.Ic kill \-l
commands to format information columns.
+Importing from the environment or unsetting this parameter removes the
+binding to the actual terminal size in favour of the provided value.
.It Ev ENV
If this parameter is found to be set after any profile files are executed, the
expanded value is used as a shell startup file.
.Nm ksh .
.It Ev HISTSIZE
The number of commands normally stored for history.
-The default is 500.
+The default is 2047.
.It Ev HOME
The default directory for the
.Ic cd
.It Ev LINES
Set to the number of lines on the terminal or window.
Always set, defaults to 24.
+See
+.Ev COLUMNS .
+.It Ev EPOCHREALTIME
+Time since the epoch, as returned by
+.Xr gettimeofday 2 ,
+formatted as decimal
+.Va tv_sec
+followed by a dot
+.Pq Sq .\&
+and
+.Va tv_usec
+padded to exactly six decimal digits.
.It Ev OLDPWD
The previous working directory.
Unset if
PS1="$x$(print \e\er)$x$(tput smso)$x\e$PWD$x$(tput rmso)$x\*(Gt "
.Ed
.Pp
-Due to pressure from David G. Korn,
+Due to a strong suggestion from David G. Korn,
.Nm
now also supports the following form:
.Bd -literal -offset indent
matches all strings (think about it).
.El
.Pp
+Note that complicated globbing, especially with alternatives,
+is slow; using separate comparisons may (or may not) be faster.
+.Pp
Note that
.Nm mksh
.Po and Nm pdksh Pc
( )
.Ed
.Pp
-Integer constants and expressions are calculated using the
-.Vt mksh_ari_t
-.Po if signed Pc
-or
-.Vt mksh_uari_t
-.Po if unsigned Pc
-type, and are limited to 32 bits.
-Overflows wrap silently.
+Integer constants and expressions are calculated using an exactly 32-bit
+wide, signed or unsigned, type with silent wraparound on integer overflow.
Integer constants may be specified with arbitrary bases using the notation
.Ar base Ns # Ns Ar number ,
where
is a decimal integer specifying the base, and
.Ar number
is a number in the specified base.
-Additionally,
-integers may be prefixed with
-.Sq 0X
-or
+Additionally, base-16 integers may be specified by prefixing them with
.Sq 0x
-(specifying base 16), similar to
-.At
-.Nm ksh ,
-or
-.Sq 0
-(base 8), as an
-.Nm
-extension, in all forms of arithmetic expressions,
-except as numeric arguments to the
+.Pq case-insensitive
+in all forms of arithmetic expressions, except as numeric arguments to the
.Ic test
-command.
+built-in command.
+It is discouraged to prefix numbers with a sole zero
+.Pq Sq 0 ,
+because some shells may interpret them as base-8 integers.
As a special
.Nm mksh
extension, numbers to the base of one are treated as either (8-bit
.Dq 1#x
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
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
Note that
.At
.Nm ksh93
-uses static scoping (one global scope, one local scope per function), whereas
+uses static scoping (one global scope, one local scope per function)
+and allows local variables only on Korn style functions, whereas
.Nm mksh
uses dynamic scoping (nested scopes of varying locality).
Note that special parameters (e.g.\&
over Korn-style functions.
.El
.Pp
-In the future, the following differences will also be added:
+In the future, the following differences may also be added:
.Bl -bullet
.It
A separate trap/signal environment will be used during the execution of
.Pp
.Ic \&[ , chdir , bind , cat ,
.Ic echo , let , mknod , print ,
-.Ic printf , pwd , realpath , rename ,
-.Ic sleep , test , ulimit , whence
+.Ic pwd , realpath , rename , sleep ,
+.Ic test , ulimit , whence
.Pp
In the future, the additional
.Nm
.Em Warning:
this utility is not portable; use the Korn shell builtin
.Ic print
-or the much slower POSIX utility
-.Ic printf
instead.
.Pp
Prints its arguments (separated by spaces) followed by a newline, to the
Exported parameters are passed in the environment to executed commands.
If values are specified, the named parameters are also assigned.
.Pp
-If no parameters are specified, the names of all parameters with the export
-attribute are printed one per line, unless the
-.Fl p
-option is used, in which case
+If no parameters are specified, all parameters with the export attribute
+set are printed one per line; either their names, or, if a
+.Ql \-
+with no option letter is specified, name=value pairs, or, with
+.Fl p ,
.Ic export
-commands defining all exported parameters, including their values, are printed.
+commands suitable for re-entry.
.Pp
.It Ic false
A command that exits with a non-zero status.
and
.Fl s
is identical: re-execute the selected command without invoking an editor.
-This command is usually accessed with the predefined
+This command is usually accessed with the predefined:
.Ic alias r=\*(aqfc \-e \-\*(aq
-or by prefixing an interactive mode input line with
-.Sq \&!
-.Pq wbx extension .
.Pp
.It Ic fg Op Ar job ...
Resume the specified job(s) in the foreground.
(character type device),
or
.Cm p
-(named pipe).
+.Pq named pipe , Tn FIFO .
The file created may be modified according to its
.Ar mode
(via the
.Pp
.It Ic printf Ar format Op Ar arguments ...
Formatted output.
-Approximately the same as the utility
-.Ic printf ,
-except that it uses the same
+Approximately the same as the
+.Xr printf 1 ,
+utility, except it uses the same
.Sx Backslash expansion
-and I/O code as the rest of
+and I/O code and does hot handle floating point as the rest of
.Nm mksh .
This is not normally part of
.Nm mksh ;
however, distributors may have added this as builtin as a speed hack.
+Do not use in new code.
.Pp
.It Ic pwd Op Fl LP
Print the present working directory.
.Pp
.It Xo
.Ic read
-.Op Fl A | Fl a
+.Op Fl A \*(Ba Fl a
.Op Fl d Ar x
.Oo Fl N Ar z \*(Ba
.Fl n Ar z Oc
.Bd -literal -offset indent
find . \-type f \-print0 \*(Ba \e
while IFS= read \-d \*(aq\*(aq \-r filename; do
- print \-r \-\- "found <${filename#./}>"
+ print \-r \-\- "found \*(Lt${filename#./}\*(Gt"
done
.Ed
.Pp
.Ql xtrace .
.It Fl p Ar file
.Ar file
-is a named pipe.
+is a named pipe
+.Pq Tn FIFO .
.It Fl r Ar file
.Ar file
exists and is readable.
x=1; [ "x" \-eq 1 ] evaluates to true
.Ed
.Pp
-Note that some special rules are applied (courtesy of POSIX)
-if the number of
-arguments to
+Note that some special rules are applied (courtesy of
+.Px
+) if the number of arguments to
.Ic test
-or
+or inside the brackets
.Ic \&[ ... \&]
is less than five: if leading
.Ql \&!
-arguments can be stripped such that only one argument remains then a string
-length test is performed (again, even if the argument is a unary operator); if
-leading
-.Ql \&!
-arguments can be stripped such that three arguments remain and the second
-argument is a binary operator, then the binary operation is performed (even
-if the first argument is a unary operator, including an unstripped
-.Ql \&! ) .
+arguments can be stripped such that only one to three arguments remain,
+then the lowered comparison is executed; (thanks to XSI) parentheses
+.Ic \e( ... \e)
+lower four- and three-argument forms to two- and one-argument forms,
+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 .
.Pp
.Sy Note :
A common mistake is to use
or, to avoid pattern matching (see
.Ic \&[[
above):
-.Dq if \&[[ $foo = "$bar" \&]]
+.Dq if \&[[ $foo = \&"$bar" \&]]
+.Pp
+The
+.Ic \&[[ ... ]]
+construct is not only more secure to use but also often faster.
.Pp
.It Xo
.Ic time
is used inside a function, any parameters specified are localised.
This is not done by the otherwise identical
.Ic global .
+.Em Note :
+This means that
+.Nm No 's Ic global
+command is
+.Em not
+equivalent to other programming languages' as it does not allow a
+function called from another function to access a parameter at truly
+global scope, but only prevents putting an accessed one into local scope.
.Pp
When
.Fl f
.Xr cat 1 ,
.Xr ed 1 ,
.Xr getopt 1 ,
-.Xr printf 1 ,
.Xr sed 1 ,
.Xr sh 1 ,
.Xr stty 1 ,
.Xr mknod 8
.Pp
.Pa http://docsrv.sco.com:507/en/man/html.C/sh.C.html
+.Pp
+.Pa https://www.mirbsd.org/ksh\-chan.htm
.Rs
.%A Morris Bolsky
.%B "The KornShell Command and Programming Language"
.Ed
.Pp
This document attempts to describe
-.Nm mksh\ R40+CVS
+.Nm mksh\ R43
and up,
compiled without any options impacting functionality, such as
.Dv MKSH_SMALL ,
+when not called as
+.Pa /bin/sh
+which, on some systems only, enables
+.Ic set \-o sh
+automatically (whose behaviour differs across targets),
for an operating environment supporting all of its advanced needs.
Please report bugs in
.Nm
to the
.Mx
mailing list at
-.Aq miros\-discuss@mirbsd.org
+.Aq miros\-mksh@mirbsd.org
or in the
.Li \&#\&!/bin/mksh
.Pq or Li \&#ksh
IRC channel at
-.Pa irc.freenode.net:6667 .
+.Pa irc.freenode.net
+.Pq Port 6697 SSL, 6667 unencrypted ,
+or at:
+.Pa https://launchpad.net/mksh