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