Return to ksh.1 CVS log

Up to [MW Coherent from dump] / coherent / a / usr / bob / korn

coherent

.nr OJ 1 \" Job Control
.nr OE 1 \" Command Editing
.nr OB 1 \" BSD enhanced ulimit options
.ds OK [\|
.ds CK \|]
.TH KSH "MWC In-House Docs"
.SH NAME
ksh \- Korn Shell (Public Domain)
.SH SYNOPSIS
\fBksh\fP
[\fB\-\fIset_options\fR] [\fB\-st\fP] [\fB\-c\fP \fIcommand\fP]
[\fIfile\fP [\fIargument ...\fP]]
.SH INTRODUCTION
This document only summarizes the System V, release 2 shell features.
All of the System V features except for "restricted mode"
and the CDPATH and MAIL* variables are implemented.
See also the BUGS section.
.LP
Features of the Korn shell are described in more detail.
Only a subset of the Korn shell features are currently implemented.
.SH DESCRIPTION
.SS Command syntax
The ``#'' character begins a one-line comment,
unless the ``#'' occurs inside a word.
The tokens ``;'', ``|'', ``&'', ``;;'', ``||'', ``&&'', ``('', and ``)''
stand by themselves.
A \fIword\fP is a sequence of any other non-whitespace characters,
which may also contain quoted strings
(quote character are ``\''', ``"'', ``\`'',
or a matching ``${ }'' or ``$( )'' pair).
A \fIname\fP is an unquoted word made up of letters, digits, or ``_''.
Any number of whitespace characters (space and tab) may separate words and tokens.
.LP
In the following syntax, { ... }? indicates an optional thing,
{ ... }* indicates zero or more repetitions, { ... | ... } indicates alternatives.
.de S
.br
\\$1
.br
..
.IP statement:
.S "\fB(\fP list \fB)\fP"
.S "\fB{\fP list \fB;\fP \fB}\fP"
.S "\fBfor\fP name { \fBin\fP { word }* }? \fBdo\fP list \fB;\fP \fBdone\fP"
.S "{ \fBwhile\fP | \fBuntil\fP } list \fB;\fP \fBdo\fP list \fB;\fP \fBdone\fP"
.S "\fBif\fP list \fB;\fP \fBthen\fP list \fB;\fP { \fBelif\fP list \fB;\fP \fBthen\fP list \fB;\fP }* { \fBelse\fP list \fB;\fP }?\fBfi\fP"
.S "\fBcase\fP name \fBin\fP { \fB(\fP word { \fB|\fP word } \fB)\fP list \fB;;\fP }* \fBesac\fP"
.S "\fBfunction\fP name \fB{\fP list \fB;\fP \fB}\fP"
.S "name \fB() {\fP list \fB;\fP \fB}\fP"
.S "\fBtime\fP pipe"
The opening parenthesis of the pattern is optional. 
Redirection may occur at the beginning or end of a statement.
.IP command:
.S "{ name=word }* { word }*"
Redirection may occur anywhere in a command.
.IP list:
.S "cond"
.S "cond \fB;\fP list"
.S "cond \fB&\fP list"
.IP cond:
.S "pipe"
.S "pipe \fB&&\fP cond"
.S "pipe \fB||\fP cond"
.IP pipe:
.S "statement { \fB|\fP statement }*"
.SS Alias expansion
Alias expansion occurs when the first word of a statement is a defined alias,
except when that alias is already being expanded.
It also occurs after the expansion of an alias whose definition ends with a space.
.SS Shell variables
The following standard special variables exist:
\fB!\fP, \fB#\fP, \fB$\fP, \fB\-\fP, \fB?\fP.
.IP CDPATH
Not yet implemented.
.IP ENV
If this variable is set at start-up
(after any profile files are executed),
the expanded value is used as shell start-up file.
It typically contains function and alias definitions.
.IP FCEDIT
The editor used by the \fIfc\fP command.
.IP IFS
\fIInternal field separator\fP,
used during substitution and the \fIread\fP command.
.IP HOME
The default directory for the \fIcd\fP command.
.IP "MAIL MAILCHECK MAILPATH"
Not yet implemented.
.IP PATH
The search path for executable commands and \fB.\fP'd files.
.IP "PS1 PS2"
\fBPS1\fP is the primary prompt for interactive shells.
Dollar substitution is performed, and \fB!\fP is replaced
with the command number (see \fIfc\fP).
.IP "PWD OLDPWD"
The current and previous working directories.
.IP SECONDS
The number of seconds since the shell was started.
.SS Substitution
In addition to the System Vr2 substitutions,
the following are available.
.IP "$(command)"
Like `command`, but no escapes are recognized.
.IP "$(<file)"
Equivalent to $(cat file), but without forking.
.IP "${#var}"
The length of the string value of \fIvar\fP,
or the number of arguments if \fIvar\fP is \fB*\fP or \fB@\fP.
.IP "${var#pattern} ${var##pattern}"
If \fIpattern\fP matches the beginning of the value of \fIvar\fP,
the matched text is deleted from the result of substitution.
A single \fB#\fP results in the shortest match,
two \fB#\fP's results in the longest match.
.IP "${var%pattern} ${var%%pattern}"
Like \fB#\fP substition, but deleting from the end of the value.
.SS Expressions
Expressions can be used with the \fBlet\fP command,
as numeric arguments to the \fBtest\fP command,
and as the value of an assignment to an integer variable.
.LP
Expression may contain alpha-numeric variable identifiers and integer constants
and may be combined with the following operators.
[list them]
.SS Command execution
After evaluation of keyword assignments and arguments,
the type of command is determined.
A command may execute a shell function, a shell built-in,
or an executable file.
.LP
Any keyword assignments are then performed according to
the type of command.
In function calls assignments are local to the function.
Assignments in built-in commands marked with a \(dg persist,
otherwise they are temporary.
Assignments in executable commands are exported to the sub-process
executing the command.
.LP
There are several built-in commands.
.IP ":"
Only expansion and assignment are performed.
This is the default if a command has no arguments.
.IP ". \fIfile\fP"
Execute the commands in \fIfile\fP without forking.
The file is searched in the directories of $PATH.
Passing arguments is not implemented.
.IP "alias [-d] [\fIname\fB=\fIvalue\fI ...]\fR"
Without arguments, \fBalias\fP lists all aliases and their values.
For any name without a value, its value is listed.
Any name with a value defines an alias, see "Alias Expansion" above.
Korn's tracked aliases are not implemented,
but System V command hashing is (see "hash").
.IP "bind [-m] [\fIkey_sequence=binding_name ...\fP]"
See section \fBInteractive Input Line Editing\fP for further details.
.IP "break [\fIlevels\fP]"
.IP "builtin \fIcommand arg ...\fP"
\fICommand\fP is executed as a built-in command.
.IP "cd [\fIpath\fP]"
Set the working directory to \fIpath\fP.
If \fIpath\fP is missing, the home directory ($HOME) is used.
If \fIpath\fP is \fB\-\fP, the previous working directory is used.
The PWD and OLDPWD variables are reset.
The System V two argument form is not implemented.
.IP "continue [\fIlevels\fP]"
.IP "echo ..."
\fIEcho\fP is replaced with the alias echo='print' in the Korn shell.
.IP "eval \fIcommand ...\fP"
.IP "exec \fIcommand arg ...\fP"
The executable command is executed without forking.
If no arguments are given, any IO redirection is permanent.
.IP "exit [\fIstatus\fP]"
.IP "fc [\fB\-l\fP] [\fB\-n\fP] [\fIfirst\fP [\fIlast\fP]]"
A simple subset of Korn's ``fix command''.
\fIFirst\fP and \fIlast\fP select commands.
Commands can be selected by history number,
or a string specifing the most recent command starting with that string.
The \fB\-l\fP option lists the command on stdout,
and \fB\-n\fP inhibits the default command numbers.
Without \fB\-l\fP, the selected commands can be edited by
the \fB$FCEDIT\fP editor, then executed by the shell.
.IP "\fBfc \-s\fP [\fIold\fB=\fInew\fR] [\fIcommand\fP]"
Re-execute the selected command (the previous command by default)
after performing the optional substitution of \fIold\fP with \fInew\fP.
This non-standard command is usually accessed with the predefined alias r="fc -s".
.IP "getopts"
See the attached manual page.
.IP "hash [\fB\-r\fP] [\fIname ...\fP]"
Without arguments, any hashed executable command pathnames are listed.
The \fB\-r\fP flag causes all hashed commands to be removed.
Each \fIname\fP is searched as if it where a command name
and added to the hash table if it is an executable command.
.IP "kill [-l] [\fB\-\fIsignal\fR] \fIprocess\fP ..."
Send a signal (TERM by default) to the named process.
The signal may be specified as a number or a mnemonic from <signal.h>
with the SIG prefix removed.
If option \fB-l\fP is specified, list all known signal types.
.IP "let [\fIexpression ...\fP]"
Each expression is evaluated, see "Expressions" above.
A zero status is returned if the last expression evaluates
to a non-zero value, otherwise a non-zero status is returned.
.IP "\fBprint\fP [\fB\-nreu\fIn\fR] [\fIargument ...\fP]"
\fBPrint\fP prints its arguments on the standard output,
separated by spaces, and terminated with a newline.
The \fB\-n\fP option eliminates the newline.
If option \fB-u\fIn\fR is specified, output is sent to shell
file descriptor \fIn\fP instead of \fIstdout\fR.
.PP
By default, certain C escapes are translated.
These include \eb, \ef, \en, \er, \et, \ev, and \e### (# is an octal digit).
\ec is equivalent to the \fB\-n\fP option.
This expansion may be inhibitted with the \fB\-r\fP option,
and may be re-enabled with the addition of the \fB\-e\fP option.
.IP "read [\fB\-ru\fIn\fR] \fIname ...\fP"
The first variable name may be of the form \fIname\fB?\fIprompt\fR.
.IP "readonly [\fIname ...\fP]"
.IP "return [\fIstatus\fP]"
.ta 5n 10n 30n
.de O
.br
\t\\$1\t\\$2\t\\$3
..
.IP "set [\fB-\fP\fI[a-z]\fP] [\fB-o\fP \fIkeyword\fP] ..."
Set (\fB\-\fP) or clear (\fB+\fP) a shell option:
.O \-a allexport "all new variable are created with export attribute"
.O \-e errexit "exit on non-zero status [incorrect]"
.O "" bgnice "background jobs are run with lower priority"
.if \n(OE \{
.O "" emacs "BRL emacs-like line editing"\}
.O "" ignoreeof "shell will not exit of EOF, must use \fIexit\fP"
.O \-k keyword "variable assignments are recognized anywhere in command"
.O "" markdirs "[not implemented]"
.if \n(OJ \{
.O \-m monitor "job control enabled (default for interactive shell)"\}
.O \-n noexec "compile input but do not execute (ignored if interactive)"
.O \-f noglob "don't expand filenames"
.O \-u nounset "dollar expansion of unset variables is an error"
.O \-v verbose "echo shell commands on stdout when compiling"
.O \-h trackall "add command pathnames to hash table"
.O \-x xtrace "echo simple commands while executing"
.IP "set [\fB\-\-\fP] \fIarg ...\fP"
Set shell arguments.
.IP "shift [\fInumber\fP]"
.IP "test"
See the attached manual page.
.IP "times"
.IP "trap [\fIhandler\fP] [\fIsignal ...\fP]"
.IP "typeset [\fB\(+-irtx\fP] [\fIname\fP[\fB=\fIvalue\fR] ...]"
If no arguments are given, lists all variables and their attributes.
.PP
If options but no names are given, lists variables with specified
attributes, and their values if unless ``+'' is used.
.PP
If names are given, set the attributes of the named variables.
Variables may also be assigned a value.
If used inside a function, the created variable are local to the function.
.PP
The attributes are as follows.
.ta 5n 10n
\t\-i\tThe variable's value is stored as an integer.
.br
\t\-x\tThe variable is exported to the enviroment.
.br
\t\-r\tThe variable is read-only cannot be reassigned a value.
.br
\t\-t\tTrace (not implemented).
.br
\t\-f\tList functions instead of variable.
.IP "umask [\fIvalue\fP]"
.IP "unalias [-d] \fIname ...\fP"
The aliases for the given names are removed.
.IP "unset [\fB\-f\fP] \fIname ...\fP"
.IP "wait [\fIprocess-id\fP]"
.IP "whence [\fB\-v\fP] name ..."
For each name, the type of command is listed.
The \fB\-v\fP flag causes function and alias values to be listed.
.if \n(OJ \{.SS Job Control
Job control features are enabled by the
\fB\-m\fP or \fB\-o monitor\fP flags.
When job control is enabled,
background commands and foreground commands that have been stopped
(usually by a
.SM SIGTSTP
signal generated by typing
.IR ^Z\^ )
are placed into separate individual
.IR "process groups" .
The following commands are used to manipulate these process groups:
.PP
.PD 0
.TP "\w'\fBkill\fP \*(OK \fIjob\fP \*(CK\ \ \ 'u"
\fBjobs\fP
Display information about the controlled jobs.
The job number is given preceeded by a percent sign,
followed by a plus sign if it is the ``current job'',
or by a minus sign if it is the ``previous job'',
then the process group number for the job,
then the command.
.TP
kill [\fB\-\fIsignal\fR] \fIjob\fP ...
Send a signal (TERM by default) to the named job process group.
.TP
\fBfg\fP \*(OK \fIjob\fP \*(CK
Resume the stopped foreground job in the foreground.
If the process group
.I n
is not specified then the ``current job'' is resumed.
.TP
\fBbg\fP \*(OK \fIjob\fP \*(CK
Resume the stopped foreground job in the background.
If the process group
.I n
is not specified then the ``current job'' is resumed.
.PD
.PP
The \fBfg\fP, \fBbg\fP, \fBkill\fP, and \fBwait\fP commands
may refer to jobs with the following ``percent'' sequences.
The percent sign is optional with the fg and bg commands.
.PP
.PD 0
.TP "\w'\fBbg\fP \*(OK \fIn\fP \*(CK\ \ \ 'u"
.BR %+ ( %\- )
If there is a ``current job'' (``previous job''),
then that job is selected.
.TP
.BI % n
If the specified job number is one of the known jobs,
then that job is selected.
.TP
.BI % string
If the string matches the initial part of a job's command,
then that job is selected.
.TP
.BI %? string
As above, but the string may match any portion of the command.
.PD\}
.br
.if \n(OE \{.SS "Interactive Input Line Editing"
When the
.B emacs
option is set,
interactive input line editing is enabled.
This mode is slightly different from the emacs mode in AT&T's KornShell.
In this mode various
.I "editing commands"
(typically bound to one or more control characters)
cause immediate actions without waiting for a new-line.
Several
.I "editing commands"
are bound to particular control characters
when the shell is invoked;
these bindings can be changed using the following commands:
.br
.PP
.PD 0
.TP 2i
\fBbind\fP
The current bindings are listed.
.TP
\fBbind\fP \*(OK \fIstring\fP \*(CK = \*(OK \fIediting-command\fP \*(CK
The specified
.I "editing command\^"
is bound to the given
.IR string ,
which should consist of a control character
(which may be written using ``caret notation'' \fB^\fP\fIx\fP\|),
optionally preceded by one of the two prefix characters.
Future input of the
.I string
will cause the
.I "editing command\^"
to be immediately invoked.
.br
.TP
\fBbind -m\fP \*(OK \fIstring\fP \*(CK = \*(OK \fIsubstitute\fP \*(CK
The specified input
.I string
will afterwards be immediately replaced by the given
.I substitute
string,
which may contain
.IR "editing commands" .
.PD
.PP
The following
.I "editing commands"
are available;
first the command name is given
followed by its default binding (if any)
using caret notation
(note that the ASCII
.SM ESC
character is written as \s-1^[\s0\|),
then the editing function performed is decribed.
Note that
.I "editing command"
names are used only with the
.B bind
command.
Furthermore,
many
.I "editing commands"
are useful only on terminals with a visible cursor.
The default bindings were chosen to resemble corresponding EMACS key bindings.
.br
.PP
.PD 0
.TP "\w'\fBdelete-word-backward\ \ ^W\fP\ \ \ 'u"
\fBabort\ \ ^G\fP
Useful as a response to a request for a
.B search-history
pattern in order to abort the search.
.br
.TP
\fBauto-insert\fP
Simply causes the character to appear as literal input.
(Most ordinary characters are bound to this.)
.br
.TP
\fBbackward-char\ \ ^B\fP
Moves the cursor backward one character.
.br
.TP
\fBbackward-word\ \ ^[\|b\fP
Moves the cursor backward to the beginning of a word;
words are delimited by the current setting of \fB\s-1IFS\s0\fP.
.br
.TP
\fBbeginning-of-line\ \ ^A\fP
Moves the cursor to the beginning of the input line
(after the prompt string).
.br
.TP
\fBcomplete\ \ ^[\|^[\fP
Automatically completes as much as is unique of the hashed command name
or the file name containing the cursor.
If the entire remaining command or file name is unique
a space is printed after its completion,
unless it is a directory name in which case
.B /
is postpended.
If there is no hashed command or file name with the current partial word
as its prefix,
a bell character is output (usually causing a ``beep'').
.br
.TP
\fBcomplete-command\ \ ^X^[\fP
Automatically completes as much as is unique of the hashed command name
having the partial word up to the cursor as its prefix,
as in the
.B complete
command described above.
Only command and function names seen since the last
.B "hash \-r"
command are available for completion;
the
.B "hash"
command may be used to register additional names.
.br
.TP
\fBcomplete-file\ \ ^X\|^X\fP
Automatically completes as much as is unique of the file name
having the partial word up to the cursor as its prefix,
as in the
.B complete
command described above.
.br
.TP
\fBdelete-char-backward\ \ ^H\fP
Deletes the character before the cursor.
.br
.TP
\fBdelete-char-forward\ \ ^D\fP
Deletes the character after the cursor.
.br
.TP
\fBdelete-word-backward\ \ ^W\fP
Deletes characters before the cursor back to the beginning of a word.
.br
.TP
\fBdelete-word-forward\ \ ^[\|d\fP
Deletes characters after the cursor up to the end of a word.
.br
.TP
\fBdown-history\ \ ^N\fP
Scrolls the history buffer forward one line (later).
Each input line originally starts just after
the last entry in the history buffer,
so
.B down-history
is not useful until either
.B search-history
or
.B up-history
has been performed.
.br
.TP
\fBend-of-line\ \ ^E\fP
Moves the cursor to the end of the input line.
.br
.TP
\fBeot\ \ ^_\fP
Acts as an end-of-file;
this is useful because edit-mode input
disables normal terminal input canonicalization.
.br
.TP
\fBforward-char\ \ ^F\fP
Moves the cursor forward one position.
.br
.TP
\fBforward-word\ \ ^[\|f\fP
Moves the cursor forward to the end of a word.
.br
.TP
\fBkill-line\ \ ^U\fP
Deletes the entire input line.
.br
.TP
\fBkill-to-eol\ \ ^K\fP
Deletes the input from the cursor to the end of the line.
.br
.TP
\fBlist\ \ ^[\|?\fP
Prints a sorted, columnated list of hashed command names or file names
(if any) that can complete the partial word containing the cursor.
Directory names have
.B /
postpended to them,
and executable file names are followed by
.BR \(** .
.br
.TP
\fBlist-command\ \ ^X\|?\fP
Prints a sorted, columnated list of hashed command names
(if any) that can complete the partial word containing the cursor.
.br
.TP
\fBlist-file\fP
Prints a sorted, columnated list of file names
(if any) that can complete the partial word containing the cursor.
File type indicators are postpended as described under
.B list
above.
.br
.TP
\fBnewline\ \ ^J\ \fP\fIand\^\fP\fB\ ^M\fP
Causes the current input line to be processed by the shell.
(The current cursor position may be anywhere on the line.)
.br
.TP
\fBprefix-1\ \ ^[\fP
Introduces a 2-character command sequence.
.br
.TP
\fBprefix-2\ \ ^X\fP
Introduces a 2-character command sequence.
.br
.TP
\fBquote\ \ ^^\fP
The following character is taken literally
rather than as an
.IR "editing command" .
.br
.TP
\fBredraw\ \ ^L\fP
Reprints the prompt string and the current input line.
.br
.TP
\fBsearch-character\ \ ^]\fP
Search forward in the current line for the next keyboard character.
.br
.TP
\fBsearch-history\ \ ^R\fP
Enter incremental search mode.
The internal history list is searched backwards for commands matching the input.
An initial ``^'' in the search string anchors the search.
The escape key will leave search mode.
Other commands will be executed after leaving search mode.
Successive
.B search-history
commands continue searching backward
to the next previous occurrence of the pattern.
The history buffer retains only a finite number of lines;
the oldest are discarded as necessary.
.br
.ie \n(OX \{.TP
\fBstuff\ \ ^T\fP\}
.el \{.TP
\fBstuff\fP\}
On systems supporting it,
pushes the bound character back onto the terminal input
where it may receive special processing by the terminal handler.
.if \n(OX \{This is useful for the BRL
.B ^T
``mini-systat'' feature,
for example.\}
.br
.TP
\fBstuff-reset\fP
Acts like
.BR stuff\^ ,
then aborts input the same as an interrupt.
.br
.ie \n(OX \{.TP
\fBtranspose-chars\fP\}
.el \{.TP
\fBtranspose-chars\ \ ^T\fP\}
Exchanges the two characters on either side of the cursor.
.br
.TP
\fBup-history\ \ ^P\fP
Scrolls the history buffer backward one line (earlier).
.br
.TP
\fByank\ \ ^Y\fP
Inserts the most recently killed text string at the current cursor position.
.br
.TP
\fByank-pop\ \ ^[\|y\fP
Immediately after a
.BR yank ,
replaces the inserted text string with the
next previous killed text string.
.PD\}
.br
.SH FILES
~/.profile
.br
/etc/profile
.SH "SEE ALSO"
sh(1) on System V or Sun OS.
.LP
.I "UNIX Shell Programming,"
Stephan G. Kochan,
Patrick H. Wood,
Hayden.
.LP
.I "KornShell: Command and Programming Language (not yet published),"
Morris Bolsky and David Korn.
.SH AUTHORS
Based on the public domain 7th edition Bourne shell.
.LP
System V and Korn modifications by Eric Gisin,
with contributions by
Ron Natalie, Arnold Robbins, Doug Gwyn, Erik Baalbergen, AT&T.\" getopt(3)
.SH "DIFFERENCES FROM AT&T VERSION"
Vi editing mode is not implemented.
The \fBselect\fP statement is not implemented.
"\fBfc \-e \-\fP" is not implemented, use "\fBfc \-s\fP".
The variables \fBRANDOM\fP and \fBPPID\fP are not implemented.
Variable arrays are not implemented.
Variable attributes other than integer are not implemented.
The \fBERR\fP and \fBEXIT\fP traps are not implemented for functions.
Alias expansion is inhibited at the beginning of an alias definition
in the AT&T version.
.SH BUGS
Interactive shells will occasionally hang while waiting for a job.
.LP
The 8th bit is stripped in emacs mode.
.LP
Please report any other bugs by mail to [email protected] or [email protected].
.TH TEST 1 "January 1988" "Korn shell"
.ta 30n
.de X
.br
\\$1\t\\$2
..
.SH NAME
test \- test condition (Korn and 8th edition)
.SH SYNOPSIS
\fBtest\fP \fIexpression\fP
.br
\fB[\fP \fIexpression\fP \fB]\fP
.SH DESCRIPTION
\fBTest\f evalutates the \fIexpression\fP and returns zero status if true,
and non-zero status otherwise.
It is normally used as the controlling command of the \fBif\fP and \fBwhile\fP statements.
.LP
The following basic expressions are available.
.IP
.X "-r file" "file exists and is readable"
.X "-w file" "file exists and is writable"
.X "-x file" "file exists and is executable"
.X "-f file" "file is a regular file"
.X "-d file" "file is a directory"
.X "-c file" "file is a character special device"
.X "-b file" "file is a block special device"
.X "-p file" "file is a named pipe"
.X "-u file" "file mode has setuid bit"
.X "-g file" "file mode has setgid bit"
.X "-k file" "file mode has sticky bit"
.X "-s file" "file is not empty"
.X "-L file" "file is a symbolic link"
.X "-S file" "file is a socket"
.X "file -nt file" "first file is newer than second file"
.X "file -ot file" "first file is older than second file"
.X "file -ef file" "first file is the same file as second file"
.X "-t filedes" "file descriptor is a tty device"
.IP
.X "string" "string is not null"
.X "-z string" "string is null"
.X "-n string" "string is not null"
.X "string = string" "strings are equal"
.X "string != string" "strings are not equal"
.IP
.X "number -eq number" "numbers compare equal"
.X "number -ne number" "numbers compare not equal"
.X "number -ge number" "numbers compare greater than or equal"
.X "number -gt number" "numbers compare greater than"
.X "number -le number" "numbers compare less than or equal"
.X "number -lt number" "numbers compare less than"
.LP
The above basic expressions may be combined with the following operators.
.IP
.X "expr -o expr" "logical or"
.X "expr -a expr" "logical and"
.X "! expr" "logical not"
.X "( expr )" "grouping"
.SH AUTHOR
Erik Baalbergen. Modified by Arnold Robbins.
.rn LP P
.TH GETOPTS 1 "January 1988" "Korn shell"
.SH NAME
getopts \- parse command options
.SH SYNOPSIS
.B getopts
optstring name [arg ...]
.SH DESCRIPTION
.I getopts
is used by shell procedures
to parse positional parameters and to check for legal options.
It supports all applicable rules of the command syntax standard
(see Rules 3-10,
.IR intro (1)).
It should be used in place of the
.IR getopt (1)
command.
(See the
.BR \s-1WARNING\s0 ,
below.)
.PP
.I optstring
must contain the option letters the command using
.I getopts
will recognize;
if a letter is followed by a colon,
the option is expected to have an argument
which should be separated from it by white space.
.PP
Each time it is invoked,
.I getopts
will place the next option in the shell variable
.I name
and the index of the next argument to be processed in the shell variable
.BR \s-1OPTIND\s0 .
Whenever the shell or a shell procedure is invoked,
.B \s-1OPTIND\s0
is initialized to
.BR 1 .
.PP
When an option requires an option-argument,
.I getopts
places it in the shell variable
.BR \s-1OPTARG\s0 .
.P
If an illegal option is encountered,
.B ?\&
will be placed in
.IR name .
.P
When the end of the options is encountered,
.I getopts
exits with a non-zero exit status.
The special option
.RB `` \-\- ''
may be used to delimit the end of the options.
.P
By default,
.I getopts
parses the positional parameters.
If extra arguments
.RI ( arg
\&...) are given on the
.I getopts
command line,
.I getopts
will parse them instead.
.PP
So all new commands will adhere to the command syntax standard described in
.IR intro (1),
they should use
.IR getopts (1)
or
.IR getopt (3C)
to parse positional parameters
and check for options that are legal for that command
(see
.BR \s-1WARNINGS\s0 ,
below).
.SH EXAMPLE
The following fragment of a shell program
shows how one might process the arguments
for a command that can take the options
.B a
or
.BR b ,
as well as the option
.BR o ,
which requires an option-argument:
.PP
.RS
.nf
.ss 18
.ta +.5i +1i
\fBwhile getopts abo: c
do
	case $c in
	a\(bvb)	FLAGS=$FLAGS$c;;
	o)	OARG=$OPTARG;;
	\e?)	echo $USAGE 1>&2
		exit 2;;
	esac
done
shift OPTIND\-1\fP
.fi
.ta
.ss 12
.RE
.PP
This code will accept any of the following as equivalent:
.PP
.RS
.nf
.ss 18
\fBcmd \-a \-b \-o "xxx z yy" file
cmd \-a \-b \-o "xxx z yy" \-\- file
cmd \-ab \-o "xxx z yy" file
cmd \-ab \-o "xxx z yy" \-\- file\fP
.fi
.ss 12
.RE
.SH SEE ALSO
intro(1),
sh(1).
.br
getopt(3C)
in the
.IR "Programmer's Reference Manual" .
.br
.IR "UNIX System V Release 3.0 Release Notes" .
.SH WARNING
Although the following command syntax rule (see
.IR intro (1))
relaxations are permitted under the current implementation,
they should not be used because they may not be supported
in future releases of the system.
As in the
.B \s-1EXAMPLE\s0
section above,
.B a
and
.B b
are options,
and the option
.B o
requires an option-argument:
.PP
.RS
.nf
.ta +1i +1.5i
\fBcmd \-aboxxx file\fP	(Rule 5 violation: options with
	option-arguments must not be grouped with other options)
\fBcmd \-ab \-oxxx file\fP	(Rule 6 violation: there must be
	white space after an option that takes an option-argument)
.fi
.ta
.RE
.PP
Changing the value of the shell variable
.B \s-1OPTIND\s0
or parsing different sets of arguments
may lead to unexpected results.
.SH DIAGNOSTICS
.I getopts
prints an error message on the standard error output
when it encounters an option letter not included in
.IR optstring .

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.