src/lksh.1

   1 .\" $MirOS: src/bin/mksh/lksh.1,v 1.10 2015/04/12 22:32:12 tg Exp $
   2 .\"-
   3 .\" Copyright (c) 2008, 2009, 2010, 2012, 2013, 2015
   4 .\"     Thorsten “mirabilos” Glaser <tg@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 \& especially with two-letter words.
  31 .\" The section after the "doc" macropackage has been loaded contains
  32 .\" additional code to convene between the UCB mdoc macropackage (and
  33 .\" its variant as BSD mdoc in groff) and the GNU mdoc macropackage.
  34 .\"
  35 .ie \n(.g \{\
  36 .       if \ 1\*[.T]\ 1ascii\ 1 .tr \-\N'45'
  37 .       if \ 1\*[.T]\ 1latin1\ 1 .tr \-\N'45'
  38 .       if \ 1\*[.T]\ 1utf8\ 1 .tr \-\N'45'
  39 .       ds <= \[<=]
  40 .       ds >= \[>=]
  41 .       ds Rq \[rq]
  42 .       ds Lq \[lq]
  43 .       ds sL \(aq
  44 .       ds sR \(aq
  45 .       if \ 1\*[.T]\ 1utf8\ 1 .ds sL `
  46 .       if \ 1\*[.T]\ 1ps\ 1 .ds sL `
  47 .       if \ 1\*[.T]\ 1utf8\ 1 .ds sR '
  48 .       if \ 1\*[.T]\ 1ps\ 1 .ds sR '
  49 .       ds aq \(aq
  50 .       ds TI \(ti
  51 .       ds ha \(ha
  52 .       ds en \(en
  53 .\}
  54 .el \{\
  55 .       ds aq '
  56 .       ds TI ~
  57 .       ds ha ^
  58 .       ds en \(em
  59 .\}
  60 .\"
  61 .\" Implement .Dd with the Mdocdate RCS keyword
  62 .\"
  63 .rn Dd xD
  64 .de Dd
  65 .ie \a\\$1\a$Mdocdate:\a \{\
  66 .       xD \\$2 \\$3, \\$4
  67 .\}
  68 .el .xD \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8
  69 ..
  70 .\"
  71 .\" .Dd must come before definition of .Mx, because when called
  72 .\" with -mandoc, it might implement .Mx itself, but we want to
  73 .\" use our own definition. And .Dd must come *first*, always.
  74 .\"
  75 .Dd $Mdocdate: April 12 2015 $
  76 .\"
  77 .\" Check which macro package we use, and do other -mdoc setup.
  78 .\"
  79 .ie \n(.g \{\
  80 .       if \ 1\*[.T]\ 1utf8\ 1 .tr \[la]\*(Lt
  81 .       if \ 1\*[.T]\ 1utf8\ 1 .tr \[ra]\*(Gt
  82 .       ie d volume-ds-1 .ds tT gnu
  83 .       el .ds tT bsd
  84 .\}
  85 .el .ds tT ucb
  86 .\"
  87 .\" Implement .Mx (MirBSD)
  88 .\"
  89 .ie "\*(tT"gnu" \{\
  90 .       eo
  91 .       de Mx
  92 .       nr curr-font \n[.f]
  93 .       nr curr-size \n[.ps]
  94 .       ds str-Mx \f[\n[curr-font]]\s[\n[curr-size]u]
  95 .       ds str-Mx1 \*[Tn-font-size]\%MirOS\*[str-Mx]
  96 .       if !\n[arg-limit] \
  97 .       if \n[.$] \{\
  98 .       ds macro-name Mx
  99 .       parse-args \$@
 100 .       \}
 101 .       if (\n[arg-limit] > \n[arg-ptr]) \{\
 102 .       nr arg-ptr +1
 103 .       ie (\n[type\n[arg-ptr]] == 2) \
 104 .       as str-Mx1 \~\*[arg\n[arg-ptr]]
 105 .       el \
 106 .       nr arg-ptr -1
 107 .       \}
 108 .       ds arg\n[arg-ptr] "\*[str-Mx1]
 109 .       nr type\n[arg-ptr] 2
 110 .       ds space\n[arg-ptr] "\*[space]
 111 .       nr num-args (\n[arg-limit] - \n[arg-ptr])
 112 .       nr arg-limit \n[arg-ptr]
 113 .       if \n[num-args] \
 114 .       parse-space-vector
 115 .       print-recursive
 116 ..
 117 .       ec
 118 .       ds sP \s0
 119 .       ds tN \*[Tn-font-size]
 120 .\}
 121 .el \{\
 122 .       de Mx
 123 .       nr cF \\n(.f
 124 .       nr cZ \\n(.s
 125 .       ds aa \&\f\\n(cF\s\\n(cZ
 126 .       if \\n(aC==0 \{\
 127 .               ie \\n(.$==0 \&MirOS\\*(aa
 128 .               el .aV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
 129 .       \}
 130 .       if \\n(aC>\\n(aP \{\
 131 .               nr aP \\n(aP+1
 132 .               ie \\n(C\\n(aP==2 \{\
 133 .                       as b1 \&MirOS\ #\&\\*(A\\n(aP\\*(aa
 134 .                       ie \\n(aC>\\n(aP \{\
 135 .                               nr aP \\n(aP+1
 136 .                               nR
 137 .                       \}
 138 .                       el .aZ
 139 .               \}
 140 .               el \{\
 141 .                       as b1 \&MirOS\\*(aa
 142 .                       nR
 143 .               \}
 144 .       \}
 145 ..
 146 .\}
 147 .\"-
 148 .Dt LKSH 1
 149 .Os MirBSD
 150 .Sh NAME
 151 .Nm lksh
 152 .Nd Legacy Korn shell built on mksh
 153 .Sh SYNOPSIS
 154 .Nm
 155 .Bk -words
 156 .Op Fl +abCefhiklmnprUuvXx
 157 .Op Fl +o Ar opt
 158 .Oo
 159 .Fl c Ar string \*(Ba
 160 .Fl s \*(Ba
 161 .Ar file
 162 .Op Ar args ...
 163 .Oc
 164 .Ek
 165 .Sh DESCRIPTION
 166 .Nm
 167 is a command interpreter intended exclusively for running legacy
 168 shell scripts.
 169 It is built on
 170 .Nm mksh ;
 171 refer to its manual page for details on the scripting language.
 172 It is recommended to port scripts to
 173 .Nm mksh
 174 instead of relying on legacy or idiotic POSIX-mandated behaviour,
 175 since the MirBSD Korn Shell scripting language is much more consistent.
 176 .Sh LEGACY MODE
 177 .Nm
 178 currently has the following differences from
 179 .Nm mksh :
 180 .Bl -bullet
 181 .It
 182 There is no explicit support for interactive use,
 183 nor any command line editing or history code.
 184 Hence,
 185 .Nm
 186 is not suitable as a user's login shell, either; use
 187 .Nm mksh
 188 instead.
 189 .It
 190 The
 191 .Ev KSH_VERSION
 192 string identifies
 193 .Nm
 194 as
 195 .Dq LEGACY KSH
 196 instead of
 197 .Dq MIRBSD KSH .
 198 Note that the rest of the version string is identical between
 199 the two shell flavours, and the behaviour and differences can
 200 change between versions; see the accompanying manual page
 201 .Xr mksh 1
 202 for the versions this document applies to.
 203 .It
 204 .Nm
 205 only offers the traditional ten file descriptors to scripts.
 206 .It
 207 .Nm
 208 uses
 209 .Tn POSIX
 210 arithmetics, which has quite a few implications:
 211 The data type for arithmetics is the host ISO C
 212 .Vt long
 213 data type.
 214 Signed integer wraparound is Undefined Behaviour.
 215 The sign of the result of a modulo operation with at least one
 216 negative operand is unspecified.
 217 Shift operations on negative numbers are unspecified.
 218 Division of the largest negative number by \-1 is Undefined Behaviour.
 219 The compiler is permitted to delete all data and crash the system
 220 if Undefined Behaviour occurs.
 221 .It
 222 The rotation arithmetic operators are not available.
 223 .It
 224 The shift arithmetic operators take all bits of the second operand into
 225 account; if they exceed permitted precision, the result is unspecified.
 226 .It
 227 The
 228 .Tn GNU
 229 .Nm bash
 230 extension &\*(Gt to redirect stdout and stderr in one go is not parsed.
 231 .It
 232 The
 233 .Nm mksh
 234 command line option
 235 .Fl T
 236 is not available.
 237 .It
 238 Unless
 239 .Ic set -o posix
 240 is active,
 241 .Nm
 242 always uses traditional mode for constructs like:
 243 .Bd -literal -offset indent
 244 $ set -- $(getopt ab:c "$@")
 245 $ echo $?
 246 .Ed
 247 .Pp
 248 POSIX mandates this to show 0, but traditional mode
 249 passes through the errorlevel from the
 250 .Xr getopt 1
 251 command.
 252 .It
 253 Unlike
 254 .At
 255 .Nm ksh ,
 256 .Nm mksh
 257 in
 258 .Fl o Ic posix
 259 or
 260 .Fl o Ic sh
 261 mode and
 262 .Nm lksh
 263 do not keep file descriptors \*(Gt 2 private from sub-processes.
 264 .It
 265 .Nm lksh
 266 undefines an alias when a
 267 .Tn POSIX
 268 function with the same name is defined,
 269 to make that function immediately callable.
 270 In
 271 .Nm mksh ,
 272 aliases have precedence; the name must be quoted or
 273 .Ic unalias Ns ed
 274 to access it.
 275 .It
 276 Functions defined with the
 277 .Ic function
 278 reserved word share the shell options
 279 .Pq Ic set -o
 280 instead of locally scoping them.
 281 .El
 282 .Sh SEE ALSO
 283 .Xr mksh 1
 284 .Pp
 285 .Pa https://www.mirbsd.org/mksh.htm
 286 .Pp
 287 .Pa https://www.mirbsd.org/ksh\-chan.htm
 288 .Sh CAVEATS
 289 To use
 290 .Nm
 291 as
 292 .Pa /bin/sh ,
 293 compilation to enable
 294 .Ic set -o posix
 295 by default is highly recommended for better standards compliance.
 296 .Pp
 297 .Nm
 298 tries to make a cross between a legacy bourne/posix compatibl-ish
 299 shell and a legacy pdksh-alike but
 300 .Dq legacy
 301 is not exactly specified.
 302 .Pp
 303 The
 304 .Ic set
 305 built-in command does not have all options one would expect
 306 from a full-blown
 307 .Nm mksh
 308 or
 309 .Nm pdksh .
 310 .Pp
 311 Talk to the
 312 .Mx
 313 development team using the mailing list at
 314 .Aq miros\-mksh@mirbsd.org
 315 or the
 316 .Li \&#\&!/bin/mksh
 317 .Pq or Li \&#ksh
 318 IRC channel at
 319 .Pa irc.freenode.net
 320 .Pq Port 6697 SSL, 6667 unencrypted
 321 if you need any further quirks or assistance,
 322 and consider migrating your legacy scripts to work with
 323 .Nm mksh
 324 instead of requiring
 325 .Nm .