src/lksh.1

   1 .\" $MirOS: src/bin/mksh/lksh.1,v 1.20 2016/11/11 23:31:35 tg Exp $
   2 .\"-
   3 .\" Copyright (c) 2008, 2009, 2010, 2012, 2013, 2015, 2016
   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: November 11 2016 $
  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 idiotic POSIX-mandated behaviour,
 177 since the MirBSD Korn Shell scripting language is much more consistent.
 178 .Pp
 179 Note that it's strongly recommended to invoke
 180 .Nm
 181 with at least the
 182 .Fl o Ic posix
 183 option, if not both that
 184 .Em and Fl o Ic sh ,
 185 to fully enjoy better compatibility to the
 186 .Tn POSIX
 187 standard (which is probably why you use
 188 .Nm
 189 over
 190 .Nm mksh
 191 in the first place) or legacy scripts, respectively.
 192 .Sh LEGACY MODE
 193 .Nm
 194 currently has the following differences from
 195 .Nm mksh :
 196 .Bl -bullet
 197 .It
 198 .\"XXX TODO: remove (some systems may wish to have lksh as ksh)
 199 There is no explicit support for interactive use,
 200 nor any command line editing or history code.
 201 Hence,
 202 .Nm
 203 is not suitable as a user's login shell, either; use
 204 .Nm mksh
 205 instead.
 206 .It
 207 The
 208 .Ev KSH_VERSION
 209 string identifies
 210 .Nm
 211 as
 212 .Dq Li LEGACY KSH
 213 instead of
 214 .Dq Li MIRBSD KSH .
 215 Note that the rest of the version string is identical between
 216 the two shell flavours, and the behaviour and differences can
 217 change between versions; see the accompanying manual page
 218 .Xr mksh 1
 219 for the versions this document applies to.
 220 .It
 221 .Nm
 222 uses
 223 .Tn POSIX
 224 arithmetic, which has quite a few implications:
 225 The data type for arithmetic operations is the host
 226 .Tn ISO
 227 C
 228 .Vt long
 229 data type.
 230 Signed integer wraparound is Undefined Behaviour; this means that...
 231 .Bd -literal -offset indent
 232 $ echo $((2147483647 + 1))
 233 .Ed
 234 .Pp
 235 \&... is permitted to, e.g. delete all files on your system
 236 (the figure differs for non-32-bit systems, the rule doesn't).
 237 The sign of the result of a modulo operation with at least one
 238 negative operand is unspecified.
 239 Shift operations on negative numbers are unspecified.
 240 Division of the largest negative number by \-1 is Undefined Behaviour.
 241 The compiler is permitted to delete all data and crash the system
 242 if Undefined Behaviour occurs (see above for an example).
 243 .It
 244 .\"XXX TODO: move this to FPOSIX
 245 The rotation arithmetic operators are not available.
 246 .It
 247 The shift arithmetic operators take all bits of the second operand into
 248 account; if they exceed permitted precision, the result is unspecified.
 249 .It
 250 .\"XXX TODO: move this to FPOSIX
 251 The
 252 .Tn GNU
 253 .Nm bash
 254 extension &\*(Gt to redirect stdout and stderr in one go is not parsed.
 255 .It
 256 .\"XXX TODO: drop along with allowing interactivity
 257 The
 258 .Nm mksh
 259 command line option
 260 .Fl T
 261 is not available.
 262 .It
 263 Unless
 264 .Ic set -o posix
 265 is active,
 266 .Nm
 267 always uses traditional mode for constructs like:
 268 .Bd -literal -offset indent
 269 $ set -- $(getopt ab:c "$@")
 270 $ echo $?
 271 .Ed
 272 .Pp
 273 POSIX mandates this to show 0, but traditional mode
 274 passes through the errorlevel from the
 275 .Xr getopt 1
 276 command.
 277 .It
 278 .\"XXX TODO: move to FPOSIX/FSH
 279 Unlike
 280 .At
 281 .Nm ksh ,
 282 .Nm mksh
 283 in
 284 .Fl o Ic posix
 285 or
 286 .Fl o Ic sh
 287 mode and
 288 .Nm lksh
 289 do not keep file descriptors \*(Gt 2 private from sub-processes.
 290 .It
 291 Functions defined with the
 292 .Ic function
 293 reserved word share the shell options
 294 .Pq Ic set -o
 295 instead of locally scoping them.
 296 .El
 297 .Sh SEE ALSO
 298 .Xr mksh 1
 299 .Pp
 300 .Pa https://www.mirbsd.org/mksh.htm
 301 .Pp
 302 .Pa https://www.mirbsd.org/ksh\-chan.htm
 303 .Sh CAVEATS
 304 The distinction between the shell variants
 305 .Pq Nm lksh / Nm mksh
 306 and shell flags
 307 .Pq Fl o Ic posix / Ic sh
 308 will be reworked for an upcoming release.
 309 .Pp
 310 To use
 311 .Nm
 312 as
 313 .Pa /bin/sh ,
 314 compilation to enable
 315 .Ic set -o posix
 316 by default if called as
 317 .Nm sh
 318 is highly recommended for better standards compliance.
 319 For better compatibility with legacy scripts, such as many
 320 .Tn Debian
 321 maintainer scripts, Upstart and SYSV init scripts, and other
 322 unfixed scripts, using the compile-time options for enabling
 323 .Em both
 324 .Ic set -o posix -o sh
 325 when the shell is run as
 326 .Nm sh
 327 is recommended.
 328 .Pp
 329 .Nm
 330 tries to make a cross between a legacy bourne/posix compatibl-ish
 331 shell and a legacy pdksh-alike but
 332 .Dq legacy
 333 is not exactly specified.
 334 .Pp
 335 The
 336 .Ic set
 337 built-in command does not currently have all options one would expect
 338 from a full-blown
 339 .Nm mksh
 340 or
 341 .Nm pdksh .
 342 .Pp
 343 Talk to the
 344 .Mx
 345 development team using the mailing list at
 346 .Aq miros\-mksh@mirbsd.org
 347 or the
 348 .Li \&#\&!/bin/mksh
 349 .Pq or Li \&#ksh
 350 IRC channel at
 351 .Pa irc.freenode.net
 352 .Pq Port 6697 SSL, 6667 unencrypted
 353 if you need any further quirks or assistance,
 354 and consider migrating your legacy scripts to work with
 355 .Nm mksh
 356 instead of requiring
 357 .Nm .