Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

OS-1592 Hasta la vista libshell docs

OS-1593 aw hacks no longer needed
  • Loading branch information...
commit d897495a4da857aefd6049f3055486feaf469b71 1 parent ff9ab63
@rmustacc rmustacc authored
Showing with 0 additions and 4,683 deletions.
  1. +0 −2  usr/src/Makefile.master
  2. +0 −1  usr/src/lib/libshell/Makefile
  3. +0 −91 usr/src/lib/libshell/Makefile.doc
  4. +0 −134 usr/src/lib/libshell/common/COMPATIBILITY
  5. +0 −170 usr/src/lib/libshell/common/DESIGN
  6. +0 −152 usr/src/lib/libshell/common/OBSOLETE
  7. +0 −232 usr/src/lib/libshell/common/README
  8. +0 −2,204 usr/src/lib/libshell/common/RELEASE
  9. +0 −182 usr/src/lib/libshell/common/TYPES
  10. BIN  usr/src/lib/libshell/misc/images/callouts/1.png
  11. BIN  usr/src/lib/libshell/misc/images/callouts/10.png
  12. BIN  usr/src/lib/libshell/misc/images/callouts/2.png
  13. BIN  usr/src/lib/libshell/misc/images/callouts/3.png
  14. BIN  usr/src/lib/libshell/misc/images/callouts/4.png
  15. BIN  usr/src/lib/libshell/misc/images/callouts/5.png
  16. BIN  usr/src/lib/libshell/misc/images/callouts/6.png
  17. BIN  usr/src/lib/libshell/misc/images/callouts/7.png
  18. BIN  usr/src/lib/libshell/misc/images/callouts/8.png
  19. BIN  usr/src/lib/libshell/misc/images/callouts/9.png
  20. BIN  usr/src/lib/libshell/misc/images/tag_bourne.png
  21. BIN  usr/src/lib/libshell/misc/images/tag_i18n.png
  22. BIN  usr/src/lib/libshell/misc/images/tag_ksh.png
  23. BIN  usr/src/lib/libshell/misc/images/tag_ksh88.png
  24. BIN  usr/src/lib/libshell/misc/images/tag_ksh93.png
  25. BIN  usr/src/lib/libshell/misc/images/tag_l10n.png
  26. BIN  usr/src/lib/libshell/misc/images/tag_perf.png
  27. +0 −1,464 usr/src/lib/libshell/misc/shell_styleguide.docbook
  28. +0 −28 usr/src/pkg/manifests/SUNWcs.mf
  29. +0 −23 usr/src/tools/aw/aw.c
View
2  usr/src/Makefile.master
@@ -172,8 +172,6 @@ $(__GNUC4)GCC_ROOT= /opt/gcc/4.4.4
GCCLIBDIR= $(GCC_ROOT)/lib
GCCLIBDIR64= $(GCC_ROOT)/lib/$(MACH64)
-DOCBOOK_XSL_ROOT= /usr/share/sgml/docbook/xsl-stylesheets
-
RPCGEN= /usr/bin/rpcgen
STABS= $(ONBLD_TOOLS)/bin/$(MACH)/stabs
ELFEXTRACT= $(ONBLD_TOOLS)/bin/$(MACH)/elfextract
View
1  usr/src/lib/libshell/Makefile
@@ -64,6 +64,5 @@ $(SUBDIRS): FRC
FRC:
include Makefile.demo
-include Makefile.doc
include ../Makefile.targ
View
91 usr/src/lib/libshell/Makefile.doc
@@ -1,91 +0,0 @@
-#
-# CDDL HEADER START
-#
-# The contents of this file are subject to the terms of the
-# Common Development and Distribution License (the "License").
-# You may not use this file except in compliance with the License.
-#
-# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
-# or http://www.opensolaris.org/os/licensing.
-# See the License for the specific language governing permissions
-# and limitations under the License.
-#
-# When distributing Covered Code, include this CDDL HEADER in each
-# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
-# If applicable, add the following below this CDDL HEADER, with the
-# fields enclosed by brackets "[]" replaced with your own identifying
-# information: Portions Copyright [yyyy] [name of copyright owner]
-#
-# CDDL HEADER END
-#
-
-#
-# Copyright 2009 Sun Microsystems, Inc. All rights reserved.
-# Use is subject to license terms.
-#
-
-ROOTDOCDIRBASE= $(ROOT)/usr/share/doc/ksh
-
-DOCFILES= \
- RELEASE \
- README \
- TYPES \
- DESIGN \
- COMPATIBILITY \
- OBSOLETE \
- shell_styleguide.docbook \
- shell_styleguide.html \
- images/tag_bourne.png \
- images/tag_i18n.png \
- images/tag_ksh88.png \
- images/tag_ksh93.png \
- images/tag_ksh.png \
- images/tag_l10n.png \
- images/tag_perf.png \
- images/callouts/1.png \
- images/callouts/2.png \
- images/callouts/3.png \
- images/callouts/4.png \
- images/callouts/5.png \
- images/callouts/6.png \
- images/callouts/7.png \
- images/callouts/8.png \
- images/callouts/9.png \
- images/callouts/10.png
-
-# Documentation rules
-$(ROOTDOCDIRBASE)/%: common/%
- $(INS.file)
-
-$(ROOTDOCDIRBASE)/%: misc/%
- $(INS.file)
-
-ROOTDOCDIRS= \
- $(ROOTDOCDIRBASE) .WAIT \
- $(ROOTDOCDIRBASE)/images .WAIT \
- $(ROOTDOCDIRBASE)/images/callouts
-
-$(ROOTDOCDIRBASE)/%.html: misc/%.docbook
- /usr/bin/xsltproc \
- --nonet \
- --stringparam generate.section.toc.level 0 \
- --stringparam toc.max.depth 3 \
- --stringparam toc.section.depth 12 \
- --xinclude \
- -o "$(@F)" \
- $(DOCBOOK_XSL_ROOT)/html/docbook.xsl \
- "$<" >xsltproc.log 2>&1
- $(INS) -s -m $(FILEMODE) -f "$(@D)" "$(@F)"
- $(RM) "$(@F)"
-
-# Generic documentation rules
-DOCFILESRCDIR= common
-ROOTDOCFILES= $(DOCFILES:%=$(ROOTDOCDIRBASE)/%)
-$(ROOTDOCDIRS) := OWNER = root
-$(ROOTDOCDIRS) := GROUP = bin
-$(ROOTDOCDIRS) := DIRMODE = 755
-
-$(ROOTDOCDIRS):
- $(INS.dir)
-
-install: $(ROOTDOCDIRS) .WAIT $(ROOTDOCFILES)
View
134 usr/src/lib/libshell/common/COMPATIBILITY
@@ -1,134 +0,0 @@
-
- KSH-93 VS. KSH-88
-
-
-The following is a list of known incompatibilities between ksh-93 and ksh-88.
-I have not include cases that are clearly bugs in ksh-88. I also have
-omitted features that are completely upward compatible.
-
-1. Functions, defined with name() with ksh-93 are compatible with
- the POSIX standard, not with ksh-88. No local variables are
- permitted, and there is no separate scope. Functions defined
- with the function name syntax, maintain compatibility.
- This also affects function traces.
-
-2. ! is now a reserved word. As a result, any command by that
- name will no longer work with ksh-93.
-
-3. The -x attribute of alias and typeset -f is no longer
- effective and the ENV file is only read for interactive
- shells. You need to use FPATH to make function definitions
- visible to scripts.
-
-4. A built-in command named command has been added which is
- always found before the PATH search. Any script which uses
- this name as the name of a command (or function) will not
- be compatible.
-
-5. The output format for some built-ins has changed. In particular
- the output format for set, typeset and alias now have single
- quotes around values that have special characters. The output
- for trap without arguments has a format that can be used as input.
-
-6. With ksh-88, a dollar sign ($') followed by a single quote was
- interpreted literally. Now it is an ANSI-C string. You
- must quote the dollar sign to get the previous behavior.
- Also, a $ in front of a " indicates that the string needs
- to be translated for locales other than C or POSIX. The $
- is ignored in the C and POSIX locale.
-
-7. With ksh-88, tilde expansion did not take place inside ${...}.
- with ksh-93, ${foo-~} will cause tilde expansion if foo is
- not set. You need to escape the ~ for the previous behavior.
-
-8. Some changes in the tokenizing rules where made that might
- cause some scripts with previously ambiguous use of quoting
- to produce syntax errors.
-
-9. Programs that rely on specific exit values for the shell,
- (rather than 0 or non-zero) may not be compatible. The
- exit status for many shell failures has been changed.
-
-10. Built-ins in ksh-88 were always executed before looking for
- the command in the PATH variable. This is no longer true.
- Thus, with ksh-93, if you have the current directory first
- in your PATH, and you have a program named test in your
- directory, it will be executed when you type test; the
- built-in version will be run at the point /bin is found
- in your PATH.
-
-11. Some undocumented combinations of argument passing to ksh
- builtins no longer works since ksh-93 is getopts conforming
- with respect to its built-ins. For example, typeset -8i
- previously would work as a synonym for typeset -i8.
-
-12. Command substitution and arithmetic expansion are now performed
- on PS1, PS3, and ENV when they are expanded. Thus, ` and $(
- as part of the value of these variables must be preceded by a \
- to preserve their previous behavior.
-
-13. The ERRNO variable has been dropped.
-
-14. If the file name following a redirection symbol contain pattern
- characters they will only be expanded for interactive shells.
-
-15. The arguments to a dot script will be restored when it completes.
-
-16. The list of tracked aliases is not displayed with alias unless
- the -t option is specified.
-
-17. The POSIX standard requires that test "$arg" have exit status
- of 0, if and only if $arg is null. However, since this breaks
- programs that use test -t, ksh93 treats an explicit test -t
- as if the user had entered test -t 1.
-
-18. The ^T directive of emacs mode has been changed to work the
- way it does in gnu-emacs.
-
-19. ksh-88 allowed unbalanced parenthes within ${name op val} whereas
- ksh-93 does not. Thus, ${foo-(} needs to be written as ${foo-\(}
- which works with both versions.
-
-20. kill -l in ksh-93 lists only the signal names, not their numerical
- values.
-
-21. Local variables defined by typeset are statically scoped in
- ksh93. In ksh88 they were dynamically scoped although this
- behavior was never documented.
-
-22. The value of the variable given to getopts is set to ? when
- the end-of-options is reached to conform to the POSIX standard.
-
-23. Since the POSIX standard requires that octal constants be
- recongnized, doing arithmetic on typeset -Z variables can
- yield different results that with ksh88. Most of these
- differences were eliminated in ksh93o.
-
-24. Starting after ksh93l, If you run ksh name, where name does
- not contain a /, the current directory will be searched
- before doing a path search on name as required by the POSIX
- shell standard.
-
-25. In ksh93, cd - will output the directory that it changes
- to on standard output as required by X/Open. With ksh88,
- this only happened for interactive shells.
-
-26. As an undocumented feature of ksh-88, a leading 0 to an
- assignment of an integer variable caused that variable
- to be treated as unsigned. This behavior was removed
- starting in ksh93p.
-
-27. The getopts builtin in ksh93 requires that optstring contain
- a leading + to allow options to begin with a +.
-
-28. In emacs/gmacs mode, control-v will not display the version when
- the stty lnext character is set to control-v or is unset.
- The sequence escape control-v will display the shell version.
-
-29. In ksh88, DEBUG traps were executed. after each command. In ksh93
- DEBUG traps are exeucted before each command.
-
-30. In ksh88, a redirection to a file name given by an empty string was
- ignored. In ksh93, this is an error.
-I am interested in expanding this list so please let me know if you
-uncover any others.
View
170 usr/src/lib/libshell/common/DESIGN
@@ -1,170 +0,0 @@
-Here is an overview of the source code organization for ksh93.
-
-Directory layout:
-
- The directory include contains header files for ksh93.
- The files nval.h and shell.h are intended to be public
- headers and can be used to add runtime builtin command.
- The remainder are private.
-
- The directory data contains readonly data files for ksh93.
- The man pages for built-ins are in builtins.c rather
- than included as statics with the implementations in the
- bltins directory because some systems don't make static const
- data readonly and we want these to be shared by all running
- shells.
-
- The directory edit contains the code for command line
- editing and history.
-
- The fun directory contains some shell function such as
- pushd, popd, and dirs.
-
- The directory features contains files that are used to generate
- header files in the FEATURE directory. Most of these files
- are in a format that is processed by iffe.
-
- The directory bltins contains code for most of the built-in
- commands. Additional built-in commands are part of libcmd.
-
- The directory sh contains most of the code for ksh93.
-
- The directory tests contains a number of regression tests.
- In most cases, when a bug gets fixed, a test is added to
- one of these files. The regression tests can be run by
- going to this directory and running
- SHELL=shell_path shell_path shtests
- where shell_path is an absolute pathname for the shell to
- be tested.
-
- The top level directory contains the nmake Makefile, a README,
- and several documentation files. The RELEASE file contains
- the list of bug fixes and new features since the original
- ksh93 release. The file COMPATIBILITY is a list of all
- known incompatibilities with ksh88.
-
- The bash_pre_rc.sh is a startup script used when emulating
- bash if the shell is compiled with SHOPT_BASH and the shell
- is invoked as bash. The bash emulation is not complete.
-
-Include directory:
- 1. argnod.h contains the type definitions for command
- nodes, io nodes, argument nodes, and for positional
- parameters.a It defines the prototypes for
- all the positional parameters functions.
- 2. builtins.h contains prototypes for builtins as well
- as symbolic constants that refer to the name-pairs
- that are associated with some of the built-ins.
- It also contains prototypes for many of the strings.
- 3. defs.h is the catch all for all definitions that
- don't fit elsewhere and it includes several other
- headers. It defines a strucuture that contains ksh
- global data, sh, and a structure that contains per
- function data, sh.st.
- 4. edit.h contains definitions that are common to both
- vi and emacs edit modes.
- 5. env.h contains interfaces for creating and modifying
- environment variables.
- 6. fault.h contains prototypes for signal related
- functions and trap and fault handling.
- 7. fcin.h contains macro and function definitions for
- reading from a file or string.
- 8. history.h contains macros and functions definitions
- related to history file processing.
- 9. jobs.h contains the definitions relating to job
- processing and control.
- 10. lexstates.h contains the states associated with
- lexical processing.
- 11. name.h contains the internal definitions related
- to name-value pair processing.
- 12. national.h contains a few I18N definitions, mostly
- obsolete.
- 13. nval.h is the public interface to the name-value
- pair library that is documented with nval.3.
- 14. path.h contains the interface for pathname processing
- and pathname searching.
- 15. shell.h is the public interface for shell functions
- that are documented int shell.3.
- 16. shlex.h contains the lexical token definitions and
- interfaces for lexical analysis.
- 17. shnodes.h contains the definition of the structures
- for each of the parse nodes and flags for the attributes.
- 18. shtable.h contains some interfaces and functions for
- table lookup.
- 19. streval.h contains the interface to the arithmetic
- functions.
- 20. terminal.h is a header file that includes the appropriate
- terminal include.
- 21. test.h contains the definitions for the test and [[...]]
- commands.
- 22. timeout.h contains the define constant for the maximum
- shell timeout.
- 23. ulimit.h includes the appropriate resource header.
- 24. variables.h contains symbolic constants for the built-in
- shell variables.
-
-sh directory:
- 1. args.c contains functions for parsing shell options
- and for processing positional parameters.
- 2. arith.c contains callback functions for the streval.c
- library and the interface to shell arithmetic.
- 3. array.c contains the code for indexed and associative
- arrays.
- 4. bash.h contains code used when compiling with SHOPT_BASH
- to add bash specific features such as shopt.
- 5. defs.c contains the data definitions for global symbols.
- 6. deparse.c contains code to generate shell script from
- a parse tree.
- 7. env.c contains code to add and delete environment variables
- to an environment list.
- 8. expand.c contains code for file name expansion and
- file name generation.
- 9. fault.c contains code for signal processing, trap
- handling and termination.
- 10. fcin.c contains code for reading and writing a character
- at a time from a file or string.
- 11. init.c contains initialization code and callbacks
- for get and set functions for built-in variables.
- 12. io.o contains code for redirections and managing file
- descriptors and file streams.
- 13. jobs.c contains the code for job management.
- 14. lex.c contains the code for the lexical analyzer.
- 15. macro.c contains code for the $ macro expansions, including
- here-documents.
- 16. main.c contains the calls to initialization, profile
- processing and the main evaluation loop as well as
- mail processing.
- 17. name.c contains the name-value pair routines that are
- built on the hash library in libast.
- 18. nvdisc.c contains code related to name-value pair disciplines.
- 19. nvtree.c contains code for compound variables and for
- walking the namespace.
- 20. nvtype.c contains most of the code related to types that
- are created with typeset -T.
- 21. parse.c contains the code for the shell parser.
- 22. path.c contains the code for pathname lookup and
- some path functions. It also contains the code
- that executes commands and scripts.
- 23. pmain.c is just a calls sh_main() so that all of the
- rest of the shell can be in a shared library.
- 24. shcomp.c contains the main program to the shell
- compiler. This program parses a script and creates
- a file that the shell can read containing the parse tree.
- 25. streval.c is an C arithmetic evaluator.
- 26. string.c contains some string related functions.
- 27. subshell.c contains the code to save and restore
- environments so that subshells can run without creating
- a new process.
- 28. suid_exec.c contains the program from running execute
- only and/or setuid/setgid scripts.
- 29. tdump.c contains the code to dump a parse tree into
- a file.
- 30. timers.c contains code for multiple event timeouts.
- 31. trestore contians the code for restoring the parse
- tree from the file created by tdump.
- 32. userinit.c contains a dummy userinit() function.
- This is now obsolete with the new version of sh_main().
- 33. waitevent.c contains the sh_waitnotify function so
- that builtins can handle processing events when the
- shell is waiting for input or for process completion.
- 34. xec.c is the main shell executuion loop.
View
152 usr/src/lib/libshell/common/OBSOLETE
@@ -1,152 +0,0 @@
-.sp 3
-.tl ''Ksh Features That Are Obsolete in Ksh93''
-.sp 2
-.AL 1
-.LI
-Using a pair of grave accents \^\fB\(ga\fR ... \fB\(ga\fR\^
-for command substition. Use \fB$(\fR ... \fB)\fR instead.
-.LI
-.B FCEDIT
-is an obsolete name for
-the default editor name for the
-.B hist
-command.
-.B FCEDIT
-is not used when
-.B HISTEDIT
-is set. Use
-.B HISTEDIT
-instead.
-.LI
-The newtest (\fB[[\fR ... \fB]]\fR) operator
-\fB\-a\fP \fIfile\fP
-is obsolete. Use
-\fB\-e\fP instead.
-.LI
-The newtest (\fB[[\fR ... \fB]]\fR) operator
-.BR = ,
-as used in
-\fIstring\fP \fB=\fP \fIpattern\fP
-is obsolete. Use
-\fB==\fP instead.
-.LI
-The following obsolete arithmetic comparisons are also permitted:
-.in +5
-.VL 20
-.LI "\fIexp1\fP \fB\-eq\fP \fIexp2\fP"
-True, if
-.I exp1
-is equal to
-.IR exp2 .
-.LI "\fIexp1\fP \fB\-ne\fP \fIexp2\fP"
-True, if
-.I exp1
-is not equal to
-.IR exp2 .
-.LI "\fIexp1\fP \fB\-lt\fP \fIexp2\fP"
-True, if
-.I exp1
-is less than
-.IR exp2 .
-.LI "\fIexp1\fP \fB\-gt\fP \fIexp2\fP"
-True, if
-.I exp1
-is greater than
-.IR exp2 .
-.LI "\fIexp1\fP \fB\-le\fP \fIexp2\fP"
-True, if
-.I exp1
-is less than or equal to
-.IR exp2 .
-.LI "\fIexp1\fP \fB\-ge\fP \fIexp2\fP"
-True, if
-.I exp1
-is greater than or equal to
-.IR exp2 .
-.LE \" End .VL
-.in -5
-.LI
-Using test -t or [ -t ] without specifying the file unit number.
-.LI
-The
-.B \-k
-option to the \fBset\fR builtin is obsolete. It causes
-.I all\^
-variable assignment arguments are placed in the environment,
-even if they occur after the command name.
-The following
-first prints
-.B "a=b c"
-and then
-.BR c :
-There is no alternative.
-.LI
-The obsolete
-.B \-xf
-option of the
-.B typeset
-command allows a function to be exported
-to scripts that are executed without a separate
-invocation of the shell.
-Functions that need to be defined across separate
-invocations of the shell should
-be placed in a directory and the
-.B FPATH
-variable should contains the name of this directory.
-They may also
-be specified in the
-.B ENV
-file with the
-.B \-xf
-option of
-.BR typeset .
-.LI
-The shell environment variable
-.B FCEDIT
-is obsolete. Use
-.B HISTEDIT
-instead.
-.LI
-In the
-.B \-s
-option
-(to \fBfc\fR or \fBhist\fR command???)
-(
-and in obsolete versions, the editor name
-.B \-
-)
-is used to skip the editing phase and
-to re-execute the command.
-.LI
-The
-.B \-t
-option to \fBalias\fR builtin is is obsolete. It
-is used to set and list tracked aliases.
-There is no replacement.
-.LI
-The shell command line option
-.B \-t
-is obsolete. This option cause the shell to exit after reading
-and executing one command. The is no replacement (although ending
-\&"command" with the exit builtin should have the same effect).
-.LI
-As an obsolete feature of the "set" builtin,
-if the first
-.I arg\^
-is
-.B \-
-then the
-.B \-x
-and
-.B \-v
-options are turned off and the next
-.I arg
-is treated as the first argument.
-Using
-.B \+
-rather than
-.B \-
-causes these options to be turned off.
-These options can also be used upon invocation of the shell.
-.LE
-
View
232 usr/src/lib/libshell/common/README
@@ -1,232 +0,0 @@
-This directory, and its subdirectories contain the source code
-for ksh-93; the language described in the second addition of
-the book, "The KornShell Command and Programming Language," by
-Morris Bolsky and David Korn which is published by Prentice Hall.
-ksh-93 has been compiled and run on several machines with several
-operating systems. The end of this file contains a partial list of
-operating systems and machines that ksh-93 has been known to run on.
-
-The layout of files for ksh-93 has changed somewhat since ksh-88,
-the last major release. Most of the source code for ksh remains in
-the sh directory. However, the shell editing and history routines
-are in the edit sub-directory. The code for shell built-ins is
-in the bltins directory. The data directory contains read-only
-data tables and messages that are used by the shell. The include
-files remain in the include directory and the shlib directory
-is gone. The features directory replaces the older install
-directory. The method for generating systems specific feature
-information has changed substantially.
-
-The Makefile file contains several compilation options that can be set
-before compiling ksh. Options are of the form SHOPT_option and become
-#define inside the code. These options are set to their recommended
-value and some of these may disappear as options in future releases.
-A value of 0, or no value represents off, 1 represents on.
-Note that == is needed, not =, because these are nmake state variables
-and changing their value will cause all modules that could be affected
-by this change to be recompiled.
-The options have the following defaults and meanings:
- ACCT off Shell accounting.
- ACCTFILE off Enable per user accounting info.
- AUDIT off For auditing specific users
- AUDITFILE "/etc/ksh_audit"
- APPEND on Allows var+=val string and array append.
- BASH off Bash compatibility mode. It is not fully implemented
- and is experimental.
- BRACEPAT on C-shell type abc{d,e}f style file generation
- CMDLIB_BLTIN off Makes all commands in libcmd.a builtins. The
- SH_CMDLIB_DIR nmake state variable can be used to
- specify a directory.
- CMDLIB_DIR off Sets CMDLIB_BLTIN=1 and provides a default value
- of "/opt/ast/bin" for SH_CMDLIB_DIR.
- COMPOUND_ARRAY
- on Allows all components of compound variables except the
- first to be any string by enclosing in [...]. It also
- allows components other than the last to be arrays.
- This is experimental and only partially complete.
- CRNL off <cr><nl> treated as <nl> in shell grammar.
- DYNAMIC on Dynamic loading of builtins. (Requires dlopen() interface.)
- ECHOPRINT off Make echo equivalent to print.
- ESH on Compile with emacs command line editing. The original
- emacs line editor code was provided by Mike Veach at IH.
- FILESCAN on Experimental option that allows fast reading of files
- using while < file;do ...; done and allowing fields in
- each line to be accessed as positional parameters.
- FS_3D off For use with 3-D file system. Enabled automatically for
- sytems with dynamic linking.
- KIA off Allow generation of shell cross reference database with -I.
- MULTIBYTE on Multibyte character handling. Requires mblen() and
- mbctowc().
- NAMESPACE on Allows namespaces. This is experimental, incomplete
- and undocumented.
- OLDTERMIO off Use either termios or termio at runtime.
- OO on Experimental object oriented extension. This option
- should disappear soon.
- OPTIMIZE on Optimize loop invariants for with for and while loops.
- P_SUID off If set, all real uids, greater than or equal to this
- value will require the -p flag to run suid/sgid scripts.
- PFSH off Compile with support for profile shell.
- RAWONLY off Turn on if the vi line mode doesn't work right unless
- you do a set -o viraw.
- SEVENBIT off Strip the eigth bit from characters.
- SPAWN off Use spawn as combined fork/exec. May improve speed on
- some systems.
- STATS on Add .sh.stats compound variable.
- SUID_EXEC on Execute /etc/suid_exec for setuid, setgid script.
- TIMEOUT off Set this to the number of seconds for timing out and
- exiting the shell when you don't enter a command. If
- non-zero, TMOUT can not be set larger than this value.
- TYPEDEF on Enable typeset type definitions.
- VSH on Compile with vi command line editing. The original vi
- line editor code was provided by Pat Sullivan at CB.
-
-The following compile options are set automatically by the feature testing:
- DEVFD Set when /dev/fd is a directory that names open files.
- SHELLMAGIC
- Set on systems that recognize script beginning with #! specially.
- VPIX Set on systems the have /usr/bin/vpix program for running MS-DOS.
-
-
-In most instances, you will generate ksh from a higher level directory
-which also generates libcmd and libast libraries on which ksh depends.
-However, it is possible to generate ksh, with by running make -f ksh.mk
-in this directory. The ksh.mk file was generated from the nmake Makefile.
-If you do not have make or nmake, but do have a Version 7 UNIX compatible
-shell, then you can run the script mamexec < Mamfile to build ksh.
-If you have nmake, version 2.3 or later, you can use it without the -f ksh.mk.
-In either case, ksh relies on libraries libast and libcmd which must be
-built first. The binary for ksh becomes the file named ./ksh which can
-be copied to where ever you install it.
-
-If you use old make or the Mamfile, and you system has dynamic shared
-libraries, then you should define the variables mam_cc_static and
-mam_cc_dynanamic as the compiler options that request static linking
-and dynamic linking respectively. This will decrease the number of
-shared libraries that ksh need and cut startup time substantially.
-
-The makefile should also generate shcomp, a program that will precompile
-a script. ksh93 is able to recognize files in this format and process
-them as scripts. You can use shcomp to send out scripts when you
-don't want to give away the original script source.
-
-It is advisable that you put the line PWD=$HOME;export PWD into the
-/etc/profile file to reduce initialization time for ksh.
-
-To be able to run setuid/setgid shell scripts, or scripts without read
-permission, the SUID_EXEC compile option must be on, and ksh must be installed
-in the /bin directory, the /usr/bin directory, the /usr/lbin directory,
-or the /usr/local/bin directory and the name must end in sh. The program
-suid_exec must be installed in the /etc directory, must be owned by root,
-and must be a suid program. If you must install ksh in some other directory
-and want to be able to run setuid/setgid and execute only scripts, then
-you will have to change the source code file sh/suid_exec.c explicitly.
-If you do not have ksh in one of these secure locations, /bin/sh will
-be invoked with the -p options and will fail when you execute a setuid/setgid
-and/or execute only script. Note, that ksh does not read the .profile
-or $ENV file when it the real and effective user/group id's are not
-equal.
-
-The tests sub-directory contains a number of regression tests for ksh.
-To run all these tests with the shell you just built, go to the tests
-directory and run the command
- SHELL=$dir/ksh $dir/ksh shtests
-where dir is the directory of the ksh you want to test.
-
-The file PROMO.mm is an advertisement that extolls the virtues of ksh.
-The file sh.1 contains the troff (man) description of this Shell.
-The file nval.3 contains the troff (man) description of the name-value
-pair library that is needed for writing built-ins that need to
-access shell variables.
-
-The file sh.memo contains a draft troff (mm) memo describing ksh. The
-file RELEASE88 contains the changes made for ksh88. The file RELEASE93
-contains the changes made in this release since ksh-88. The file
-RELEASE contains bug fixes made in this release since ksh-88. The file
-COMPATIBILITY contains a list of incompatibilities with ksh-88. The
-file bltins.mm is a draft troff (mm) memo describing how to write
-built-in commands that can be loaded at run time.
-
-Most of the work for internationalization has been done with ksh93.
-The file ksh.msg is a generated file that contains error messages
-that need to be translated. In addition, the function translate()
-in sh/init.c has to be completed to interface with the dictionary
-lookup. The translate function takes two argument, the string
-that is to be translated and a type which is
- 0 when a library string needs translation.
- 1 when one of the error messages in ksh.msg needs translation.
- 2 when a string in a script needs translation. You use a $ in front
- of a double quoted string in a script to indicate that it
- needs translation. The -D option for ksh builds the dictionary.
-The translate routine needs to return the translated message.
-For dictionaries that need to use a numeric key, it should be
-possible to use the strhash() function to generate numbers to
-go along with each of the messages and to use this number both
-when generating the dictionary and when converting strings.
-If you encounter error messages of type 1 that are not be translated via
-this translate() function send mail to the address below.
-
-Please report any problems or suggestions to:
-
-dgk@research.att.com
-
-
-ksh93 has been compiled and alpha tested on the following. An asterisk
-signifies that ksh has been installed as /bin/sh on this machine.
-
-* Sun OS 4.1.[123] on sparc.
- Sun OS 4.1.1 on sun.
- Solaris 2.[1-9] on sparc.
- Solaris 2.[4-8] on X86.
- HP/UX 8 on HP-9000/730.
- HP/UX 9 on HP-9000/730.
- HP/UX 10 on HP-9000/857.
- HP/UX 11 on pa-risc.
- System V Release 3 on Counterpoint C19
- System V Release 4 on AT&T Intel 486.
- System V Release 4 on NCR 4850 Intel 486.
- IRIX Release 4.0.? System V on SGI-MIPS.
- IRIX Release 5.1 System V on SGI-MIPS.
- IRIX Release 6.[1-5] System V on SGI-MIPS.
- System V Release 3.2 on 3B2.
- UTS 5.2.6 on Amdahl 3090,5990,580.
- System V Release 3.2 on i386.
- SMP_DC.OSx olivetti dcosx MIServer-S 2/128.
- SMP_DC.OSx Pyramid dcosx MIServer-S 2/160 r3000.
- 4.3BSD on Vax 8650.
- AIX release 2 on RS6000.
- AIX 3.2 on RS6000.
- Linux 1.X on Intel
- Linux 2.X on Intel
- Linux 2.X on Alpha
- Linux 2.X on Alpha
- Linux 2.X on OS/390
- Linux 2.X on sparc
- Linux 2.4 on intel itanium 64
- Linux Slackware on sparc64
-* Linux ARM on i-PAQ
- OSF1 on DEC alpha.
- OSF4 on DEC alpha.
- UMIPS 4.52 on mips.
- BSD-i [2-4] on X86.
- OpenBSD on X86
- NetBSD on X86
- FreeBSD on X86
- NeXT on Intel X86.
- NeXT on HP.
-* Windows NT using UWIN on X86
-* Windows NT using UWIN on alpha
- Windows NT using Cygwin on X86
- Windows NT with NutCracker libraries.
- Windows NT with Portage libraries.
- Windows 3.1 using custom C library.
- OpenEdition on MVS
- Darwin OS X on PPC
- MVS on OS 390
- SCO Openserver 3.2 on X86
- Unixware 7 on X86
-
-Good luck!!
-
-David Korn
-dgk@research.att.com
-
View
2,204 usr/src/lib/libshell/common/RELEASE
0 additions, 2,204 deletions not shown
View
182 usr/src/lib/libshell/common/TYPES
@@ -1,182 +0,0 @@
-
-The ability for users to define types has been added to ksh93t.
-Here is a quick summary of how types are defined and used in ksh93t.
-This is still a work in progress so some changes and additions
-are likely.
-
-A type can be defined either by a shared library or by using the new
-typeset -T option to the shell. The method for defining types via
-a shared library is not described here. However, the source file
-bltins/enum.c is an example of a builtin that creates enumeration types.
-
-By convention, typenames begin with a capitol letter and end in _t.
-To define a type, use
- typeset -T Type_t=(
- definition
- )
-where definition contains assignment commands, declaration commands,
-and function definitions. A declaration command (for example typeset,
-readonly, and export), is a built-in that differs from other builtins in
-that tilde substitution is performed on arguments after an =, assignments
-do not have to precede the command name, and field splitting and pathname
-expansion is not performed on the arguments.
-For example,
- typeset -T Pt_t=(
- float -h 'length in inches' x=1
- float -h 'width in inches' y=0
- integer -S count=0
- len()
- {
- print -r $((sqrt(_.x*_.x + _.y*_.y)))
- }
- set()
- {
- (( _.count++))
- }
- )
-
-defines a type Pt_t that has three variables x, y, and count defined as well
-as the discipline functions len and set. The variable x has an initial value
-of 1 and the variable y has an initial value of 0. The new -h option argument,
-is used for documentations purposes as described later and is ignored outside
-of a type definition.
-
-
-The variable count has the new -S attribute which means that it is shared
-between all instances of the type. The -S option to typeset is ignored
-outside of a type definition. Note the variable named _ that is used inside
-the function definition for len and set. It will be a reference to the
-instance of Pt_t that invoked the function. The functions len and set
-could also have been defined with function len and function set, but
-since there are no local variables, the len() and set() form are more
-efficient since they don't need to set up a context for local variables
-and for saving and restoring traps.
-
-If the discipline function named create is defined it will be
-invoked when creating each instance for that type. A function named
-create cannot be defined by any instance.
-
-When a type is defined, a declaration built-in command by this name
-is added to ksh. As with other shell builtins, you can get the man page
-for this newly added command by invoking Pt_t --man. The information from
-the -h options will be embedded in this man page. Any functions that
-use getopts to process arguments will be cross referenced on the generated
-man page.
-
-Since Pt_t is now a declaration command it can be used in the definition
-of other types, for example
- typeset -T Rect_t=( Pt_t ur ll)
-
-Because a type definition is a command, it can be loaded on first reference
-by putting the definition into a file that is found on FPATH.
-Thus, if this definition is in a file named Pt_t on FPATH, then
-a program can create instances of Pt_t without first including
-the definition.
-
-A type definition is readonly and cannot be unset. Unsetting non-shared
-elements of a type restores them to their default value. Unsetting a
-shared element has no effect.
-
-The Pt_t command is used to create an instance of Pt_t.
- Pt_t p1
-creates an instance named p1 with the initial value for p1.x set to 1
-and the initial value of p1.y set to 0.
- Pt_t p2=(x=3 y=4)
-creates an instance with the specified initial values. The len function
-gives the distance of the point to the origin. Thus, p1.len will output
-1 and p2.len will output 5.
-
-ksh93t also introduces a more efficient command substitution mechanism.
-Instead of $(command), the new command substitution ${ command;}
-can be used. Unlike (and ) which are always special, the { and } are
-reserved words and require the space after { and a newline or ; before }.
-Unlike $(), the ${ ;} command substitution executes the command in
-the current shell context saving the need to save and restore
-changes, therefore also allowing side effects.
-
-When trying to expand an element of a type, if the element does not exist,
-ksh will look for a discipline function with that name and treat this as if
-it were the ${ ;} command substitution. Thus, ${p1.len} is equivalent to
-${ p1.len;} and within an arithmetic expression, p1.len will be expanded
-via the new command substitution method.
-
-The type of any variable can be obtained from the new prefix
-operator @. Thus, ${@p1} will output Pt_t.
-
-By default, each instance inherits all the discipline functions defined
-by the type definition other than create. However, each instance can define
-a function by the same name that will override this definition.
-However, only discipline functions with the same name as those defined
-by the type or the standard get, set, append, and unset disciplines
-can be defined by each instance.
-
-Each instance of the type Pt_t behaves like a compound variable except
-that only the variables defined by the type can be referenced or set.
-Thus, p2.x=9 is valid, but p2.z=9 is not. Unless a set discipline function
-does otherwise, the value of $p1 will be expanded to the form of a compound
-variable that can be used for reinput into ksh.
-
-If the variables var1 and var2 are of the same type, then the assignment
- var2=var1
-will create a copy of the variable var1 into var2. This is equivalent to
- eval var2="$var1"
-but is faster since the variable does not need to get expanded or reparsed.
-
-The type Pt_t can be referenced as if it were a variable using the name
-.sh.type.Pt_t. To change the default point location for subsequent
-instances of Pt_t, you can do
- .sh.type.Pt_t=(x=5 y=12)
-so that
- Pt_t p3
- p3.len
-would be 13.
-
-Types can be defined for simple variables as well as for compound
-objects such as Pt_t. In this case, the variable named . inside
-the definition refers to the real value for the variable. For example,
-the type definition
- typeset -T Time_t=(
- integer .=0
- _='%H:%M:%S'
- get()
- {
- .sh.value=$(printf "%(${_._})T" "#$((_))" )
- }
- set()
- {
- .sh.value=$(printf "%(%#)T" "${.sh.value}")
-
- }
- )
-
-The sub-variable name _ is reserved for data used by discipline functions
-and will not be included with data written with the %B option to printf.
-In this case it is used to specify a date format.
-
-In this case
- Time_t t1 t2=now
-will define t1 as the time at the beginning of the epoch and t2
-as the current time. Unlike the previous case, $t2 will output
-the current time in the date format specified by the value t2._.
-However, the value of ${t2.} will expand the instance to a form
-that can be used as input to the shell.
-
-Finally, types can be derived from an existing type. If the first
-element in a type definition is named _, then the new type
-consists of all the elements and discipline functions from the
-type of _ extended by elements and discipline functions defined
-by new type definition. For example,
-
- typeset -T Pq_t=(
- Pt_t _
- float z=0.
- len()
- {
- print -r $((sqrt(_.x*_.x + _.y*_.y + _.z*_.z)))
- }
- )
-
-defines a new type Pq_t which is based on Pq_t and contains an additional
-field z and a different len discipline function. It is also possible
-to create a new type Pt_t based on the original Pt_t. In this case
-the original Pt_t is no longer accessible.
View
BIN  usr/src/lib/libshell/misc/images/callouts/1.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/callouts/10.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/callouts/2.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/callouts/3.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/callouts/4.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/callouts/5.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/callouts/6.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/callouts/7.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/callouts/8.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/callouts/9.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/tag_bourne.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/tag_i18n.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/tag_ksh.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/tag_ksh88.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/tag_ksh93.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/tag_l10n.png
Deleted file not rendered
View
BIN  usr/src/lib/libshell/misc/images/tag_perf.png
Deleted file not rendered
View
1,464 usr/src/lib/libshell/misc/shell_styleguide.docbook
@@ -1,1464 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN" "http://www.oasis-open.org/docbook/xml/5.0b5/dtd/docbook.dtd" [
- <!ENTITY tag_bourneonly '<inlinemediaobject><imageobject><imagedata fileref="images/tag_bourne.png"></imagedata></imageobject><textobject><phrase>[Bourne]</phrase></textobject></inlinemediaobject> '>
- <!ENTITY tag_kshonly '<inlinemediaobject><imageobject><imagedata fileref="images/tag_ksh.png"></imagedata></imageobject><textobject><phrase>[ksh]</phrase></textobject></inlinemediaobject> '>
- <!ENTITY tag_ksh88only '<inlinemediaobject><imageobject><imagedata fileref="images/tag_ksh88.png"></imagedata></imageobject><textobject><phrase>[ksh88]</phrase></textobject></inlinemediaobject> '>
- <!ENTITY tag_ksh93only '<inlinemediaobject><imageobject><imagedata fileref="images/tag_ksh93.png"></imagedata></imageobject><textobject><phrase>[ksh93]</phrase></textobject></inlinemediaobject> '>
- <!ENTITY tag_performance '<inlinemediaobject><imageobject><imagedata fileref="images/tag_perf.png"></imagedata></imageobject><textobject><phrase>[perf]</phrase></textobject></inlinemediaobject> '>
- <!ENTITY tag_i18n '<inlinemediaobject><imageobject><imagedata fileref="images/tag_i18n.png"></imagedata></imageobject><textobject><phrase>[i18n]</phrase></textobject></inlinemediaobject> '>
- <!ENTITY tag_l10n '<inlinemediaobject><imageobject><imagedata fileref="images/tag_l10n.png"></imagedata></imageobject><textobject><phrase>[l10n]</phrase></textobject></inlinemediaobject> '>
-]>
-<!--
-
- CDDL HEADER START
-
- The contents of this file are subject to the terms of the
- Common Development and Distribution License (the "License").
- You may not use this file except in compliance with the License.
-
- You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
- or http://www.opensolaris.org/os/licensing.
- See the License for the specific language governing permissions
- and limitations under the License.
-
- When distributing Covered Code, include this CDDL HEADER in each
- file and include the License file at usr/src/OPENSOLARIS.LICENSE.
- If applicable, add the following below this CDDL HEADER, with the
- fields enclosed by brackets "[]" replaced with your own identifying
- information: Portions Copyright [yyyy] [name of copyright owner]
-
- CDDL HEADER END
-
--->
-
-<!--
-
- Copyright 2009 Sun Microsystems, Inc. All rights reserved.
- Use is subject to license terms.
-
--->
-
-<!-- tag images were created like this:
-$ (text="perf" ;
- pbmtext -nomargins -lspace 0 -builtin fixed "${text}" |
- pbmtopgm 1 1 |
- pgmtoppm 1.0,1.0,1.0-0,0,0 /dev/stdin |
- ppmtogif |
- giftopnm |
- pnmtopng >"tag_${text}.png")
--->
-
-<!-- compile with:
-xsltproc &minus;&minus;stringparam generate.section.toc.level 0 \
- &minus;&minus;stringparam toc.max.depth 3 \
- &minus;&minus;stringparam toc.section.depth 12 \
- &minus;&minus;xinclude -o opensolaris_shell_styleguide.html /usr/share/sgml/docbook/docbook-xsl-stylesheets-1.69.1/html/docbook.xsl opensolaris_shell_styleguide.docbook
--->
-
-<article
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns="http://docbook.org/ns/docbook"
- xml:lang="en">
- <!-- xmlns:xi="http://www.w3.org/2001/XInclude" -->
-
- <info>
- <title><emphasis>[DRAFT]</emphasis> Bourne/Korn Shell Coding Conventions</title>
-
- <!-- subtitle abuse -->
- <subtitle>
- This page is currently work-in-progress until it is approved by the OS/Net community. Please send any comments to
- <email>shell-discuss@opensolaris.org</email>.
- </subtitle>
-
-
- <authorgroup>
-<!--
- <author><personname>David G. Korn</personname><email>dgk@research.att.com</email></author>
- <author><personname>Roland Mainz</personname><email>roland.mainz@nrubsig.org</email></author>
- <author><personname>Mike Shapiro</personname><email>mike.shapiro@sun.com</email></author>
--->
- <author><orgname>OpenSolaris.org</orgname></author>
- </authorgroup>
- </info>
-
-<section xml:id="intro">
- <title>Intro</title>
- <para>This document describes the shell coding style used for all the SMF script changes integrated into (Open)Solaris.</para>
- <para>All new SMF shell code should conform to this coding standard, which is intended to match our existing C coding standard.</para>
- <para>When in doubt, think "what would be the C-Style equivalent ?" and "What does the POSIX (shell) standard say ?"</para>
-</section><!-- end of intro -->
-
-
-<section xml:id="rules">
- <title>Rules</title>
-
-
-
- <section xml:id="general">
- <title>General</title>
-
- <section xml:id="basic_format">
- <title>Basic Format</title>
- <para>Similar to <literal>cstyle</literal>, the basic format is that all
- lines are indented by TABs or eight spaces, and continuation lines (which
- in the shell end with "\") are indented by an equivalent number of TABs
- and then an additional four spaces, e.g.
-<programlisting>
-cp foo bar
-cp some_realllllllllllllllly_realllllllllllllly_long_path \
- to_another_really_long_path
-</programlisting>
- </para>
- <para>The encoding used for the shell scripts is either <literal>ASCII</literal>
- or <literal>UTF-8</literal>, alternative encodings are only allowed when the
- application requires this.</para>
- </section>
-
-
- <section xml:id="commenting">
- <title>Commenting</title>
- <para>Shell comments are preceded by the '<literal>#</literal>' character. Place
- single-line comments in the right-hand margin. Use an extra '<literal>#</literal>'
- above and below the comment in the case of multi-line comments:
-<programlisting>
-cp foo bar # Copy foo to bar
-
-#
-# Modify the permissions on bar. We need to set them to root/sys
-# in order to match the package prototype.
-#
-chown root bar
-chgrp sys bar
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="interpreter_magic">
- <title>Interpreter magic</title>
- <para>The proper interpreter magic for your shell script should be one of these:
-<programlisting>
-#!/bin/sh Standard Bourne shell script
-#!/bin/ksh -p Standard Korn shell 88 script. You should always write ksh
- scripts with -p so that ${ENV} (if set by the user) is not
- sourced into your script by the shell.
-#!/bin/ksh93 Standard Korn shell 93 script (-p is not needed since ${ENV} is
- only used for interactive shell sessions).
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="harden_your_script_against_unexpected_input">
- <title>Harden the script against unexpected (user) input</title>
- <para>Harden your script against unexpected (user) input, including
- command line options, filenames with blanks (or other special
- characters) in the name, or file input</para>
- </section>
-
-
- <section xml:id="use_builtin_commands">
- <title>&tag_kshonly;&tag_performance;Use builtin commands if the shell provides them</title>
- <para>
- Use builtin commands if the shell provides them. For example ksh93s+
- (ksh93, version 's+') delivered with Solaris (as defined by PSARC 2006/550)
- supports the following builtins:
- <simplelist type="inline">
- <member>basename</member>
- <member>cat</member>
- <member>chgrp</member>
- <member>chmod</member>
- <member>chown</member>
- <member>cmp</member>
- <member>comm</member>
- <member>cp</member>
- <member>cut</member>
- <member>date</member>
- <member>dirname</member>
- <member>expr</member>
- <member>fds</member>
- <member>fmt</member>
- <member>fold</member>
- <member>getconf</member>
- <member>head</member>
- <member>id</member>
- <member>join</member>
- <member>ln</member>
- <member>logname</member>
- <member>mkdir</member>
- <member>mkfifo</member>
- <member>mv</member>
- <member>paste</member>
- <member>pathchk</member>
- <member>rev</member>
- <member>rm</member>
- <member>rmdir</member>
- <member>stty</member>
- <member>tail</member>
- <member>tee</member>
- <member>tty</member>
- <member>uname</member>
- <member>uniq</member>
- <member>wc</member>
- <member>sync</member>
- </simplelist>
- Those builtins can be enabled via <literal>$ builtin name_of_builtin #</literal> in shell
- scripts (note that ksh93 builtins implement exact POSIX behaviour - some
- commands in Solaris <filename>/usr/bin/</filename> directory implement pre-POSIX behaviour.
- Add <literal>/usr/xpg6/bin/:/usr/xpg4/bin</literal> before
- <filename>/usr/bin/</filename> in <envar>${PATH}</envar> to test whether your script works with
- the XPG6/POSIX versions)
- </para>
- </section>
-
-
- <section xml:id="use_blocks_not_subshells">
- <title>&tag_performance;Use blocks and not subshells if possible</title>
- <para>Use blocks and not subshells if possible, e.g. use
- <literal>$ { print "foo" ; print "bar" ; }</literal> instead of
- <literal>$ (print "foo" ; print "bar") #</literal> - blocks are
- faster since they do not require to save the subshell context (ksh93) or
- trigger a shell child process (Bourne shell, bash, ksh88 etc.)
- </para>
- </section>
-
-
- <section xml:id="use_long_options_for_set_builtin">
- <title>&tag_kshonly; use long options for "<literal>set</literal>"</title>
- <para>use long options for "<literal>set</literal>", for example instead of <literal>$ set -x #</literal>
- use <literal>$ set -o xtrace #</literal> to make the code more readable.</para>
- </section>
-
-
- <section xml:id="use_posix_command_substitutions_syntax">
- <title>&tag_kshonly; Use <literal>$(...)</literal> instead of <literal>`...`</literal> command substitutions</title>
- <para>Use <literal>$(...)</literal> instead of <literal>`...`</literal> - <literal>`...`</literal>
- is an obsolete construct in ksh+POSIX sh scripts and <literal>$(...)</literal>.is a cleaner design,
- requires no escaping rules, allows easy nesting etc.</para>
-
- <note><title>&tag_ksh93only; <literal>${ ...;}</literal>-style command substitutions</title>
- <para>ksh93 has support for an alternative version of command substitutions with the
- syntax <literal>${ ...;}</literal> which do not run in a subshell.
- </para></note>
- </section>
-
-
- <section xml:id="put_command_substitution_result_in_quotes">
- <title>&tag_kshonly; Always put the result of a <literal>$(...)</literal> or
- <literal>$( ...;)</literal> command substitution in quotes</title>
- <para>Always put the result of <literal>$( ... )</literal> or <literal>$( ...;)</literal> in
- quotes (e.g. <literal>foo="$( ... )"</literal> or <literal>foo="$( ...;)"</literal>) unless
- there is a very good reason for not doing it</para>
- </section>
-
-
- <section xml:id="always_set_path">
- <title>Scripts should always set their <envar>PATH</envar></title>
- <para>Scripts should always set their <envar>PATH</envar> to make sure they do not use
- alternative commands by accident (unless the value of <envar>PATH</envar> is well-known
- and guaranteed to be set by the caller)</para>
- </section>
-
-
- <section xml:id="make_sure_commands_are_available">
- <title>Make sure that commands from other packages/applications are really installed on the machine</title>
- <para>Scripts should make sure that commands in optional packages are really
- there, e.g. add a "precheck" block in scipts to avoid later failure when
- doing the main job</para>
- </section>
-
-
- <section xml:id="check_usage_of_boolean_variables">
- <title>Check how boolean values are used/implemented in your application</title>
- <para>Check how boolean values are used in your application.</para>
- <para>For example:
-<programlisting>
-mybool=0
-# do something
-if [ $mybool -eq 1 ] ; then do_something_1 ; fi
-</programlisting>
-could be rewritten like this:
-<programlisting>
-mybool=false # (valid values are "true" or "false", pointing
-# to the builtin equivalents of /bin/true or /bin/false)
-# do something
-if ${mybool} ; then do_something_1 ; fi
-</programlisting>
-or
-<programlisting>
-integer mybool=0 # values are 0 or 1
-# do something
-if (( mybool==1 )) ; then do_something_1 ; fi
-</programlisting>
- </para>
- </section>
-
- <section xml:id="shell_uses_characters_not_bytes">
- <title>&tag_i18n;The shell always operates on <emphasis>characters</emphasis> not bytes</title>
- <para>Shell scripts operate on characters and <emphasis>not</emphasis> bytes.
- Some locales use multiple bytes (called "multibyte locales") to represent one character</para>
-
- <note><para>ksh93 has support for binary variables which explicitly
- operate on bytes, not characters. This is the <emphasis>only</emphasis> allowed
- exception.</para></note>
- </section>
-
-
- <section xml:id="multibyte_locale_input">
- <title>&tag_i18n;Multibyte locales and input</title>
- <para>Think about whether your application has to handle file names or
- variables in multibyte locales and make sure all commands used in your
- script can handle such characters (e.g. lots of commands in Solaris's
- <filename>/usr/bin/</filename> are <emphasis>not</emphasis> able to handle such values - either use ksh93
- builtin constructs (which are guaranteed to be multibyte-aware) or
- commands from <filename>/usr/xpg4/bin/</filename> and/or <filename>/usr/xpg6/bin</filename>)
- </para>
- </section>
-
-
- <section xml:id="use_external_filters_only_for_large_datasets">
- <title>&tag_performance;Only use external filters like <literal>grep</literal>/<literal>sed</literal>/<literal>awk</literal>/etc.
- if you want to process lots of data with them</title>
- <para>Only use external filters like <literal>grep</literal>/<literal>sed</literal>/<literal>awk</literal>/etc.
- if a significant amount of data is processed by the filter or if
- benchmarking shows that the use of builtin commands is significantly slower
- (otherwise the time and resources needed to start the filter are
- far greater then the amount of data being processed,
- creating a performance problem).</para>
- <para>For example:
-<programlisting>
-if [ "$(echo "$x" | egrep '.*foo.*')" != "" ] ; then
- do_something ;
-done
-</programlisting>
-can be re-written using ksh93 builtin constructs, saving several
-<literal>|fork()|+|exec()|</literal>'s:
-<programlisting>
-if [[ "${x}" == ~(E).*foo.* ]] ; then
- do_something ;
-done
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="use_dashdash_if_first_arg_is_variable">
- <title>If the first operand of a command is a variable, use <literal>--</literal></title>
- <para>If the first operand of a command is a variable, use <literal>--</literal>
- for any command that accepts this as end of argument to
- avoid problems if the variable expands to a value starting with <literal>-</literal>.
- </para>
- <note><para>
- At least
- <simplelist type="inline">
- <member>print</member>
- <member>/usr/bin/fgrep</member><member>/usr/xpg4/bin/fgrep</member>
- <member>/usr/bin/grep</member> <member>/usr/xpg4/bin/grep</member>
- <member>/usr/bin/egrep</member><member>/usr/xpg4/bin/egrep</member>
- </simplelist>
- support <literal>--</literal> as "end of arguments"-terminator.
- </para></note>
- </section>
-
- <section xml:id="use_export">
- <title>&tag_kshonly;&tag_performance;Use <literal>$ export FOOBAR=val #</literal> instead of
- <literal>$ FOOBAR=val ; export FOOBAR #</literal></title>
- <para>Use <literal>$ export FOOBAR=val # instead of $ FOOBAR=val ; export FOOBAR #</literal> -
- this is much faster.</para>
- </section>
-
-
- <section xml:id="use_subshell_around_set_dashdash_usage">
- <title>Use a subshell (e.g. <literal>$ ( mycmd ) #</literal>) around places which use
- <literal>set -- $(mycmd)</literal> and/or <literal>shift</literal></title>
- <para>Use a subshell (e.g. <literal>$ ( mycmd ) #</literal>) around places which use
- <literal>set -- $(mycmd)</literal> and/or <literal>shift</literal> unless the variable
- affected is either a local one or if it's guaranteed that this variable will no longer be used
- (be careful for loadable functions, e.g. ksh/ksh93's <literal>autoload</literal> !!!!)
- </para>
- </section>
-
-
- <section xml:id="be_careful_with_tabs_in_script_code">
- <title>Be careful with using TABS in script code, they are not portable
- between editors or platforms</title>
- <para>Be careful with using TABS in script code, they are not portable
- between editors or platforms.</para>
- <para>If you use ksh93 use <literal>$'\t'</literal> to include TABs in sources, not the TAB character itself.</para>
- </section>
-
-
- <section xml:id="centralise_error_exit">
- <title>If you have multiple points where your application exits with an error
- message create a central function for this purpose</title>
- <para>If you have multiple points where your application exits with an error
- message create a central function for this, e.g.
-<programlisting>
-if [ -z "$tmpdir" ] ; then
- print -u2 "mktemp failed to produce output; aborting."
- exit 1
-fi
-if [ ! -d $tmpdir ] ; then
- print -u2 "mktemp failed to create a directory; aborting."
- exit 1
-fi
-</programlisting>
-should be replaced with
-<programlisting>
-function fatal_error
-{
- print -u2 "${progname}: $*"
- exit 1
-}
-# do something (and save ARGV[0] to variable "progname")
-if [ -z "$tmpdir" ] ; then
- fatal_error "mktemp failed to produce output; aborting."
-fi
-if [ ! -d "$tmpdir" ] ; then
- fatal_error "mktemp failed to create a directory; aborting."
-fi
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="use_set_o_nounset">
- <title>&tag_kshonly; Think about using <literal>$ set -o nounset #</literal> by default</title>
- <para>Think about using <literal>$ set -o nounset #</literal> by default (or at least during the
- script's development phase) to catch errors where variables are used
- when they are not set (yet), e.g.
-<screen>
-$ <userinput>(set -o nounset ; print ${foonotset})</userinput>
-<computeroutput>/bin/ksh93: foonotset: parameter not set</computeroutput>
-</screen>
- </para>
- </section>
-
-
- <section xml:id="avoid_eval_builtin">
- <title>Avoid using <literal>eval</literal> unless absolutely necessary</title>
- <para>Avoid using <literal>eval</literal> unless absolutely necessary. Subtle things
- can happen when a string is passed back through the shell
- parser. You can use name references to avoid uses such as
- <literal>eval $name="$value"</literal>.
- </para>
- </section>
-
-
- <section xml:id="use_concatenation_operator">
- <title>&tag_ksh93only;Use the string/array concatenation operator <literal>+=</literal></title>
- <para>Use <literal>+=</literal> instead of manually adding strings/array elements, e.g.
-<programlisting>
-foo=""
-foo="${foo}a"
-foo="${foo}b"
-foo="${foo}c"
-</programlisting>
-should be replaced with
-<programlisting>
-foo=""
-foo+="a"
-foo+="b"
-foo+="c"
-</programlisting>
- </para>
- </section>
-
- <section xml:id="use_source_not_dot">
- <title>&tag_ksh93only;Use <literal>source</literal> instead of '<literal>.</literal> '(dot)
- to include other shell script fragments</title>
- <para>Use <literal>source</literal> instead of '<literal>.</literal>'
- (dot) to include other shell script fragments - the new form is much
- more readable than the tiny dot and a failure can be caught within the script.</para>
- </section>
-
-
- <section xml:id="use_builtin_localisation_support">
- <title>&tag_ksh93only;&tag_performance;&tag_l10n;Use <literal>$"..."</literal> instead of
- <literal>gettext ... "..."</literal> for strings that need to be localized for different locales</title>
- <para>Use $"..." instead of <literal>gettext ... "..."</literal> for strings that need to be
- localized for different locales. <literal>gettext</literal> will require a
- <literal>fork()+exec()</literal> and
- reads the whole catalog each time it's called, creating a huge overhead for localisation
- (and the <literal>$"..."</literal> is easier to use, e.g. you only have to put a
- <literal>$</literal> in front of the catalog and the string will be localised).
- </para>
- </section>
-
-
- <section xml:id="use_set_o_noglob">
- <title>&tag_kshonly;&tag_performance;Use <literal>set -o noglob</literal> if you do not need to expand files</title>
- <para>If you don't expect to expand files, you can do set <literal>-f</literal>
- (<literal>set -o noglob</literal>) as well. This way the need to use <literal>""</literal> is
- greatly reduced.</para>
- </section>
-
-
- <section xml:id="use_empty_ifs_to_handle_spaces">
- <title>&tag_ksh93only;Use <literal>IFS=</literal> to avoid problems with spaces in filenames</title>
- <para>Unless you want to do word splitting, put <literal>IFS=</literal>
- at the beginning of a command. This way spaces in
- file names won't be a problem. You can do
- <literal>IFS='delims' read -r</literal> line
- to override <envar>IFS</envar> just for the <literal>read</literal> command. However,
- you can't do this for the <literal>set</literal> builtin.</para>
- </section>
-
-
- <section xml:id="set_locale_when_comparing_against_localised_output">
- <title>Set the message locale if you process output of tools which may be localised</title>
- <para>Set the message locale (<envar>LC_MESSAGES</envar>) if you process output of tools which may be localised</para>
- <example><title>Set <envar>LC_MESSAGES</envar> when testing for specific outout of the <filename>/usr/bin/file</filename> utility:</title>
-<programlisting>
-# set french as default message locale
-export LC_MESSAGES=fr_FR.UTF-8
-
-...
-
-# test whether the file "/tmp" has the filetype "directory" or not
-# we set LC_MESSAGES to "C" to ensure the returned message is in english
-if [[ "$(LC_MESSAGES=C file /tmp)" = *directory ]] ; then
- print "is a directory"
-fi
-</programlisting>
- <note><para>The environment variable <envar>LC_ALL</envar> always
- overrides any other <envar>LC_*</envar> environment variables
- (and <envar>LANG</envar>, too),
- including <envar>LC_MESSAGES</envar>.
- if there is the chance that <envar>LC_ALL</envar> may be set
- replace <envar>LC_MESSAGES</envar> with <envar>LC_ALL</envar>
- in the example above.</para></note>
- </example>
- </section>
-
- <section xml:id="cleanup_after_yourself">
- <title>Cleanup after yourself.</title>
- <para>Cleanup after yourself. For example ksh/ksh93 have an <literal>EXIT</literal> trap which
- is very useful for this.
- </para>
- <note><para>
- Note that the <literal>EXIT</literal> trap is executed for a subshell and each subshell
- level can run it's own <literal>EXIT</literal> trap, for example
-<screen>
-$ <userinput>(trap "print bam" EXIT ; (trap "print snap" EXIT ; print "foo"))</userinput>
-<computeroutput>foo
-snap
-bam</computeroutput>
-</screen>
- </para></note>
- </section>
-
- <section xml:id="use_proper_exit_code">
- <title>Use a proper <literal>exit</literal> code</title>
- <para>Explicitly set the exit code of a script, otherwise the exit code
- from the last command executed will be used which may trigger problems
- if the value is unexpected.</para>
- </section>
-
-
- <section xml:id="shell_lint">
- <title>&tag_ksh93only;Use <literal>shcomp -n scriptname.sh /dev/null</literal> to check for common errors</title>
- <para>Use <literal>shcomp -n scriptname.sh /dev/null</literal> to
- check for common problems (such as insecure, depreciated or ambiguous constructs) in shell scripts.</para>
- </section>
- </section><!-- end of general -->
-
-
-
-
-
- <section xml:id="functions">
- <title>Functions</title>
-
- <section xml:id="use_functions">
- <title>Use functions to break up your code</title>
- <para>Use functions to break up your code into smaller, logical blocks.</para>
- </section>
-
- <section xml:id="do_not_reserved_keywords_for_function_names">
- <title>Do not use function names which are reserved keywords in C/C++/JAVA or the POSIX shell standard</title>
- <para>Do not use function names which are reserved keywords (or function names) in C/C++/JAVA or the POSIX shell standard
- (to avoid confusion and/or future changes/updates to the shell language).
- </para>
- </section>
-
- <section xml:id="use_ksh_style_function_syntax">
- <title>&tag_kshonly;&tag_performance;Use ksh-style <literal>function</literal></title>
- <para>It is <emphasis>highly</emphasis> recommended to use ksh style functions
- (<literal>function foo { ... }</literal>) instead
- of Bourne-style functions (<literal>foo() { ... }</literal>) if possible
- (and local variables instead of spamming the global namespace).</para>
-
- <warning><para>
- The difference between old-style Bourne functions and ksh functions is one of the major differences
- between ksh88 and ksh93 - ksh88 allowed variables to be local for Bourne-style functions while ksh93
- conforms to the POSIX standard and will use a function-local scope for variables declared in
- Bourne-style functions.</para>
- <para>Example (note that "<literal>integer</literal>" is an alias for "<literal>typeset -li</literal>"):
-<programlisting>
-# new style function with local variable
-$ ksh93 -c 'integer x=2 ; function foo { integer x=5 ; } ; print "x=$x"
-; foo ; print "x=$x" ;'
-x=2
-x=2
-# old style function with an attempt to create a local variable
-$ ksh93 -c 'integer x=2 ; foo() { integer x=5 ; } ; print "x=$x" ; foo ;
-print "x=$x" ;'
-x=2
-x=5
-</programlisting>
-
- <uri xlink:href="http://www.opensolaris.org/os/project/ksh93-integration/docs/ksh93r/general/compatibility/">usr/src/lib/libshell/common/COMPATIBILITY</uri>
- says about this issue:
-<blockquote><para>
-Functions, defined with name() with ksh-93 are compatible with
-the POSIX standard, not with ksh-88. No local variables are
-permitted, and there is no separate scope. Functions defined
-with the function name syntax, maintain compatibility.
-This also affects function traces.
-</para></blockquote>
-(this issue also affects <filename>/usr/xpg4/bin/sh</filename> in Solaris 10 because it is based on ksh88. This is a bug.).
- </para></warning>
-
- </section>
-
-
- <section xml:id="use_proper_return_code">
- <title>Use a proper <literal>return</literal> code</title>
- <para>Explicitly set the return code of a function - otherwise the exit code
- from the last command executed will be used which may trigger problems
- if the value is unexpected.</para>
- <para>The only allowed exception is if a function uses the shell's <literal>errexit</literal> mode to leave
- a function, subshell or the script if a command returns a non-zero exit code.
- </para>
- </section>
-
- <section xml:id="use_fpath_to_load_common_code">
- <title>&tag_kshonly;Use <envar>FPATH</envar> to load common functions, not <literal>source</literal></title>
- <para>
- Use the ksh <envar>FPATH</envar> (function path) feature to load functions which are shared between scripts
- and not <literal>source</literal> - this allows to load such a function on demand and not all at once.</para>
- </section>
-
- </section><!-- end of functions -->
-
-
-
-
- <section xml:id="if_for_while">
- <title><literal>if</literal>, <literal>for</literal> and <literal>while</literal></title>
-
- <section xml:id="if_for_while_format">
- <title>Format</title>
- <para>To match <literal>cstyle</literal>, the shell token equivalent to the <literal>C</literal>
- "<literal>{</literal>" should appear on the same line, separated by a
- "<literal>;</literal>", as in:
-<programlisting>
-if [ "$x" = "hello" ] ; then
- echo $x
-fi
-
-if [[ "$x" = "hello" ]] ; then
- print $x
-fi
-
-for i in 1 2 3; do
- echo $i
-done
-
-for ((i=0 ; i &lt; 3 ; i++)); do
- print $i
-done
-
-while [ $# -gt 0 ]; do
- echo $1
- shift
-done
-
-while (( $# &gt; 0 )); do
- print $1
- shift
-done
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="test_builtin">
- <title><literal>test</literal> Builtin</title>
- <para>DO NOT use the test builtin. Sorry, executive decision.</para>
- <para>In our Bourne shell, the <literal>test</literal> built-in is the same as the "["
- builtin (if you don't believe me, try "type test" or refer to <filename>usr/src/cmd/sh/msg.c</filename>).</para>
- <para>
- So please do not write:
-<programlisting>
-if test $# -gt 0 ; then
-</programlisting>
-instead use:
-<programlisting>
-if [ $# -gt 0 ] ; then
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="use_ksh_test_syntax">
- <title>&tag_kshonly;&tag_performance;Use "<literal>[[ expr ]]</literal>" instead of "<literal>[ expr ]</literal>"</title>
- <para>Use "<literal>[[ expr ]]</literal>" instead of "<literal>[ expr ]</literal>" if possible
- since it avoids going through the whole pattern expansion/etc. machinery and
- adds additional operators not available in the Bourne shell, such as short-circuit
- <literal>&amp;&amp;</literal> and <literal>||</literal>.
- </para>
- </section>
-
-
- <section xml:id="use_posix_arithmetic_expressions">
- <title>&tag_kshonly; Use "<literal>(( ... ))</literal>" for arithmetic expressions</title>
- <para>Use "<literal>(( ... ))</literal>" instead of "<literal>[ expr ]</literal>"
- or "<literal>[[ expr ]]</literal>" expressions.
- </para>
- <para>
- Example: Replace
-<programlisting>
-i=5
-# do something
-if [ $i -gt 5 ] ; then
-</programlisting>
-with
-<programlisting>
-i=5
-# do something
-if (( i &gt; 5 )) ; then
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="compare_exit_code_using_math">
- <title>&tag_kshonly;&tag_performance;Compare exit code using arithmetic expressions expressions</title>
- <para>Use POSIX arithmetic expressions to test for exit/return codes of commands and functions.
- For example turn
-<programlisting>
-if [ $? -gt 0 ] ; then
-</programlisting>
-into
-<programlisting>
-if (( $? &gt; 0 )) ; then
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="use_builtin_commands_in_loops">
- <title>&tag_bourneonly; Use builtin commands in conditions for <literal>while</literal> endless loops</title>
- <para>Make sure that your shell has a "<literal>true</literal>" builtin (like ksh93) when
- executing endless loops like <literal>$ while true ; do do_something ; done #</literal> -
- otherwise each loop cycle runs a <literal>|fork()|+|exec()|</literal>-cycle to run
- <filename>/bin/true</filename>
- </para>
- </section>
-
-
- <section xml:id="single_line_if_statements">
- <title>Single-line if-statements</title>
- <para>It is permissible to use <literal>&amp;&amp;</literal> and <literal>||</literal> to construct
- shorthand for an "<literal>if</literal>" statement in the case where the if statement has a
- single consequent line:
-<programlisting>
-[ $# -eq 0 ] &amp;&amp; exit 0
-</programlisting>
-instead of the longer:
-<programlisting>
-if [ $# -eq 0 ]; then
- exit 0
-fi
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="exit_status_and_if_for_while">
- <title>Exit Status and <literal>if</literal>/<literal>while</literal> statements</title>
- <para>Recall that "<literal>if</literal>" and "<literal>while</literal>"
- operate on the exit status of the statement
- to be executed. In the shell, zero (0) means true and non-zero means false.
- The exit status of the last command which was executed is available in the $?
- variable. When using "<literal>if</literal>" and "<literal>while</literal>",
- it is typically not necessary to use
- <literal>$?</literal> explicitly, as in:
-<programlisting>
-grep foo /etc/passwd &gt;/dev/null 2>&amp;1
-if [ $? -eq 0 ]; then
- echo "found"
-fi
-</programlisting>
-Instead, you can more concisely write:
-<programlisting>
-if grep foo /etc/passwd &gt;/dev/null 2>&amp;1; then
- echo "found"
-fi
-</programlisting>
-Or, when appropriate:
-<programlisting>
-grep foo /etc/passwd &gt;/dev/null 2>&amp;1 &amp;&amp; echo "found"
-</programlisting>
- </para>
- </section>
-
- </section><!-- end of if/for/while -->
-
-
-
-
-
-
- <section xml:id="variables">
- <title>Variable types, naming and usage</title>
-
- <section xml:id="names_should_be_lowercase">
- <title>Names of local, non-environment, non-constant variables should be lowercase</title>
- <para>Names of variables local to the current script which are not exported to the environment
- should be lowercase while variable names which are exported to the
- environment should be uppercase.</para>
- <para>The only exception are global constants (=global readonly variables,
- e.g. <literal>$ float -r M_PI=3.14159265358979323846 #</literal> (taken from &lt;math.h&gt;))
- which may be allowed to use uppercase names, too.
- </para>
-
- <warning><para>
- Uppercase variable names should be avoided because there is a good chance
- of naming collisions with either special variable names used by the shell
- (e.g. <literal>PWD</literal>, <literal>SECONDS</literal> etc.).
- </para></warning>
- </section>
-
- <section xml:id="do_not_reserved_keywords_for_variable_names">
- <title>Do not use variable names which are reserved keywords/variable names in C/C++/JAVA or the POSIX shell standard</title>
- <para>Do not use variable names which are reserved keywords in C/C++/JAVA or the POSIX shell standard
- (to avoid confusion and/or future changes/updates to the shell language).
- </para>
- <note>
- <para>The Korn Shell and the POSIX shell standard have many more
- reserved variable names than the original Bourne shell. All
- these reserved variable names are spelled uppercase.
- </para>
- </note>
- </section>
-
- <section xml:id="use_brackets_around_long_names">
- <title>Always use <literal>'{'</literal>+<literal>'}'</literal> when using variable
- names longer than one character</title>
- <para>Always use <literal>'{'</literal>+<literal>'}'</literal> when using
- variable names longer than one character unless a simple variable name is
- followed by a blank, <literal>/</literal>, <literal>;</literal>, or <literal>$</literal>
- character (to avoid problems with array,
- compound variables or accidental misinterpretation by users/shell)
-<programlisting>
-print "$foo=info"
-</programlisting>
-should be rewritten to
-<programlisting>
-print "${foo}=info"
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="quote_variables_containing_filenames_or_userinput">
- <title><emphasis>Always</emphasis> put variables into quotes when handling filenames or user input</title>
- <para><emphasis>Always</emphasis> put variables into quotes when handling filenames or user input, even if
- the values are hardcoded or the values appear to be fixed. Otherwise at
- least two things may go wrong:
- <itemizedlist>
- <listitem><para>a malicious user may be able to exploit a script's inner working to
- infect his/her own code</para></listitem>
- <listitem><para>a script may (fatally) misbehave for unexpected input (e.g. file names
- with blanks and/or special symbols which are interpreted by the shell)</para></listitem>
- </itemizedlist>
- </para>
-
- <note><para>
- As alternative a script may set <literal>IFS='' ; set -o noglob</literal> to turn off the
- interpretation of any field seperators and the pattern globbing.
- </para></note>
- </section>
-
-
-
- <section xml:id="use_typed_variables">
- <title>&tag_kshonly;&tag_performance;Use typed variables if possible.</title>
- <para>For example the following is very
- inefficient since it transforms the integer values to strings and back
- several times:
-<programlisting>
-a=0
-b=1
-c=2
-# more code
-if [ $a -lt 5 -o $b -gt c ] ; then do_something ; fi
-</programlisting>
-This could be rewritten using ksh constructs:
-<programlisting>
-integer a=0
-integer b=1
-integer c=2
-# more code
-if (( a &lt; 5 || b &gt; c )) ; then do_something ; fi
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="store_lists_in_arrays">
- <title>&tag_ksh93only; Store lists in arrays or associative arrays</title>
- <para>Store lists in arrays or associative arrays - this is usually easier
- to manage.</para>
- <para>
- For example:
-<programlisting>
-x="
-/etc/foo
-/etc/bar
-/etc/baz
-"
-echo $x
-</programlisting>
-can be replaced with
-<programlisting>
-typeset -a mylist
-mylist[0]="/etc/foo"
-mylist[1]="/etc/bar"
-mylist[2]="/etc/baz"
-print "${mylist[@]}"
-</programlisting>
-or (ksh93-style append entries to a normal (non-associative) array)
-<programlisting>
-typeset -a mylist
-mylist+=( "/etc/foo" )
-mylist+=( "/etc/bar" )
-mylist+=( "/etc/baz" )
-print "${mylist[@]}"
-</programlisting>
- </para>
- <note>
- <title>Difference between expanding arrays with mylist[@] and mylist[*] subscript operators</title>
- <para>
- Arrays may be expanded using two similar subscript operators, @ and *. These subscripts
- differ only when the variable expansion appears within double quotes. If the variable expansion
- is between double-quotes, "${mylist[*]}" expands to a single string with the value of each array
- member separated by the first character of the <envar>IFS</envar> variable, and "${mylist[@]}"
- expands each element of name to a separate string.
- </para>
- <example><title>Difference between [@] and [*] when expanding arrays</title>
-<programlisting>
-typeset -a mylist
-mylist+=( "/etc/foo" )
-mylist+=( "/etc/bar" )
-mylist+=( "/etc/baz" )
-IFS=","
-printf "mylist[*]={ 0=|%s| 1=|%s| 2=|%s| 3=|%s| }\n" "${mylist[*]}"
-printf "mylist[@]={ 0=|%s| 1=|%s| 2=|%s| 3=|%s| }\n" "${mylist[@]}"
-</programlisting>
-<para>will print:</para>
-<screen>
-<computeroutput>mylist[*]={ 0=|/etc/foo,/etc/bar,/etc/baz| 1=|| 2=|| 3=|| }
-mylist[@]={ 0=|/etc/foo| 1=|/etc/bar| 2=|/etc/baz| 3=|| }
-</computeroutput>
-</screen>
- </example>
- </note>
- </section>
-
-
- <section xml:id="use_compound_variables_or_lists_for_grouping">
- <title>&tag_ksh93only; Use compound variables or associative arrays to group similar variables together</title>
- <para>Use compound variables or associative arrays to group similar variables together.</para>
- <para>
- For example:
-<programlisting>
-box_width=56
-box_height=10
-box_depth=19
-echo "${box_width} ${box_height} ${box_depth}"
-</programlisting>
-could be rewritten to ("associative array"-style)
-<programlisting>
-typeset -A -E box=( [width]=56 [height]=10 [depth]=19 )
-print -- "${box[width]} ${box[height]} ${box[depth]}"
-</programlisting>
-or ("compound variable"-style
-<programlisting>
-box=(
- float width=56
- float height=10
- float depth=19
- )
-print -- "${box.width} ${box.height} ${box.depth}"
-</programlisting>
- </para>
- </section>
- </section><!-- end of variables -->
-
-
-
-
-
-
-
- <section xml:id="io">
- <title>I/O</title>
-
- <section xml:id="avoid_echo">
- <title>Avoid using the "<literal>echo</literal>" command for output</title>
- <para>The behaviour of "<literal>echo</literal>" is not portable
- (e.g. System V, BSD, UCB and ksh93/bash shell builtin versions all
- slightly differ in functionality) and should be avoided if possible.
- POSIX defines the "<literal>printf</literal>" command as replacement
- which provides more flexible and portable behaviour.</para>
-
- <note>
- <title>&tag_kshonly;Use "<literal>print</literal>" and not "<literal>echo</literal>" in Korn Shell scripts</title>
- <para>Korn shell scripts should prefer the "<literal>print</literal>"
- builtin which was introduced as replacement for "<literal>echo</literal>".</para>
- <caution>
- <para>Use <literal>$ print -- ${varname}" #</literal> when there is the slightest chance that the
- variable "<literal>varname</literal>" may contain symbols like "-". Or better use "<literal>printf</literal>"
- instead, for example
-<programlisting>
-integer fx
-# do something
-print $fx
-</programlisting>
-may fail if "f" contains a negative value. A better way may be to use
-<programlisting>
-integer fx
-# do something
-printf "%d\n" fx
-</programlisting>
- </para>
- </caution>
- </note>
- </section>
-
- <section xml:id="use_redirect_not_exec_to_open_files">
- <title>&tag_ksh93only;Use <literal>redirect</literal> and not <literal>exec</literal> to open files</title>
- <para>Use <literal>redirect</literal> and not <literal>exec</literal> to open files - <literal>exec</literal>
- will terminate the current function or script if an error occurs while <literal>redirect</literal>
- just returns a non-zero exit code which can be caught.</para>
-<para>Example:
-<programlisting>
-if redirect 5&lt;/etc/profile ; then
- print "file open ok"
- head &lt;&amp;5
-else
- print "could not open file"
-fi
-</programlisting>
- </para>
- </section>
-
- <section xml:id="group_identical_redirections_together">
- <title>&tag_performance;Avoid redirections per command when the output goes into the same file,
- e.g. <literal>$ echo "foo" &gt;xxx ; echo "bar" &gt;&gt;xxx ; echo "baz" &gt;&gt;xxx #</literal></title>
- <para>Each of the redirections above trigger an
- <literal>|open()|,|write()|,|close()|</literal>-sequence. It is much
- more efficient (and faster) to group the rediction into a block,
- e.g. <literal>{ echo "foo" ; echo "bar" ; echo "baz" } &gt;xxx #</literal></para>
- </section>
-
-
- <section xml:id="avoid_using_temporary_files">
- <title>&tag_performance;Avoid the creation of temporary files and store the values in variables instead</title>
- <para>Avoid the creation of temporary files and store the values in variables instead if possible</para>
- <para>
- Example:
-<programlisting>
-ls -1 &gt;xxx
-for i in $(cat xxx) ; do
- do_something ;
-done
-</programlisting>
-can be replaced with
-<programlisting>
-x="$(ls -1)"
-for i in ${x} ; do
- do_something ;
-done
-</programlisting>
- </para>
- <note><para>ksh93 supports binary variables (e.g. <literal>typeset -b varname</literal>) which can hold any value.</para></note>
- </section>
-
-
- <section xml:id="create_subdirs_for_multiple_temporary_files">
- <title>If you create more than one temporary file create an unique subdir</title>
- <para>If you create more than one temporary file create an unique subdir for
- these files and make sure the dir is writable. Make sure you cleanup
- after yourself (unless you are debugging).
- </para>
- </section>
-
-
- <section xml:id="use_dynamic_file_descriptors">
- <title>&tag_ksh93only;Use {n}&lt;file instead of fixed file descriptor numbers</title>
- <para>When opening a file use {n}&lt;file, where <envar>n</envar> is an
- integer variable rather than specifying a fixed descriptor number.</para>
- <para>This is highly recommended in functions to avoid that fixed file
- descriptor numbers interfere with the calling script.</para>
-<example><title>Open a network connection and store the file descriptor number in a variable</title>
-<programlisting>
-function cat_http
-{
- integer netfd
-
-...
-
- # open TCP channel
- redirect {netfd}&lt;&gt;"/dev/tcp/${host}/${port}"
-
- # send HTTP request
- request="GET /${path} HTTP/1.1\n"
- request+="Host: ${host}\n"
- request+="User-Agent: demo code/ksh93 (2007-08-30; $(uname -s -r -p))\n"
- request+="Connection: close\n"
- print "${request}\n" &gt;&amp;${netfd}
-
- # collect response and send it to stdout
- cat &lt;&amp;${netfd}
-
- # close connection
- exec {netfd}&lt;&amp;-
-
-...
-
-}
-</programlisting>
-</example>
- </section>
-
-
- <section xml:id="use_inline_here_documents">
- <title>&tag_ksh93only;&tag_performance;Use inline here documents
- instead of <literal>echo "$x" | command</literal></title>
- <para>Use inline here documents, for example
-<programlisting>
-command &lt;&lt;&lt; $x
-</programlisting>
- rather than
-<programlisting>
-print -r -- "$x" | command
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="use_read_r">
- <title>&tag_ksh93only;Use the <literal>-r</literal> option of <literal>read</literal> to read a line</title>
- <para>Use the <literal>-r</literal> option of <literal>read</literal> to read a line.
- You never know when a line will end in <literal>\</literal> and without a
- <literal>-r</literal> multiple
- lines can be read.</para>
- </section>
-
-
- <section xml:id="print_compound_variables_using_print_C">
- <title>&tag_ksh93only;Print compound variables using <literal>print -C varname</literal> or <literal>print -v varname</literal></title>
- <para>Print compound variables using <literal>print -C varname</literal> or
- <literal>print -v varname</literal> to make sure that non-printable characters
- are correctly encoded.</para>
-<example><title>Print compound variable with non-printable characters</title>
-<programlisting>
-compound x=(
- a=5
- b="hello"
- c=(
- d=9
- e="$(printf "1\v3")" <co xml:id="co.vertical_tab1" />
- )
-)
-print -v x
-</programlisting>
-<para>will print:</para>
-<screen>
-<computeroutput>(
- a=5
- b=hello
- c=(
- d=9
- e=$'1\0133' <co xml:id="co.vertical_tab2" />
- )
-)</computeroutput>
-</screen>
-<calloutlist>
- <callout arearefs="co.vertical_tab1 co.vertical_tab2">
- <para>vertical tab, <literal>\v</literal>, octal=<literal>\013</literal>.</para>
- </callout>
-</calloutlist>
-</example>
- </section>
-
- <section xml:id="command_name_before_redirections">
- <title>Put the command name and arguments before redirections</title>
- <para>Put the command name and arguments before redirections.
- You can legally do <literal>$ &gt; file date</literal> instead of <literal>date &gt; file</literal>
- but don't do it.</para>
- </section>
-
- <section xml:id="enable_gmacs_editor_mode_for_user_prompts">
- <title>&tag_ksh93only;Enable the <literal>gmacs</literal> editor
- mode when reading user input using the <literal>read</literal> builtin</title>
- <para>Enable the <literal>gmacs</literal>editor mode before reading user
- input using the <literal>read</literal> builtin to enable the use of
- cursor+backspace+delete keys in the edit line</para>
-<example><title>Prompt user for a string with gmacs editor mode enabled</title>
-<programlisting>
-set -o gmacs <co xml:id="co.enable_gmacs" />
-typeset inputstring="default value"
-...
-read -v<co xml:id="co.read_v" /> inputstring<co xml:id="co.readvar" />?"Please enter a string: "<co xml:id="co.prompt" />
-...
-printf "The user entered the following string: '%s'\n" "${inputstring}"
-
-...
-</programlisting>
-<calloutlist>
- <callout arearefs="co.enable_gmacs">
- <para>Enable gmacs editor mode.</para>
- </callout>
- <callout arearefs="co.read_v">
- <para>The value of the variable is displayed and used as a default value.</para>
- </callout>
- <callout arearefs="co.readvar">
- <para>Variable used to store the result.</para>
- </callout>
- <callout arearefs="co.prompt">
- <para>Prompt string which is displayed in stderr.</para>
- </callout>
-</calloutlist>
-</example>
- </section>
- </section><!-- end of I/O -->
-
-
-
-
-
-
- <section xml:id="math">
- <title>Math</title>
-
- <section xml:id="use_builtin_arithmetic_expressions">
- <title>&tag_kshonly;&tag_performance;Use builtin arithmetic expressions instead of external applications</title>
- <para>Use builtin (POSIX shell) arithmetic expressions instead of
- <filename>expr</filename>,
- <filename>bc</filename>,
- <filename>dc</filename>,
- <filename>awk</filename>,
- <filename>nawk</filename> or
- <filename>perl</filename>.
- </para>
- <note>
- <para>ksh93 supports C99-like floating-point arithmetic including special values
- such as
- <simplelist type="inline">
- <member>+Inf</member>
- <member>-Inf</member>
- <member>+NaN</member>
- <member>-NaN</member>
- </simplelist>.
- </para>
- </note>
- </section>
-
-
- <section xml:id="use_floating_point_arithmetic_expressions">
- <title>&tag_ksh93only; Use floating-point arithmetic expressions if
- calculations may trigger a division by zero or other exceptions</title>
- <para>Use floating-point arithmetic expressions if calculations may
- trigger a division by zero or other exceptions - floating point arithmetic expressions in
- ksh93 support special values such as <literal>+Inf</literal>/<literal>-Inf</literal> and
- <literal>+NaN</literal>/<literal>-NaN</literal> which can greatly simplify testing for
- error conditions, e.g. instead of a <literal>trap</literal> or explicit
- <literal>if ... then... else</literal> checks for every sub-expression
- you can check the results for such special values.
- </para>
- <para>Example:
-<screen>
-$ <userinput>ksh93 -c 'integer i=0 j=5 ; print -- "x=$((j/i)) "'</userinput>
-<computeroutput>ksh93: line 1: j/i: divide by zero</computeroutput>
-$ <userinput>ksh93 -c 'float i=0 j=-5 ; print -- "x=$((j/i)) "'</userinput>
-<computeroutput>x=-Inf</computeroutput>
-</screen>
- </para>
- </section>
-
-
- <section xml:id="use_printf_a_for_passing_float_values">
- <title>&tag_ksh93only; Use <literal>printf "%a"</literal> when passing floating-point values</title>
- <para>Use <literal>printf "%a"</literal> when passing floating-point values between scripts or
- as output of a function to avoid rounding errors when converting between
- bases.</para>
- <para>
- Example:
-<programlisting>
-function xxx
-{
- float val
-
- (( val=sin(5.) ))
- printf "%a\n" val
-}
-float out
-(( out=$(xxx) ))
-xxx
-print -- $out
-</programlisting>
-This will print:
-<programlisting>
--0.9589242747
--0x1.eaf81f5e09933226af13e5563bc6p-01
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="put_constants_into_readonly_variables">
- <title>&tag_kshonly;&tag_performance;Put constant values into readonly variables</title>
- <para>Put constant values into readonly variables</para>
- <para>For example:
-<programlisting>
-float -r M_PI=3.14159265358979323846
-</programlisting>
-or
-<programlisting>
-float M_PI=3.14159265358979323846
-readonly M_PI
-</programlisting>
- </para>
- </section>
-
-
- <section xml:id="avoid_unnecessary_string_number_conversions">
- <title>&tag_kshonly;&tag_performance;Avoid string to number
- (and/or number to string) conversions in arithmetic expressions
- expressions</title>
- <para>Avoid string to number and/or number to string conversions in
- arithmetic expressions expressions to avoid performance degradation
- and rounding errors.</para>
- <example><title>(( x=$x*2 )) vs. (( x=x*2 ))</title>
-<programlisting>
-float x
-...
-(( x=$x*2 ))
-</programlisting>
-<para>
-will convert the variable "x" (stored in the machine's native
-<literal>|long double|</literal> datatype) to a string value in base10 format,
-apply pattern expansion (globbing), then insert this string into the
-arithmetic expressions and parse the value which converts it into the internal |long double| datatype format again.
-This is both slow and generates rounding errors when converting the floating-point value between
-the internal base2 and the base10 representation of the string.
-</para>
-<para>
-The correct usage would be:
-</para>
-<programlisting>
-float x
-...
-(( x=x*2 ))
-</programlisting>
-<para>
-e.g. omit the '$' because it's (at least) redundant within arithmetic expressions.
-</para>
- </example>
-
-
- <example><title>x=$(( y+5.5 )) vs. (( x=y+5.5 ))</title>
-<programlisting>
-float x
-float y=7.1
-...
-x=$(( y+5.5 ))
-</programlisting>
-<para>
-will calculate the value of <literal>y+5.5</literal>, convert it to a
-base-10 string value amd assign the value to the floating-point variable
-<literal>x</literal> again which will convert the string value back to the
-internal |long double| datatype format again.
-</para>
-<para>
-The correct usage would be:
-</para>
-<programlisting>
-float x
-float y=7.1
-...
-(( x=y+5.5 ))
-</programlisting>
-<para>
-i.e. this will save the string conversions and avoid any base2--&gt;base10--&gt;base2-conversions.
-</para>
- </example>
- </section>
-
-
- <section xml:id="set_lc_numeric_when_using_floating_point">
- <title>&tag_ksh93only;Set <envar>LC_NUMERIC</envar> when using floating-point constants</title>
- <para>Set <envar>LC_NUMERIC</envar> when using floating-point constants to avoid problems with radix-point
- representations which differ from the representation used in the script, for example the <literal>de_DE.*</literal> locale
- use ',' instead of '.' as default radix point symbol.</para>
- <para>For example:
-<programlisting>
-# Make sure all math stuff runs in the "C" locale to avoid problems with alternative
-# radix point representations (e.g. ',' instead of '.' in de_DE.*-locales). This
-# needs to be set _before_ any floating-point constants are defined in this script)
-if [[ "${LC_ALL}" != "" ]] ; then
- export \
- LC_MONETARY="${LC_ALL}" \
- LC_MESSAGES="${LC_ALL}" \
- LC_COLLATE="${LC_ALL}" \
- LC_CTYPE="${LC_ALL}"
- unset LC_ALL
-fi
-export LC_NUMERIC=C
-...
-float -r M_PI=3.14159265358979323846
-</programlisting>
- </para>
-
- <note><para>The environment variable <envar>LC_ALL</envar> always overrides all other <envar>LC_*</envar> variables,
- including <envar>LC_NUMERIC</envar>. The script should always protect itself against custom <envar>LC_NUMERIC</envar> and
- <envar>LC_ALL</envar> values as shown in the example above.
- </para></note>
- </section>
-
-
-
- </section><!-- end of math -->
-
-
-
-
-
-
- <section xml:id="misc">
- <title>Misc</title>
-
- <section xml:id="debug_use_lineno_in_ps4">
- <title>Put <literal>[${LINENO}]</literal> in your <envar>PS4</envar></title>
- <para>Put <literal>[${LINENO}]</literal> in your <envar>PS4</envar> prompt so that you will get line
- numbers with you run with <literal>-x</literal>. If you are looking at performance
- issues put <literal>$SECONDS</literal> in the <envar>PS4</envar> prompt as well.</para>
- </section>
-
- </section><!-- end of misc -->
-
-
-
-
-</section><!-- end of RULES -->
-
-
-
-
-</article>
View
28 usr/src/pkg/manifests/SUNWcs.mf
@@ -238,9 +238,6 @@ $(i386_ONLY)dir path=usr/sbin/$(ARCH32)
dir path=usr/sbin/$(ARCH64)
dir path=usr/share
dir path=usr/share/doc group=other
-dir path=usr/share/doc/ksh
-dir path=usr/share/doc/ksh/images
-dir path=usr/share/doc/ksh/images/callouts
dir path=usr/share/lib
dir path=usr/share/lib/mailx
dir path=usr/share/lib/pub
@@ -1426,31 +1423,6 @@ file path=usr/sbin/volcopy mode=0555
file path=usr/sbin/wall group=tty mode=2555
file path=usr/sbin/zdump mode=0555
file path=usr/sbin/zic mode=0555
-file path=usr/share/doc/ksh/COMPATIBILITY
-file path=usr/share/doc/ksh/DESIGN
-file path=usr/share/doc/ksh/OBSOLETE
-file path=usr/share/doc/ksh/README
-file path=usr/share/doc/ksh/RELEASE
-file path=usr/share/doc/ksh/TYPES
-file path=usr/share/doc/ksh/images/callouts/1.png
-file path=usr/share/doc/ksh/images/callouts/10.png
-file path=usr/share/doc/ksh/images/callouts/2.png
-file path=usr/share/doc/ksh/images/callouts/3.png
-file path=usr/share/doc/ksh/images/callouts/4.png
-file path=usr/share/doc/ksh/images/callouts/5.png
-file path=usr/share/doc/ksh/images/callouts/6.png
-file path=usr/share/doc/ksh/images/callouts/7.png
-file path=usr/share/doc/ksh/images/callouts/8.png
-file path=usr/share/doc/ksh/images/callouts/9.png
-file path=usr/share/doc/ksh/images/tag_bourne.png
-file path=usr/share/doc/ksh/images/tag_i18n.png
-file path=usr/share/doc/ksh/images/tag_ksh.png
-file path=usr/share/doc/ksh/images/tag_ksh88.png
-file path=usr/share/doc/ksh/images/tag_ksh93.png
-file path=usr/share/doc/ksh/images/tag_l10n.png
-file path=usr/share/doc/ksh/images/tag_perf.png
-file path=usr/share/doc/ksh/shell_styleguide.docbook
-file path=usr/share/doc/ksh/shell_styleguide.html
file path=usr/share/lib/mailx/mailx.help
file path=usr/share/lib/mailx/mailx.help.~
file path=usr/share/lib/tabset/3101
View
23 usr/src/tools/aw/aw.c
@@ -550,29 +550,6 @@ main(int argc, char *argv[])
newae(as, "--traditional-format");
/*
- * This is a support hack to rewrite code for the compiler
- * which should probably cause an assembler programmer to recode
- * - so, generate a warning in this case.
- *
- * -K was dropped begining with version 2.18.
- */
- {
- struct aelist *as_ver = newael();
- struct aelist *ggrep = newael();
-
- newae(as_ver, as_pgm);
- newae(as_ver, "--version");
- newae(ggrep, "/usr/bin/ggrep");
- newae(ggrep, "-q");
- newae(ggrep, "-E");
- newae(ggrep, "2.1[567]");
- code = pipeline(aeltoargv(as_ver), aeltoargv(ggrep));
- if (code == 0) {
- newae(as, "-K");
- }
- }
-
- /*
* Walk the argument list, translating as we go ..
*/
while (--argc > 0) {
Please sign in to comment.
Something went wrong with that request. Please try again.