xref: /illumos-gate/usr/src/contrib/ast/src/cmd/ksh93/README (revision b30d1939)
1da2e3ebdSchinThis directory, and its subdirectories contain the source code
2da2e3ebdSchinfor ksh-93; the language described in the second addition of
3da2e3ebdSchinthe book, "The KornShell Command and Programming Language," by
4da2e3ebdSchinMorris Bolsky and David Korn which is published by Prentice Hall.
5da2e3ebdSchinksh-93 has been compiled and run on several machines with several
6da2e3ebdSchinoperating systems.  The end of this file contains a partial list of
7da2e3ebdSchinoperating systems and machines that ksh-93 has been known to run on.
8da2e3ebdSchin
9da2e3ebdSchinThe layout of files for ksh-93 has changed somewhat since ksh-88,
10da2e3ebdSchinthe last major release.  Most of the source code for ksh remains in
11da2e3ebdSchinthe sh directory.  However, the shell editing and history routines
12da2e3ebdSchinare in the edit sub-directory.  The code for shell built-ins is
13da2e3ebdSchinin the bltins directory.  The data directory contains read-only
14da2e3ebdSchindata tables and messages that are used by the shell.  The include
15da2e3ebdSchinfiles remain in the include directory and the shlib directory
16da2e3ebdSchinis gone.  The features directory replaces the older install
17da2e3ebdSchindirectory. The method for generating systems specific feature
18da2e3ebdSchininformation has changed substantially.
19da2e3ebdSchin
20da2e3ebdSchinThe Makefile file contains several compilation options that can be set
21da2e3ebdSchinbefore compiling ksh.  Options are of the form SHOPT_option and become
22da2e3ebdSchin#define inside the code.  These options are set to their recommended
23da2e3ebdSchinvalue and some of these may disappear as options in future releases.
24da2e3ebdSchinA value of 0, or no value  represents off, 1 represents on.
25da2e3ebdSchinNote that == is needed, not =, because these are nmake state variables
26da2e3ebdSchinand changing their value will cause all modules that could be affected
27da2e3ebdSchinby this change to be recompiled.
28da2e3ebdSchinThe options have the following defaults and meanings:
29da2e3ebdSchin    ACCT         off Shell accounting.
307c2fbfb3SApril Chin    ACCTFILE     off Enable per user accounting info.
317c2fbfb3SApril Chin    AUDIT	 off For auditing specific users
327c2fbfb3SApril Chin    AUDITFILE	 "/etc/ksh_audit"
33da2e3ebdSchin    APPEND       on  Allows var+=val string and array append.
34da2e3ebdSchin    BASH         off Bash compatibility mode.  It is not fully implemented
35da2e3ebdSchin                     and is experimental.
36da2e3ebdSchin    BRACEPAT     on  C-shell type abc{d,e}f style file generation
37da2e3ebdSchin    CMDLIB_BLTIN off Makes all commands in libcmd.a builtins.  The
38da2e3ebdSchin                     SH_CMDLIB_DIR nmake state variable can be used to
39da2e3ebdSchin		     specify a directory.
40da2e3ebdSchin    CMDLIB_DIR   off Sets CMDLIB_BLTIN=1 and provides a default value
41da2e3ebdSchin                     of "/opt/ast/bin" for SH_CMDLIB_DIR.
42da2e3ebdSchin    COMPOUND_ARRAY
43da2e3ebdSchin                 on  Allows all components of compound variables except the
44da2e3ebdSchin                     first to be any string by enclosing in [...].  It also
45da2e3ebdSchin                     allows components other than the last to be arrays.
46da2e3ebdSchin                     This is experimental and only partially complete.
47da2e3ebdSchin    CRNL         off <cr><nl> treated as <nl> in shell grammar.
48da2e3ebdSchin    DYNAMIC      on  Dynamic loading of builtins. (Requires dlopen() interface.)
49da2e3ebdSchin    ECHOPRINT    off Make echo equivalent to print.
50da2e3ebdSchin    ESH          on  Compile with emacs command line editing.  The original
51da2e3ebdSchin                     emacs line editor code was provided by Mike Veach at IH.
52da2e3ebdSchin    FILESCAN     on  Experimental option that allows fast reading of files
53da2e3ebdSchin                     using while < file;do ...; done and allowing fields in
54da2e3ebdSchin                     each line to be accessed as positional parameters.
55da2e3ebdSchin    FS_3D        off For use with 3-D file system.  Enabled automatically for
56*b30d1939SAndy Fiddaman                     sytems with dynamic linking.
57da2e3ebdSchin    KIA          off Allow generation of shell cross reference database with -I.
58da2e3ebdSchin    MULTIBYTE    on  Multibyte character handling.  Requires mblen() and
59da2e3ebdSchin                     mbctowc().
60da2e3ebdSchin    NAMESPACE    on  Allows namespaces.  This is experimental, incomplete
61da2e3ebdSchin                     and undocumented.
62da2e3ebdSchin    OLDTERMIO    off Use either termios or termio at runtime.
63da2e3ebdSchin    OO           on  Experimental object oriented extension.  This option
64da2e3ebdSchin                     should disappear soon.
65da2e3ebdSchin    OPTIMIZE     on  Optimize loop invariants for with for and while loops.
66da2e3ebdSchin    P_SUID       off If set, all real uids, greater than or equal to this
67da2e3ebdSchin                     value will require the -p flag to run suid/sgid scripts.
68da2e3ebdSchin    PFSH         off Compile with support for profile shell.
69da2e3ebdSchin    RAWONLY      off Turn on if the vi line mode doesn't work right unless
70da2e3ebdSchin                     you do a set -o viraw.
71da2e3ebdSchin    SEVENBIT     off Strip the eigth bit from characters.
72da2e3ebdSchin    SPAWN        off Use spawn as combined fork/exec.  May improve speed on
73da2e3ebdSchin                     some systems.
747c2fbfb3SApril Chin    STATS	 on  Add .sh.stats compound variable.
75da2e3ebdSchin    SUID_EXEC    on  Execute /etc/suid_exec for setuid, setgid script.
76da2e3ebdSchin    TIMEOUT      off Set this to the number of seconds for timing out and
77da2e3ebdSchin                     exiting the shell when you don't enter a command.  If
78da2e3ebdSchin                     non-zero, TMOUT can not be set larger than this value.
797c2fbfb3SApril Chin    TYPEDEF	 on  Enable typeset type definitions.
80da2e3ebdSchin    VSH          on  Compile with vi command line editing.  The original vi
81da2e3ebdSchin                     line editor code was provided by Pat Sullivan at CB.
82da2e3ebdSchin
83da2e3ebdSchinThe following compile options are set automatically by the feature testing:
84da2e3ebdSchin    DEVFD   Set when /dev/fd is a directory that names open files.
85da2e3ebdSchin    SHELLMAGIC
86da2e3ebdSchin            Set on systems that recognize script beginning with #! specially.
87da2e3ebdSchin    VPIX    Set on systems the have /usr/bin/vpix program for running MS-DOS.
88da2e3ebdSchin
89da2e3ebdSchin
90da2e3ebdSchinIn most instances, you will generate ksh from a higher level directory
91da2e3ebdSchinwhich also generates libcmd and libast libraries on which ksh depends.
92da2e3ebdSchinHowever, it is possible to generate ksh, with by running make -f ksh.mk
93da2e3ebdSchinin this directory.  The ksh.mk file was generated from the nmake Makefile.
94da2e3ebdSchinIf you do not have make or nmake, but do have a Version 7 UNIX compatible
95da2e3ebdSchinshell, then you can run the script mamexec < Mamfile to build ksh.
96da2e3ebdSchinIf you have nmake, version 2.3 or later, you can use it without the -f ksh.mk.
97da2e3ebdSchinIn either case, ksh relies on libraries libast and libcmd which must be
98da2e3ebdSchinbuilt first.  The binary for ksh becomes the file named ./ksh which can
99da2e3ebdSchinbe copied to where ever you install it.
100da2e3ebdSchin
101da2e3ebdSchinIf you use old make or the Mamfile, and you system has dynamic shared
102da2e3ebdSchinlibraries, then you should define the variables mam_cc_static and
103da2e3ebdSchinmam_cc_dynanamic as the compiler options that request static linking
104da2e3ebdSchinand dynamic linking respectively.  This will decrease the number of
105da2e3ebdSchinshared libraries that ksh need and cut startup time substantially.
106da2e3ebdSchin
107da2e3ebdSchinThe makefile should also generate shcomp, a program that will precompile
108da2e3ebdSchina script.  ksh93 is able to recognize files in this format and process
109da2e3ebdSchinthem as scripts.  You can use shcomp to send out scripts when you
110da2e3ebdSchindon't want to give away the original script source.
111da2e3ebdSchin
112da2e3ebdSchinIt is advisable that you put the line PWD=$HOME;export PWD into the
113da2e3ebdSchin/etc/profile file to reduce initialization time for ksh.
114da2e3ebdSchin
115da2e3ebdSchinTo be able to run setuid/setgid shell scripts, or scripts without read
116da2e3ebdSchinpermission, the SUID_EXEC compile option must be on, and ksh must be installed
117da2e3ebdSchinin the /bin directory, the /usr/bin directory, the /usr/lbin directory,
118da2e3ebdSchinor the /usr/local/bin directory and the name must end in sh. The program
119da2e3ebdSchinsuid_exec must be installed in the /etc directory, must be owned by root,
120da2e3ebdSchinand must be a suid program.  If you must install ksh in some other directory
121da2e3ebdSchinand want to be able to run setuid/setgid and execute only scripts, then
122da2e3ebdSchinyou will have to change the source code file sh/suid_exec.c explicitly.
123da2e3ebdSchinIf you do not have ksh in one of these secure locations, /bin/sh will
124da2e3ebdSchinbe invoked with the -p options and will fail when you execute a setuid/setgid
125da2e3ebdSchinand/or execute only script.  Note, that ksh does not read the .profile
126da2e3ebdSchinor $ENV file when it the real and effective user/group id's are not
127da2e3ebdSchinequal.
128da2e3ebdSchin
129da2e3ebdSchinThe tests sub-directory contains a number of regression tests for ksh.
130da2e3ebdSchinTo run all these tests with the shell you just built, go to the tests
131da2e3ebdSchindirectory and run the command
1327c2fbfb3SApril Chin        SHELL=$dir/ksh $dir/ksh shtests
1337c2fbfb3SApril Chinwhere dir is the directory of the ksh you want to test.
134da2e3ebdSchin
135da2e3ebdSchinThe file PROMO.mm is an advertisement that extolls the virtues of ksh.
136da2e3ebdSchinThe file sh.1 contains the troff (man) description of this Shell.
137da2e3ebdSchinThe file nval.3 contains the troff (man) description of the name-value
138da2e3ebdSchinpair library that is needed for writing built-ins that need to
139da2e3ebdSchinaccess shell variables.
140da2e3ebdSchin
141da2e3ebdSchinThe file sh.memo contains a draft troff (mm) memo describing ksh.  The
142da2e3ebdSchinfile RELEASE88 contains the changes made for ksh88.  The file RELEASE93
143da2e3ebdSchincontains the changes made in this release since ksh-88.  The file
144da2e3ebdSchinRELEASE contains bug fixes made in this release since ksh-88.  The file
145da2e3ebdSchinCOMPATIBILITY contains a list of incompatibilities with ksh-88.  The
146da2e3ebdSchinfile bltins.mm is a draft troff (mm) memo describing how to write
147da2e3ebdSchinbuilt-in commands that can be loaded at run time.
148da2e3ebdSchin
149da2e3ebdSchinMost of the work for internationalization has been done with ksh93.
150da2e3ebdSchinThe file ksh.msg is a generated file that contains error messages
151da2e3ebdSchinthat need to be translated.  In addition, the function translate()
152da2e3ebdSchinin sh/init.c has to be completed to interface with the dictionary
153da2e3ebdSchinlookup.  The translate function takes two argument, the string
154da2e3ebdSchinthat is to be translated and a type which is
155da2e3ebdSchin    0 when a library string needs translation.
156da2e3ebdSchin    1 when one of the error messages in ksh.msg needs translation.
157da2e3ebdSchin    2 when a string in a script needs translation.  You use a $ in front
158da2e3ebdSchin      of a double quoted string in a script to indicate that it
159da2e3ebdSchin      needs translation.  The -D option for ksh builds the dictionary.
160da2e3ebdSchinThe translate routine needs to return the translated message.
161da2e3ebdSchinFor dictionaries that need to use a numeric key, it should be
162da2e3ebdSchinpossible to use the strhash() function to generate numbers to
163da2e3ebdSchingo along with each of the messages and to use this number both
164da2e3ebdSchinwhen generating the dictionary and when converting strings.
165da2e3ebdSchinIf you encounter error messages of type 1 that are not be translated via
166da2e3ebdSchinthis translate() function send mail to the address below.
167da2e3ebdSchin
168da2e3ebdSchinPlease report any problems or suggestions to:
169da2e3ebdSchin
170da2e3ebdSchindgk@research.att.com
171da2e3ebdSchin
172da2e3ebdSchin
173da2e3ebdSchinksh93 has been compiled and alpha tested on the following.  An asterisk
174da2e3ebdSchinsignifies that ksh has been installed as /bin/sh on this machine.
175da2e3ebdSchin
176da2e3ebdSchin*    Sun OS 4.1.[123] on sparc.
177da2e3ebdSchin     Sun OS 4.1.1 on sun.
178da2e3ebdSchin     Solaris 2.[1-9] on sparc.
179da2e3ebdSchin     Solaris 2.[4-8] on X86.
180da2e3ebdSchin     HP/UX 8 on HP-9000/730.
181da2e3ebdSchin     HP/UX 9 on HP-9000/730.
182da2e3ebdSchin     HP/UX 10 on HP-9000/857.
183da2e3ebdSchin     HP/UX 11 on pa-risc.
184da2e3ebdSchin     System V Release 3 on Counterpoint C19
185da2e3ebdSchin     System V Release  4 on AT&T Intel 486.
186da2e3ebdSchin     System V Release  4 on NCR 4850 Intel 486.
187da2e3ebdSchin     IRIX Release 4.0.? System V on SGI-MIPS.
188da2e3ebdSchin     IRIX Release 5.1 System V on SGI-MIPS.
189da2e3ebdSchin     IRIX Release 6.[1-5] System V on SGI-MIPS.
190da2e3ebdSchin     System V Release 3.2 on 3B2.
191da2e3ebdSchin     UTS 5.2.6 on Amdahl 3090,5990,580.
192da2e3ebdSchin     System V Release 3.2 on i386.
193da2e3ebdSchin     SMP_DC.OSx olivetti dcosx MIServer-S 2/128.
194da2e3ebdSchin     SMP_DC.OSx Pyramid dcosx MIServer-S 2/160 r3000.
195da2e3ebdSchin     4.3BSD on Vax 8650.
196da2e3ebdSchin     AIX release 2 on RS6000.
197da2e3ebdSchin     AIX 3.2 on RS6000.
198da2e3ebdSchin     Linux 1.X on Intel
199da2e3ebdSchin     Linux 2.X on Intel
200da2e3ebdSchin     Linux 2.X on Alpha
201da2e3ebdSchin     Linux 2.X on Alpha
202da2e3ebdSchin     Linux 2.X on OS/390
203da2e3ebdSchin     Linux 2.X on sparc
204da2e3ebdSchin     Linux 2.4 on intel itanium 64
205da2e3ebdSchin     Linux Slackware on sparc64
206da2e3ebdSchin*    Linux ARM on i-PAQ
207da2e3ebdSchin     OSF1 on DEC alpha.
208da2e3ebdSchin     OSF4 on DEC alpha.
209da2e3ebdSchin     UMIPS 4.52 on mips.
210da2e3ebdSchin     BSD-i [2-4] on X86.
211da2e3ebdSchin     OpenBSD on X86
212da2e3ebdSchin     NetBSD on X86
213da2e3ebdSchin     FreeBSD on X86
214da2e3ebdSchin     NeXT on Intel X86.
215da2e3ebdSchin     NeXT on HP.
216da2e3ebdSchin*    Windows NT using UWIN on X86
217da2e3ebdSchin*    Windows NT using UWIN on alpha
218da2e3ebdSchin     Windows NT using Cygwin on X86
219da2e3ebdSchin     Windows NT with NutCracker libraries.
220da2e3ebdSchin     Windows NT with Portage libraries.
221da2e3ebdSchin     Windows 3.1 using custom C library.
222da2e3ebdSchin     OpenEdition on MVS
223da2e3ebdSchin     Darwin OS X on PPC
224da2e3ebdSchin     MVS on OS 390
225da2e3ebdSchin     SCO Openserver 3.2 on X86
226da2e3ebdSchin     Unixware 7 on X86
227da2e3ebdSchin
228da2e3ebdSchinGood luck!!
229da2e3ebdSchin
230da2e3ebdSchinDavid Korn
231da2e3ebdSchindgk@research.att.com
232da2e3ebdSchin
233