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