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