src/lksh.1

   1 .\" $MirOS: src/bin/mksh/lksh.1,v 1.23 2017/04/02 13:38:02 tg Exp $
   2 .\"-
   3 .\" Copyright (c) 2008, 2009, 2010, 2012, 2013, 2015, 2016, 2017
   4 .\"     mirabilos <m@mirbsd.org>
   5 .\"
   6 .\" Provided that these terms and disclaimer and all copyright notices
   7 .\" are retained or reproduced in an accompanying document, permission
   8 .\" is granted to deal in this work without restriction, including un‐
   9 .\" limited rights to use, publicly perform, distribute, sell, modify,
  10 .\" merge, give away, or sublicence.
  11 .\"
  12 .\" This work is provided “AS IS” and WITHOUT WARRANTY of any kind, to
  13 .\" the utmost extent permitted by applicable law, neither express nor
  14 .\" implied; without malicious intent or gross negligence. In no event
  15 .\" may a licensor, author or contributor be held liable for indirect,
  16 .\" direct, other damage, loss, or other issues arising in any way out
  17 .\" of dealing in the work, even if advised of the possibility of such
  18 .\" damage or existence of a defect, except proven that it results out
  19 .\" of said person’s immediate fault when using the work as intended.
  20 .\"-
  21 .\" Try to make GNU groff and AT&T nroff more compatible
  22 .\" * ` generates ‘ in gnroff, so use \`
  23 .\" * ' generates ’ in gnroff, \' generates ´, so use \*(aq
  24 .\" * - generates ‐ in gnroff, \- generates −, so .tr it to -
  25 .\"   thus use - for hyphens and \- for minus signs and option dashes
  26 .\" * ~ is size-reduced and placed atop in groff, so use \*(TI
  27 .\" * ^ is size-reduced and placed atop in groff, so use \*(ha
  28 .\" * \(en does not work in nroff, so use \*(en
  29 .\" * <>| are problematic, so redefine and use \*(Lt\*(Gt\*(Ba
  30 .\" Also make sure to use \& *before* a punctuation char that is to not
  31 .\" be interpreted as punctuation, and especially with two-letter words
  32 .\" but also (after) a period that does not end a sentence (“e.g.\&”).
  33 .\" The section after the "doc" macropackage has been loaded contains
  34 .\" additional code to convene between the UCB mdoc macropackage (and
  35 .\" its variant as BSD mdoc in groff) and the GNU mdoc macropackage.
  36 .\"
  37 .ie \n(.g \{\
  38 .       if \ 1\*[.T]\ 1ascii\ 1 .tr \-\N'45'
  39 .       if \ 1\*[.T]\ 1latin1\ 1 .tr \-\N'45'
  40 .       if \ 1\*[.T]\ 1utf8\ 1 .tr \-\N'45'
  41 .       ds <= \[<=]
  42 .       ds >= \[>=]
  43 .       ds Rq \[rq]
  44 .       ds Lq \[lq]
  45 .       ds sL \(aq
  46 .       ds sR \(aq
  47 .       if \ 1\*[.T]\ 1utf8\ 1 .ds sL `
  48 .       if \ 1\*[.T]\ 1ps\ 1 .ds sL `
  49 .       if \ 1\*[.T]\ 1utf8\ 1 .ds sR '
  50 .       if \ 1\*[.T]\ 1ps\ 1 .ds sR '
  51 .       ds aq \(aq
  52 .       ds TI \(ti
  53 .       ds ha \(ha
  54 .       ds en \(en
  55 .\}
  56 .el \{\
  57 .       ds aq '
  58 .       ds TI ~
  59 .       ds ha ^
  60 .       ds en \(em
  61 .\}
  62 .\"
  63 .\" Implement .Dd with the Mdocdate RCS keyword
  64 .\"
  65 .rn Dd xD
  66 .de Dd
  67 .ie \a\\$1\a$Mdocdate:\a \{\
  68 .       xD \\$2 \\$3, \\$4
  69 .\}
  70 .el .xD \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8
  71 ..
  72 .\"
  73 .\" .Dd must come before definition of .Mx, because when called
  74 .\" with -mandoc, it might implement .Mx itself, but we want to
  75 .\" use our own definition. And .Dd must come *first*, always.
  76 .\"
  77 .Dd $Mdocdate: April 2 2017 $
  78 .\"
  79 .\" Check which macro package we use, and do other -mdoc setup.
  80 .\"
  81 .ie \n(.g \{\
  82 .       if \ 1\*[.T]\ 1utf8\ 1 .tr \[la]\*(Lt
  83 .       if \ 1\*[.T]\ 1utf8\ 1 .tr \[ra]\*(Gt
  84 .       ie d volume-ds-1 .ds tT gnu
  85 .       el .ds tT bsd
  86 .\}
  87 .el .ds tT ucb
  88 .\"
  89 .\" Implement .Mx (MirBSD)
  90 .\"
  91 .ie "\*(tT"gnu" \{\
  92 .       eo
  93 .       de Mx
  94 .       nr curr-font \n[.f]
  95 .       nr curr-size \n[.ps]
  96 .       ds str-Mx \f[\n[curr-font]]\s[\n[curr-size]u]
  97 .       ds str-Mx1 \*[Tn-font-size]\%MirOS\*[str-Mx]
  98 .       if !\n[arg-limit] \
  99 .       if \n[.$] \{\
 100 .       ds macro-name Mx
 101 .       parse-args \$@
 102 .       \}
 103 .       if (\n[arg-limit] > \n[arg-ptr]) \{\
 104 .       nr arg-ptr +1
 105 .       ie (\n[type\n[arg-ptr]] == 2) \
 106 .       as str-Mx1 \~\*[arg\n[arg-ptr]]
 107 .       el \
 108 .       nr arg-ptr -1
 109 .       \}
 110 .       ds arg\n[arg-ptr] "\*[str-Mx1]
 111 .       nr type\n[arg-ptr] 2
 112 .       ds space\n[arg-ptr] "\*[space]
 113 .       nr num-args (\n[arg-limit] - \n[arg-ptr])
 114 .       nr arg-limit \n[arg-ptr]
 115 .       if \n[num-args] \
 116 .       parse-space-vector
 117 .       print-recursive
 118 ..
 119 .       ec
 120 .       ds sP \s0
 121 .       ds tN \*[Tn-font-size]
 122 .\}
 123 .el \{\
 124 .       de Mx
 125 .       nr cF \\n(.f
 126 .       nr cZ \\n(.s
 127 .       ds aa \&\f\\n(cF\s\\n(cZ
 128 .       if \\n(aC==0 \{\
 129 .               ie \\n(.$==0 \&MirOS\\*(aa
 130 .               el .aV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
 131 .       \}
 132 .       if \\n(aC>\\n(aP \{\
 133 .               nr aP \\n(aP+1
 134 .               ie \\n(C\\n(aP==2 \{\
 135 .                       as b1 \&MirOS\ #\&\\*(A\\n(aP\\*(aa
 136 .                       ie \\n(aC>\\n(aP \{\
 137 .                               nr aP \\n(aP+1
 138 .                               nR
 139 .                       \}
 140 .                       el .aZ
 141 .               \}
 142 .               el \{\
 143 .                       as b1 \&MirOS\\*(aa
 144 .                       nR
 145 .               \}
 146 .       \}
 147 ..
 148 .\}
 149 .\"-
 150 .Dt LKSH 1
 151 .Os MirBSD
 152 .Sh NAME
 153 .Nm lksh
 154 .Nd Legacy Korn shell built on mksh
 155 .Sh SYNOPSIS
 156 .Nm
 157 .Bk -words
 158 .Op Fl +abCefhiklmnprUuvXx
 159 .Op Fl +o Ar opt
 160 .Oo
 161 .Fl c Ar string \*(Ba
 162 .Fl s \*(Ba
 163 .Ar file
 164 .Op Ar args ...
 165 .Oc
 166 .Ek
 167 .Sh DESCRIPTION
 168 .Nm
 169 is a command interpreter intended exclusively for running legacy
 170 shell scripts.
 171 It is built on
 172 .Nm mksh ;
 173 refer to its manual page for details on the scripting language.
 174 It is recommended to port scripts to
 175 .Nm mksh
 176 instead of relying on legacy or objectionable POSIX-mandated behaviour,
 177 since the MirBSD Korn Shell scripting language is much more consistent.
 178 .Pp
 179 Do not use
 180 .Nm
 181 as an interactive or login shell; use
 182 .Nm mksh
 183 instead.
 184 .Pp
 185 Note that it's strongly recommended to invoke
 186 .Nm
 187 with
 188 .Fl o Ic posix
 189 to fully enjoy better compatibility to the
 190 .Tn POSIX
 191 standard (which is probably why you use
 192 .Nm
 193 over
 194 .Nm mksh
 195 in the first place);
 196 .Fl o Ic sh
 197 (possibly additionally to the above) may be needed for some legacy scripts.
 198 .Sh LEGACY MODE
 199 .Nm
 200 currently has the following differences from
 201 .Nm mksh :
 202 .Bl -bullet
 203 .It
 204 The
 205 .Ev KSH_VERSION
 206 string identifies
 207 .Nm
 208 as
 209 .Dq Li LEGACY KSH
 210 instead of
 211 .Dq Li MIRBSD KSH .
 212 Note that the rest of the version string is identical between
 213 the two shell flavours, and the behaviour and differences can
 214 change between versions; see the accompanying manual page
 215 .Xr mksh 1
 216 for the versions this document applies to.
 217 .It
 218 .Nm
 219 uses
 220 .Tn POSIX
 221 arithmetic, which has quite a few implications:
 222 The data type for arithmetic operations is the host
 223 .Tn ISO
 224 C
 225 .Vt long
 226 data type.
 227 Signed integer wraparound is Undefined Behaviour; this means that...
 228 .Bd -literal -offset indent
 229 $ echo $((2147483647 + 1))
 230 .Ed
 231 .Pp
 232 \&... is permitted to, e.g. delete all files on your system
 233 (the figure differs for non-32-bit systems, the rule doesn't).
 234 The sign of the result of a modulo operation with at least one
 235 negative operand is unspecified.
 236 Shift operations on negative numbers are unspecified.
 237 Division of the largest negative number by \-1 is Undefined Behaviour.
 238 The compiler is permitted to delete all data and crash the system
 239 if Undefined Behaviour occurs (see above for an example).
 240 .It
 241 The rotation arithmetic operators are not available.
 242 .It
 243 The shift arithmetic operators take all bits of the second operand into
 244 account; if they exceed permitted precision, the result is unspecified.
 245 .It
 246 Unless
 247 .Ic set -o posix
 248 is active,
 249 .Nm
 250 always uses traditional mode for constructs like:
 251 .Bd -literal -offset indent
 252 $ set -- $(getopt ab:c "$@")
 253 $ echo $?
 254 .Ed
 255 .Pp
 256 POSIX mandates this to show 0, but traditional mode
 257 passes through the errorlevel from the
 258 .Xr getopt 1
 259 command.
 260 .It
 261 Functions defined with the
 262 .Ic function
 263 reserved word share the shell options
 264 .Pq Ic set -o
 265 instead of locally scoping them.
 266 .El
 267 .Sh SEE ALSO
 268 .Xr mksh 1
 269 .Pp
 270 .Pa http://www.mirbsd.org/mksh.htm
 271 .Pp
 272 .Pa http://www.mirbsd.org/ksh\-chan.htm
 273 .Sh CAVEATS
 274 To use
 275 .Nm
 276 as
 277 .Pa /bin/sh ,
 278 compilation to enable
 279 .Ic set -o posix
 280 by default if called as
 281 .Nm sh
 282 .Pq adding Dv \-DMKSH_BINSHPOSIX to Dv CPPFLAGS
 283 is highly recommended for better standards compliance.
 284 .Pp
 285 For better compatibility with legacy scripts, such as many
 286 .Tn Debian
 287 maintainer scripts, Upstart and SYSV init scripts, and other
 288 unfixed scripts, also adding the
 289 .Dv \-DMKSH_BINSHREDUCED
 290 compile-time option to enable
 291 .Em both
 292 .Ic set -o posix -o sh
 293 when the shell is run as
 294 .Nm sh ,
 295 as well as integrating the optional disrecommended
 296 .Xr printf 1
 297 builtin, might be necessary.
 298 .Pp
 299 .Nm
 300 tries to make a cross between a legacy bourne/posix compatibl-ish
 301 shell and a legacy pdksh-alike but
 302 .Dq legacy
 303 is not exactly specified.
 304 .Pp
 305 Talk to the
 306 .Mx
 307 development team using the mailing list at
 308 .Aq miros\-mksh@mirbsd.org
 309 or the
 310 .Li \&#\&!/bin/mksh
 311 .Pq or Li \&#ksh
 312 IRC channel at
 313 .Pa irc.freenode.net
 314 .Pq Port 6697 SSL, 6667 unencrypted
 315 if you need any further quirks or assistance,
 316 and consider migrating your legacy scripts to work with
 317 .Nm mksh
 318 instead of requiring
 319 .Nm .