'\" t

.\" $NetBSD: ksh.Man,v 1.23 2011/10/18 12:36:31 reed Exp $

.\"{{{}}}

.\"{{{ Notes about man page

.\" - use the pseudo-macros .sh( and .sh) to begin and end sh-specific

.\" text and .ksh( and .ksh) for ksh specific text.

.\" - put i.e., e.g. and etc. in italics

.\"}}}

.\"{{{ To do

.\" todo: Things not covered that should be:

.\" - distinguish (POSIX) special built-in's, (POSIX) regular built-in's,

.\" and sh/ksh weirdo built-in's (put S,R,X superscripts after command

.\" name in built-in commands section?)

.\" - need to be consistent about notation for `See section-name', `

.\" See description of foobar command', `See section section-name', etc.

.\" - need to use the term `external command' meaning `a command that is

.\" executed using execve(2)' (as opposed to a built-in command or

.\" function) for more clear description.

.\"}}}

.\"{{{ Title

.ksh(

.TH KSH 1 "August 19, 1996" "" "User commands"

.ksh)

.sh(

.TH SH 1 "August 19, 1996" "" "User commands"

.sh)

.\"}}}

.\"{{{ Name

.SH NAME

.ksh(

ksh \- Public domain Korn shell

.ksh)

.sh(

sh \- Public domain Bourne shell

.sh)

.\"}}}

.\"{{{ Synopsis

.SH SYNOPSIS

.ad l

.ksh(

\fBksh\fP

.ksh)

.sh(

\fBsh\fP

.sh)

[\fB\(+-abCefhikmnprsuvxX\fP] [\fB\(+-o\fP \fIoption\fP] [ [ \fB\-c\fP \fIcommand-string\fP [\fIcommand-name\fP] | \fB\-s\fP | \fIfile\fP ] [\fIargument\fP ...] ]

.ad b

.\"}}}

.\"{{{ Description

.SH DESCRIPTION

.ksh(

\fBksh\fP is a command interpreter that is intended for both

interactive and shell script use.

Its command language is a superset of the \fIsh\fP(1) shell language.

.ksh)

.sh(

\fBsh\fP is a re-implementation of the Bourne shell, a command

interpreter for both interactive and script use.

.sh)

.\"{{{ Shell Startup

.SS "Shell Startup"

The following options can be specified only on the command line:

.IP "\fB\-c\fP \fIcommand-string\fP"

the shell executes the command(s) contained in \fIcommand-string\fP

.IP \fB\-i\fP

interactive mode \(em see below

.IP \fB\-l\fP

login shell \(em see below

interactive mode \(em see below

.IP \fB\-s\fP

the shell reads commands from standard input; all non-option arguments

are positional parameters

.IP \fB\-r\fP

restricted mode \(em see below

.PP

In addition to the above, the options described in the \fBset\fP built-in

command can also be used on the command line.

.PP

If neither the \fB\-c\fP nor the \fB\-s\fP options are specified, the

first non-option argument specifies the name of a file the shell reads

commands from; if there are no non-option arguments, the shell reads

commands from standard input.

The name of the shell (\fIi.e.\fP, the contents of the \fB$0\fP) parameter

is determined as follows: if the \fB\-c\fP option is used and there is

a non-option argument, it is used as the name; if commands are being

read from a file, the file is used as the name; otherwise the name

the shell was called with (\fIi.e.\fP, argv[0]) is used.

.PP

A shell is \fBinteractive\fP if the \fB\-i\fP option is used or

if both standard input and standard error are attached to a tty.

An interactive shell has job control enabled (if available),

ignores the INT, QUIT and TERM signals, and prints prompts before

reading input (see \fBPS1\fP and \fBPS2\fP parameters).

For non-interactive shells, the \fBtrackall\fP option is on by default

(see \fBset\fP command below).

.PP

A shell is \fBrestricted\fP if the \fB\-r\fP option is used or if either

the basename of the name the shell is invoked with or the \fBSHELL\fP

parameter match the pattern *r*sh (\fIe.g.\fP, rsh, rksh, rpdksh, \fIetc.\fP).

The following restrictions come into effect after the shell processes

any profile and \fB$ENV\fP files:

.nr P2 \n(PD

.nr PD 0

.IP \ \ \(bu

the \fBcd\fP command is disabled

.IP \ \ \(bu

the \fBSHELL\fP, \fBENV\fP and \fBPATH\fP parameters can't be changed

.IP \ \ \(bu

command names can't be specified with absolute or relative paths

.IP \ \ \(bu

the \fB\-p\fP option of the \fBcommand\fP built-in can't be used

.IP \ \ \(bu

redirections that create files can't be used (\fIi.e.\fP, \fB>\fP,

\fB>|\fP, \fB>>\fP, \fB<>\fP)

.nr PD \n(P2

.PP

A shell is \fBprivileged\fP if the \fB\-p\fP option is used or if

the real user-id or group-id does not match the effective user-id

or group-id (see \fIgetuid\fP(2), \fIgetgid\fP(2)).

A privileged shell does not process $HOME/.profile nor the \fBENV\fP

parameter (see below), instead the file /etc/suid_profile is processed.

Clearing the privileged option causes the shell to set its effective

user-id (group-id) to its real user-id (group-id).

.PP

If the basename of the name the shell is called with (\fIi.e.\fP, argv[0])

starts with \fB\-\fP or if the \fB\-l\fP option is used, the shell is assumed

to be a login shell and the shell reads and executes the contents of

\fB/etc/profile\fP, \fB$HOME/.profile\fP and \fB$ENV\fP if they exist and are

readable.

.PP

If the \fBENV\fP parameter is set when the shell starts (or, in the

case of login shells, after any profiles are processed), its value

is subjected to parameter, command, arithmetic and tilde substitution and

the resulting file (if any) is read and executed.

If the \fBENV\fP parameter is not set (and not null) the file \fB$HOME/.kshrc\fP

is included (after the above mentioned substitutions have been performed).

.PP

The exit status of the shell is 127 if the command file specified

on the command line could not be opened, or non-zero if a fatal syntax

error occurred during the execution of a script.

In the absence of fatal errors, the exit status is that of the last

command executed, or zero, if no command is executed.

.\"}}}

.\"{{{ Command Syntax

.SS "Command Syntax"

.\"{{{ words and tokens

The shell begins parsing its input by breaking it into \fIword\fPs.

Words, which are sequences of characters, are delimited by unquoted

\fIwhite-space\fP characters (space, tab and newline) or \fImeta-characters\fP

(\fB<\fP, \fB>\fP, \fB|\fP, \fB;\fP, \fB&\fP, \fB(\fP and \fB)\fP).

Aside from delimiting words, spaces and tabs are ignored, while

newlines usually delimit commands.

The meta-characters are used in building the following tokens:

\fB<\fP, \fB<&\fP, \fB<<\fP, \fB>\fP, \fB>&\fP, \fB>>\fP, \fIetc.\fP are

used to specify redirections (see Input/Output Redirection below);

\fB|\fP is used to create pipelines;

.ksh(

\fB|&\fP is used to create co-processes (see Co-Processes below);

.ksh)

\fB;\fP is used to separate commands;

\fB&\fP is used to create asynchronous pipelines;

\fB&&\fP and \fB||\fP are used to specify conditional execution;

\fB;;\fP is used in \fBcase\fP statements;

.ksh(

\fB((\fP .. \fB))\fP are used in arithmetic expressions;

.ksh)

and lastly,

\fB(\fP .. \fB)\fP are used to create subshells.

.PP

White-space and meta-characters can be quoted individually using

backslash (\fB\e\fP), or in groups using double (\fB"\fP) or single (\fB'\fP)

quotes.

Note that the following characters are also treated specially by the shell and

must be quoted if they are to represent themselves:

\fB\e\fP, \fB"\fP, \fB'\fP, \fB#\fP, \fB$\fP, \fB`\fP, \fB~\fP, \fB{\fP,

\fB}\fP, \fB*\fP, \fB?\fP and \fB[\fP.

The first three of these are the above mentioned quoting characters

(see Quoting below);

\fB#\fP, if used at the beginning of a word, introduces a comment \(em everything

after the \fB#\fP up to the nearest newline is ignored;

\fB$\fP is used to introduce parameter, command and arithmetic substitutions

(see Substitution below);

\fB`\fP introduces an old-style command substitution

(see Substitution below);

\fB~\fP begins a directory expansion (see Tilde Expansion below);

\fB{\fP and \fB}\fP delimit \fIcsh\fP(1) style alternations

(see Brace Expansion below);

and, finally, \fB*\fP, \fB?\fP and \fB[\fP are used in file name generation

(see File Name Patterns below).

.\"}}}

.\"{{{ simple-command

.PP

As words and tokens are parsed, the shell builds commands, of which

there are two basic types: \fIsimple-commands\fP, typically programs

that are executed, and \fIcompound-commands\fP, such as \fBfor\fP and

\fBif\fP statements, grouping constructs and function definitions.

.PP

A simple-command consists of some combination of parameter assignments (see

Parameters below), input/output redirections (see Input/Output Redirections

below), and command words; the only restriction is that parameter assignments

come before any command words.

The command words, if any, define the command that is to be executed and its

arguments.

The command may be a shell built-in command, a function or an \fIexternal

command\fP, \fIi.e.\fP, a separate executable file that is located using the

\fBPATH\fP parameter (see Command Execution below).

Note that all command constructs have an \fIexit status\fP: for external

commands, this is related to the status returned by \fIwait\fP(2) (if the

command could not be found, the exit status is 127, if it could not be

executed, the exit status is 126);

the exit status of other command constructs (built-in commands, functions,

compound-commands, pipelines, lists, \fIetc.\fP) are all well defined and are

described where the construct is described.

The exit status of a command consisting only of parameter assignments is that

of the last command substitution performed during the parameter assignment

or zero if there were no command substitutions.

.\"}}}

.\"{{{ pipeline

.PP

Commands can be chained together using the \fB|\fP token to

form \fIpipelines\fP, in which the standard output of each command but

the last is piped (see \fIpipe\fP(2)) to the standard input of the following

command.

The exit status of a pipeline is that of its last command.

A pipeline may be prefixed by the \fB!\fP reserved word which

causes the exit status of the pipeline to be logically

complemented: if the original status was 0 the complemented status will

be 1, and if the original status was not 0, then the complemented

status will be 0.

.\"}}}

.\"{{{ lists

.PP

\fILists\fP of commands can be created by separating pipelines by

any of the following tokens: \fB&&\fP, \fB||\fP, \fB&\fP, \fB|&\fP and \fB;\fP.

The first two are for conditional execution: \fIcmd1\fP \fB&&\fP \fIcmd2\fP

executes \fIcmd2\fP only if the exit status of \fIcmd1\fP is zero;

\fB||\fP is the opposite \(em \fIcmd2\fP is executed only if the exit status

of \fIcmd1\fP is non-zero.

\fB&&\fP and \fB||\fP have equal precedence which is higher than that of

\fB&\fP, \fB|&\fP and \fB;\fP, which also have equal precedence.

The \fB&\fP token causes the preceding command to be executed asynchronously,

that is, the shell starts the command, but does not wait for it to complete

(the shell does keep track of the status of asynchronous commands \(em see

Job Control below).

When an asynchronous command is started when job control is disabled

(\fIi.e.\fP, in most scripts), the command is started with signals INT

and QUIT ignored and with input redirected from /dev/null

(however, redirections specified in the asynchronous command have precedence).

.ksh(

The \fB|&\fP operator starts a \fIco-process\fP which is special kind of

asynchronous process (see Co-Processes below).

.ksh)

Note that a command must follow the \fB&&\fP and \fB||\fP operators, while

a command need not follow \fB&\fP, \fB|&\fP and \fB;\fP.

The exit status of a list is that of the last command executed, with the

exception of asynchronous lists, for which the exit status is 0.

.\"}}}

.\"{{{ compound-commands

.PP

Compound commands are created using the following reserved words \(em these

words are only recognized if they are unquoted and if they are used as

the first word of a command (\fIi.e.\fP, they can't be preceded by parameter

assignments or redirections):

.TS

center;

lfB lfB lfB lfB lfB .

case else function then !

do esac if time [[

done fi in until {

elif for select while }

.TE

\fBNote:\fP Some shells (but not this one) execute control structure commands

in a subshell when one or more of their file descriptors are redirected, so

any environment changes inside them may fail.

To be portable, the \fBexec\fP statement should be used instead to redirect

file descriptors before the control structure.

.PP

In the following compound command descriptions, command lists (denoted as

\fIlist\fP) that are followed by reserved words must end with a

semi-colon, a newline or a (syntactically correct) reserved word.

For example,

.RS

\fB{ echo foo; echo bar; }\fP

.br

\fB{ echo foo; echo bar<newline>}\fP

.br

\fB{ { echo foo; echo bar; } }\fP

.RE

are all valid, but

.RS

\fB{ echo foo; echo bar }\fP

.RE

is not.

.\"{{{ ( list )

.IP "\fB(\fP \fIlist\fP \fB)\fP"

Execute \fIlist\fP in a subshell.

There is no implicit way to pass

environment changes from a subshell back to its parent.

.\"}}}

.\"{{{ { list }

.IP "\fB{\fP \fIlist\fP \fB}\fP"

Compound construct; \fIlist\fP is executed, but not in a subshell.

Note that \fB{\fP and \fB}\fP are reserved words, not meta-characters.

.\"}}}

.\"{{{ case word in [ [ ( ] pattern [ | pattern ] ... ) list ;; ] ... esac

.IP "\fBcase\fP \fIword\fP \fBin\fP [ [\fB(\fP] \fIpattern\fP [\fB|\fP \fIpattern\fP] ... \fB)\fP \fIlist\fP \fB;;\fP ] ... \fBesac\fP"

The \fBcase\fP statement attempts to match \fIword\fP against the specified

\fIpattern\fPs; the \fIlist\fP associated with the first successfully matched

pattern is executed.

Patterns used in \fBcase\fP statements are the same as

those used for file name patterns except that the restrictions regarding

\fB\&.\fP and \fB/\fP are dropped.

Note that any unquoted space before and

after a pattern is stripped; any space with a pattern must be quoted.

Both the word and the patterns are subject to parameter, command, and

arithmetic substitution as well as tilde substitution.

For historical reasons, open and close braces may be used instead

of \fBin\fP and \fBesac\fP (\fIe.g.\fP, \fBcase $foo { *) echo bar; }\fP).

The exit status of a \fBcase\fP statement is that of the executed \fIlist\fP;

if no \fIlist\fP is executed, the exit status is zero.

.\"}}}

.\"{{{ for name [ in word ... term ] do list done

.IP "\fBfor\fP \fIname\fP [ \fBin\fP \fIword\fP ... \fIterm\fP ] \fBdo\fP \fIlist\fP \fBdone\fP"

where \fIterm\fP is either a newline or a \fB;\fP.

For each \fIword\fP in the specified word list, the parameter \fIname\fP is

set to the word and \fIlist\fP is executed.

If \fBin\fP is not used to

specify a word list, the positional parameters (\fB"$1"\fP, \fB"$2"\fP,

\fIetc.\fP) are used instead.

For historical reasons, open and close braces may be used instead

of \fBdo\fP and \fBdone\fP (\fIe.g.\fP, \fBfor i; { echo $i; }\fP).

The exit status of a \fBfor\fP statement is the last exit status

of \fIlist\fP; if \fIlist\fP is never executed, the exit status is zero.

.\"}}}

.\"{{{ if list then list [ elif list then list ] ... [ else list ] fi

.IP "\fBif\fP \fIlist\fP \fBthen\fP \fIlist\fP [\fBelif\fP \fIlist\fP \fBthen\fP \fIlist\fP] ... [\fBelse\fP \fIlist\fP] \fBfi\fP"

If the exit status of the first \fIlist\fP is zero, the second \fIlist\fP

is executed; otherwise the \fIlist\fP following the \fBelif\fP, if any, is

executed with similar consequences.

If all the lists following the \fBif\fP

and \fBelif\fPs fail (\fIi.e.\fP, exit with non-zero status), the \fIlist\fP

following the \fBelse\fP is executed.

The exit status of an \fBif\fP statement is that

of non-conditional \fIlist\fP that is executed; if no non-conditional

\fIlist\fP is executed, the exit status is zero.

.\"}}}

.\"{{{ select name [ in word ... ] do list done

.ksh(

.IP "\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ... \fIterm\fP ] \fBdo\fP \fIlist\fP \fBdone\fP"

where \fIterm\fP is either a newline or a \fB;\fP.

The \fBselect\fP statement provides an automatic method of presenting

the user with a menu and selecting from it.

An enumerated list of the specified \fIwords\fP is printed on standard

error, followed by a prompt (\fBPS3\fP, normally `\fB#? \fP').

A number corresponding to one of the enumerated words is then read

from standard input, \fIname\fP is set to the selected word (or is

unset if the selection is not valid), \fBREPLY\fP

is set to what was read (leading/trailing space is stripped),

and \fIlist\fP is executed.

If a blank line (\fIi.e.\fP, zero or more \fBIFS\fP characters) is entered,

the menu is re-printed without executing \fIlist\fP.

When \fIlist\fP completes, the enumerated list is printed if \fBREPLY\fP

is null, the prompt is printed and so on.

This process is continues until an end-of-file is read, an interrupt is

received or a break statement is executed inside the loop.

If \fBin\fP \fIword\fP \fB\&...\fP is omitted, the positional parameters

are used (\fIi.e.\fP, \fB"$1"\fP, \fB"$2"\fP, \fIetc.\fP).

For historical reasons, open and close braces may be used instead

of \fBdo\fP and \fBdone\fP (\fIe.g.\fP, \fBselect i; { echo $i; }\fP).

The exit status of a \fBselect\fP statement is zero if a break statement

is used to exit the loop, non-zero otherwise.

.ksh)

.\"}}}

.\"{{{ until list do list done

.IP "\fBuntil\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP"

This works like \fBwhile\fP, except that the body is executed only while the

exit status of the first \fIlist\fP is non-zero.

.\"}}}

.\"{{{ while list do list done

.IP "\fBwhile\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP"

A \fBwhile\fP is a prechecked loop.

Its body is executed as often

as the exit status of the first \fIlist\fP is zero.

The exit status of a \fBwhile\fP statement is the last exit status

of the \fIlist\fP in the body of the loop; if the body is not executed,

the exit status is zero.

.\"}}}

.\"{{{ function name { list }

.IP "\fBfunction\fP \fIname\fP \fB{\fP \fIlist\fP \fB}\fP"

Defines the function \fIname\fP.

See Functions below.

Note that redirections specified after a function definition are

performed whenever the function is executed, not when the function

definition is executed.

.\"}}}

.\"{{{ name () command

.IP "\fIname\fP \fB()\fP \fIcommand\fP"

Mostly the same as \fBfunction\fP.

See Functions below.

.\"}}}

.\"{{{ time [-p] [ pipeline ]

.IP "\fBtime\fP [ \fB-p\fP ] [ \fIpipeline\fP ]"

The \fBtime\fP reserved word is described in the Command Execution section.

.\"}}}

.\"{{{ (( expression ))

.ksh(

.IP "\fB((\fP \fIexpression\fP \fB))\fP"

The arithmetic expression \fIexpression\fP is evaluated;

equivalent to \fBlet "\fP\fIexpression\fP\fB"\fP.

See Arithmetic Expressions and the \fBlet\fP command below.

.ksh)

.\"}}}

.\"{{{ [[ expression ]]

.ksh(

.IP "\fB[[\fP \fIexpression\fP \fB]]\fP"

Similar to the \fBtest\fP and \fB[\fP \&... \fB]\fP commands (described later),

with the following exceptions:

.RS

.nr P2 \n(PD

.nr PD 0

.IP \ \ \(bu

Field splitting and file name generation are not performed on

arguments.

.IP \ \ \(bu

The \fB\-a\fP (and) and \fB\-o\fP (or) operators are replaced with

\fB&&\fP and \fB||\fP, respectively.

.IP \ \ \(bu

Operators (\fIe.g.\fP, \fB\-f\fP, \fB=\fP, \fB!\fP, \fIetc.\fP) must be unquoted.

.IP \ \ \(bu

The second operand of \fB!=\fP and \fB=\fP

expressions are patterns (\fIe.g.\fP, the comparison in

.ce

\fB[[ foobar = f*r ]]\fP

succeeds).

.IP \ \ \(bu

There are two additional binary operators: \fB<\fP and \fB>\fP

which return true if their first string operand is less than,

or greater than, their second string operand, respectively.

.IP \ \ \(bu

The single argument form

of \fBtest\fP, which tests if the argument has non-zero length, is not valid

- explicit operators must always be used, \fIe.g.\fP, instead of

.ce

\fB[\fP \fIstr\fP \fB]\fP

use

.ce

\fB[[ \-n \fP\fIstr\fP\fB ]]\fP

.IP \ \ \(bu

Parameter, command and arithmetic substitutions are performed as

expressions are evaluated and lazy expression evaluation is used for

the \fB&&\fP and \fB||\fP operators.

This means that in the statement

.ce

\fB[[ -r foo && $(< foo) = b*r ]]\fP

the \fB$(< foo)\fP is evaluated if and only if the file \fBfoo\fP exists

and is readable.

.nr PD \n(P2

.RE

.ksh)

.\"}}}

.\"}}}

.\"}}}

.\"{{{ Quoting

.SS Quoting

Quoting is used to prevent the shell from treating characters or words

specially.

There are three methods of quoting: First, \fB\e\fP quotes

the following character, unless it is at the end of a line, in which

case both the \fB\e\fP and the newline are stripped.

Second, a single quote (\fB'\fP) quotes everything up to the next single

quote (this may span lines).

Third, a double quote (\fB"\fP) quotes all characters,

except \fB$\fP, \fB`\fP and \fB\e\fP, up to the next unquoted double quote.

\fB$\fP and \fB`\fP inside double quotes have their usual meaning (\fIi.e.\fP,

parameter, command or arithmetic substitution) except no field splitting

is carried out on the results of double-quoted substitutions.

If a \fB\e\fP inside a double-quoted string is followed by \fB\e\fP, \fB$\fP,

\fB`\fP or \fB"\fP, it is replaced by the second character; if it is

followed by a newline, both the \fB\e\fP and the newline are stripped;

otherwise, both the \fB\e\fP and the character following are unchanged.

.PP

Note: An earlier version of ksh(1) changed the interpretation of sequences

of the form \fB"\fP...\fB`\fP...\fB\e"\fP...\fB`\fP..\fB"\fP

according to whether or not POSIX mode was in effect.

In the current implementation, the backslash in \fB\e"\fP

is seen and removed by the outer \fB"\fP...\fB"\fP,

so the backslash is not seen by the inner \fB`\fP...\fB`\fP.

.\"}}}

.\"{{{ Aliases

.SS "Aliases"

There are two types of aliases: normal command aliases and tracked aliases.

Command aliases are normally used as a short hand for a long

or often used command.

The shell expands command aliases (\fIi.e.\fP,

substitutes the alias name for its value) when it reads the first word

of a command.

An expanded alias is re-processed to check for more

aliases.

If a command alias ends in a space or tab, the following word

is also checked for alias expansion.

The alias expansion process stops

when a word that is not an alias is found, when a quoted word is found

or when an alias word that is currently being expanded is found.

.PP

The following command aliases are defined automatically by the shell:

.ft B

.RS

.ksh(

autoload='typeset \-fu'

.br

functions='typeset \-f'

.br

.ksh)

hash='alias \-t'

.ksh(

.br

history='fc \-l'

.br

integer='typeset \-i'

.br

local='typeset'

.br

login='exec login'

.\" ifndef __NetBSD__

.\" .br

.\" newgrp='exec newgrp'

.\" endif

.br

nohup='nohup '

.br

r='fc \-e \-'

.br

stop='kill \-STOP'

.br

suspend='kill \-STOP $$'

.ksh)

.br

type='whence \-v'

.RE

.ft P

.PP

Tracked aliases allow the shell to remember where it found a particular

command.

The first time the shell does a path search for a command that

is marked as a tracked alias, it saves the full path of the command.

The next time the command is executed, the shell checks the saved path

to see that it is still valid, and if so, avoids repeating the path search.

Tracked aliases can be listed and created using \fBalias \-t\fP.

Note that changing the \fBPATH\fP parameter clears the saved

paths for all tracked aliases.

If the \fBtrackall\fP option is set (\fIi.e.\fP,

\fBset \-o trackall\fP or \fBset \-h\fP), the shell tracks all commands.

This option is set automatically for non-interactive shells.

For interactive shells, only the following commands are automatically

tracked: \fBcat\fP, \fBcc\fP, \fBchmod\fP, \fBcp\fP, \fBdate\fP, \fBed\fP,

\fBemacs\fP, \fBgrep\fP, \fBls\fP, \fBmail\fP, \fBmake\fP, \fBmv\fP,

\fBpr\fP, \fBrm\fP, \fBsed\fP, \fBsh\fP, \fBvi\fP and \fBwho\fP.

.\"}}}

.\"{{{ Substitution

.SS "Substitution"

The first step the shell takes in executing a simple-command is to

perform substitutions on the words of the command.

There are three kinds of substitution: parameter, command and arithmetic.

Parameter substitutions, which are described in detail in the next section,

take the form \fB$name\fP or \fB${\fP...\fB}\fP; command substitutions take

the form \fB$(\fP\fIcommand\fP\fB)\fP or \fB`\fP\fIcommand\fP\fB`\fP;

and arithmetic substitutions take the form \fB$((\fP\fIexpression\fP\fB))\fP.

.PP

If a substitution appears outside of double quotes, the results of the

substitution are generally subject to word or field splitting according to

the current value of the \fBIFS\fP parameter.

The \fBIFS\fP parameter specifies a list of characters which

are used to break a string up into several words;

any characters from the set space, tab and newline that appear in the

IFS characters are called \fIIFS white space\fP.

Sequences of one or more IFS white space characters, in combination with

zero or one non-IFS white space characters delimit a field.

As a special case, leading and trailing IFS white space is stripped (\fIi.e.\fP,

no leading or trailing empty field is created by it); leading or trailing

non-IFS white space does create an empty field.

Example: if \fBIFS\fP is set to `<space>:', the sequence of characters

`<space>A<space>:<space><space>B::D' contains four fields: `A', `B', `' and `D'.

Note that if the \fBIFS\fP parameter is set to the null string, no

field splitting is done; if the parameter is unset, the default value

of space, tab and newline is used.

.PP

The results of substitution are, unless otherwise specified, also subject

to brace expansion and file name expansion (see the relevant sections

below).

.PP

A command substitution is replaced by the output generated by the specified

command, which is run in a subshell.

For \fB$(\fP\fIcommand\fP\fB)\fP substitutions, normal quoting rules

are used when \fIcommand\fP is parsed, however, for the

\fB`\fP\fIcommand\fP\fB`\fP form, a \fB\e\fP followed by any of

\fB$\fP, \fB`\fP or \fB\e\fP is stripped (a \fB\e\fP followed by any other

character is unchanged).

As a special case in command substitutions, a command of the form

\fB<\fP \fIfile\fP is interpreted to mean substitute the contents

of \fIfile\fP ($(< foo) has the same effect as $(cat foo), but it

is carried out more efficiently because no process is started).

.br

.\"todo: fix this( $(..) parenthesis counting).

NOTE: \fB$(\fP\fIcommand\fP\fB)\fP expressions are currently parsed by

finding the matching parenthesis, regardless of quoting.

This will hopefully be fixed soon.

.PP

Arithmetic substitutions are replaced by the value of the specified

expression.

For example, the command \fBecho $((2+3*4))\fP prints 14.

See Arithmetic Expressions for a description of an \fIexpression\fP.

.\"}}}

.\"{{{ Parameters

.SS "Parameters"

Parameters are shell variables; they can be assigned values and

their values can be accessed using a parameter substitution.

A parameter name is either one of the special single punctuation or digit

character parameters described below, or a letter followed by zero or more

letters or digits (`_' counts as a letter).

The later form can be treated as arrays by appending an array

index of the form: \fB[\fP\fIexpr\fP\fB]\fP where \fIexpr\fP is

an arithmetic expression.

Array indices are currently limited to the range 0 through 1023, inclusive.

Parameter substitutions take the form \fB$\fP\fIname\fP,

\fB${\fP\fIname\fP\fB}\fP or

\fB${\fP\fIname\fP\fB[\fP\fIexpr\fP\fB]}\fP, where \fIname\fP is a

parameter name.

If substitution is performed on a parameter (or an array parameter element)

that is not set, a null

string is substituted unless the \fBnounset\fP option (\fBset \-o nounset\fP

or \fBset \-u\fP) is set, in which case an error occurs.

.PP

.\"{{{ parameter assignment

Parameters can be assigned values in a number of ways.

First, the shell implicitly sets some parameters like \fB#\fP, \fBPWD\fP,

etc.; this is the only way the special single character parameters are

set.

Second, parameters are imported from the shell's environment at startup.

Third, parameters can be assigned values on the command line, for example,

`\fBFOO=bar\fP' sets the parameter FOO to bar; multiple parameter

assignments can be given on a single command line and they can

be followed by a simple-command, in which case the assignments are

in effect only for the duration of the command (such assignments are

also exported, see below for implications of this).

Note that both the parameter name and the \fB=\fP must be unquoted for

the shell to recognize a parameter assignment.

The fourth way of setting a parameter is with the \fBexport\fP, \fBreadonly\fP

and \fBtypeset\fP commands; see their descriptions in the Command Execution

section.

Fifth, \fBfor\fP and \fBselect\fP loops set parameters as well as

the \fBgetopts\fP, \fBread\fP and \fBset \-A\fP commands.

Lastly, parameters can be assigned values using assignment operators

inside arithmetic expressions (see Arithmetic Expressions below) or

using the \fB${\fP\fIname\fP\fB=\fP\fIvalue\fP\fB}\fP form

of parameter substitution (see below).

.\"}}}

.PP

.\"{{{ environment

Parameters with the export attribute (set using the \fBexport\fP or

\fBtypeset \-x\fP commands, or by parameter assignments followed by simple

commands) are put in the environment (see \fIenviron\fP(7)) of commands

run by the shell as \fIname\fP\fB=\fP\fIvalue\fP pairs.

The order in which parameters appear in the environment of a command

is unspecified.

When the shell starts up, it extracts parameters and their values from its

environment and automatically sets the export attribute for those parameters.

.\"}}}

.\"{{{ ${name[:][-+=?]word}

.PP

Modifiers can be applied to the \fB${\fP\fIname\fP\fB}\fP form of parameter

substitution:

.IP \fB${\fP\fIname\fP\fB:-\fP\fIword\fP\fB}\fP

if \fIname\fP is set and not null, it is substituted, otherwise \fIword\fP is

substituted.

.IP \fB${\fP\fIname\fP\fB:+\fP\fIword\fP\fB}\fP

if \fIname\fP is set and not null, \fIword\fP is substituted, otherwise nothing is substituted.

.IP \fB${\fP\fIname\fP\fB:=\fP\fIword\fP\fB}\fP

if \fIname\fP is set and not null, it is substituted, otherwise it is

assigned \fIword\fP and the resulting value of \fIname\fP is substituted.

.IP \fB${\fP\fIname\fP\fB:?\fP\fIword\fP\fB}\fP

if \fIname\fP is set and not null, it is substituted, otherwise \fIword\fP

is printed on standard error (preceded by \fIname\fP:) and an error occurs

(normally causing termination of a shell script, function or \&.-script).

If word is omitted the string `parameter null or not set' is used instead.

.PP

In the above modifiers, the \fB:\fP can be omitted, in which case the

conditions only depend on \fIname\fP being set (as opposed to set and

not null).

If \fIword\fP is needed, parameter, command, arithmetic and tilde substitution

are performed on it; if \fIword\fP is not needed, it is not evaluated.

.\"}}}

.PP

The following forms of parameter substitution can also be used:

.\"{{{ ${#name}

.IP \fB${#\fP\fIname\fP\fB}\fP

The number of positional parameters if \fIname\fP is \fB*\fP, \fB@\fP or

is not specified,

or the length of the string value of parameter \fIname\fP.

.\"}}}

.\"{{{ ${#name[*]}, ${#name[@]}

.IP "\fB${#\fP\fIname\fP\fB[*]}\fP, \fB${#\fP\fIname\fP\fB[@]}\fP"

The number of elements in the array \fIname\fP.

.\"}}}

.\"{{{ ${name#pattern}, ${name##pattern}

.IP "\fB${\fP\fIname\fP\fB#\fP\fIpattern\fP\fB}\fP, \fB${\fP\fIname\fP\fB##\fP\fIpattern\fP\fB}\fP"

If \fIpattern\fP matches the beginning of the value of parameter \fIname\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.

.\"}}}

.\"{{{ ${name%pattern}, ${name%%pattern}

.IP "\fB${\fP\fIname\fP\fB%\fP\fIpattern\fP\fB}\fP, \fB${\fP\fIname\fP\fB%%\fP\fIpattern\fP\fB}\fP"

Like \fB${\fP..\fB#\fP..\fB}\fP substitution, but it deletes from the end of the

value.

.\"}}}

.\"{{{ special shell parameters

.PP

The following special parameters are implicitly set by the shell and cannot be

set directly using assignments:

.\"{{{ !

.IP \fB!\fP

Process id of the last background process started.

If no background processes have been started, the parameter is not set.

.\"}}}

.\"{{{ #

.IP \fB#\fP

The number of positional parameters (\fIi.e.\fP, \fB$1\fP, \fB$2\fP,

\fIetc.\fP).

.\"}}}

.\"{{{ $

.IP \fB$\fP

The process ID of the shell, or the PID of the original shell if

it is a subshell.

.\"}}}

.\"{{{ -

.IP \fB\-\fP

The concatenation of the current single letter options

(see \fBset\fP command below for list of options).

.\"}}}

.\"{{{ ?

.IP \fB?\fP

The exit status of the last non-asynchronous command executed.

If the last command was killed by a signal, \fB$?\fP is set to 128 plus

the signal number.

.\"}}}

.\"{{{ 0

.IP "\fB0\fP"

The name the shell was invoked with (\fIi.e.\fP, \fBargv[0]\fP), or the

\fBcommand-name\fP if it was invoked with the \fB\-c\fP option and the

\fBcommand-name\fP was supplied, or the \fIfile\fP argument, if it was

supplied.

If the \fBposix\fP option is not set, \fB$0\fP is the name of the current

function or script.

.\"}}}

.\"{{{ 1-9

.IP "\fB1\fP ... \fB9\fP"

The first nine positional parameters that were supplied to the shell,

function or \fB.\fP-script.

Further positional parameters may be accessed using

\fB${\fP\fInumber\fP\fB}\fP.

.\"}}}

.\"{{{ *

.IP \fB*\fP

All positional parameters (except parameter 0),

\fIi.e.\fP, \fB$1 $2 $3\fP....

If used outside of double quotes, parameters are separate words

(which are subjected to word splitting); if used within double quotes,

parameters are separated by the first character of the \fBIFS\fP parameter

(or the empty string if \fBIFS\fP is null).

.\"}}}

.\"{{{ @

.IP \fB@\fP

Same as \fB$*\fP, unless it is used inside double quotes, in which case

a separate word is generated for each positional parameter \- if there

are no positional parameters, no word is generated ("$@" can be used

to access arguments, verbatim, without losing null arguments or

splitting arguments with spaces).

.\"}}}

.\"}}}

.\"{{{ general shell parameters

.PP

The following parameters are set and/or used by the shell:

.\"{{{ _

.ksh(

.IP "\fB_\fP \fI(underscore)\fP"

When an external command is executed by the shell, this parameter is

set in the environment of the new process to the path of the executed

command.

In interactive use, this parameter is also set in the parent shell to

the last word of the previous command.

When \fBMAILPATH\fP messages are evaluated, this parameter contains

the name of the file that changed (see \fBMAILPATH\fP parameter below).

.ksh)

.\"}}}

.\"{{{ CDPATH

.IP \fBCDPATH\fP

Search path for the \fBcd\fP built-in command.

Works the same way as

\fBPATH\fP for those directories not beginning with \fB/\fP in \fBcd\fP

commands.

Note that if CDPATH is set and does not contain \fB.\fP nor an empty path,

the current directory is not searched.

.\"}}}

.\"{{{ COLUMNS

.IP \fBCOLUMNS\fP

Set to the number of columns on the terminal or window.

Currently set to the \fBcols\fP value as reported by \fIstty\fP(1) if that

value is non-zero.

This parameter is used by the interactive line editing modes, and by

\fBselect\fP, \fBset \-o\fP and \fBkill \-l\fP commands

to format information in columns.

.\"}}}

.\"{{{ EDITOR

.ksh(

.IP \fBEDITOR\fP

If the \fBVISUAL\fP parameter is not set, this parameter controls the

command line editing mode for interactive shells.

See \fBVISUAL\fP parameter below for how this works.

.ksh)

.\"}}}

.\"{{{ ENV

.IP \fBENV\fP

If this parameter is found to be set after any profile files are

executed, the expanded value is used as a shell start-up file.

It typically contains function and alias definitions.

.\"}}}

.\"{{{ ERRNO

.IP \fBERRNO\fP

Integer value of the shell's errno variable \(em indicates the reason

the last system call failed.

.\" todo: ERRNO variable

.sp

Not implemented yet.

.\"}}}

.\"{{{ EXECSHELL

.IP \fBEXECSHELL\fP

If set, this parameter is assumed to contain the shell that is to be

used to execute commands that \fIexecve\fP(2) fails to execute and

which do not start with a `\fB#!\fP \fIshell\fP' sequence.

.\"}}}

.\"{{{ FCEDIT

.IP \fBFCEDIT\fP

The editor used by the \fBfc\fP command (see below).

.\"}}}

.\"{{{ FPATH

.IP \fBFPATH\fP

Like \fBPATH\fP, but used when an undefined function is executed to locate

the file defining the function.

It is also searched when a command can't be found using \fBPATH\fP.

See Functions below for more information.

.\"}}}

.\"{{{ HISTFILE

.ksh(

.IP \fBHISTFILE\fP

The name of the file used to store history.

When assigned to, history is loaded from the specified file.

Also, several invocations of the

shell running on the same machine will share history if their

\fBHISTFILE\fP parameters all point at the same file.

.br

NOTE: if HISTFILE isn't set, no history file is used.

This is

different from the original Korn shell, which uses \fB$HOME/.sh_history\fP;

in future, pdksh may also use a default history file.

.ksh)

.\"}}}

.\"{{{ HISTSIZE

.ksh(

.IP \fBHISTSIZE\fP

The number of commands normally stored for history, default 128.

.ksh)

.\"}}}

.\"{{{ HOME

.IP \fBHOME\fP

The default directory for the \fBcd\fP command and the value

substituted for an unqualified \fB~\fP (see Tilde Expansion below).

.\"}}}

.\"{{{ IFS

.IP \fBIFS\fP

Internal field separator, used during substitution and by the \fBread\fP

command, to split values into distinct arguments; normally set to

space, tab and newline.

See Substitution above for details.

.br

\fBNote:\fP this parameter is not imported from the environment

when the shell is started.

.\"}}}

.\"{{{ KSH_VERSION

.ksh(

.IP \fBKSH_VERSION\fP

The version of shell and the date the version was created (readonly).

See also the version commands in Emacs Editing Mode

and Vi Editing Mode sections, below.

.ksh)

.\"}}}

.\"{{{ SH_VERSION

.sh(

.IP \fBSH_VERSION\fP

The version of shell and the date the version was created (readonly).

.sh)

.\"}}}

.\"{{{ LINENO

.IP \fBLINENO\fP

The line number of the function or shell script that is currently being

executed.

.\"}}}

.\"{{{ LINES

.IP \fBLINES\fP

Set to the number of lines on the terminal or window.

.\"Currently set to the \fBrows\fP value as reported by \fIstty\fP(1) if that

.\"value is non-zero.

.\" todo: LINES variable

.sp

Not implemented yet.

.\"}}}

.\"{{{ MAIL

.ksh(

.IP \fBMAIL\fP

If set, the user will be informed of the arrival of mail in the named file.

This parameter is ignored if the \fBMAILPATH\fP parameter is set.

.ksh)

.\"}}}

.\"{{{ MAILCHECK

.ksh(

.IP \fBMAILCHECK\fP

How often, in seconds, the shell will check for mail in the file(s)

specified by \fBMAIL\fP or \fBMAILPATH\fP.

If 0, the shell checks before each prompt.

The default is 600 (10 minutes).

.ksh)

.\"}}}

.\"{{{ MAILPATH

.ksh(

.IP \fBMAILPATH\fP

A list of files to be checked for mail.

The list is colon separated,

and each file may be followed by a \fB?\fP and a message to be printed

if new mail has arrived.

Command, parameter and arithmetic substitution is

performed on the message, and, during substitution, the parameter \fB$_\fP

contains the name of the file.

The default message is \fByou have mail in $_\fP.

.ksh)

.\"}}}

.\"{{{ OLDPWD

.IP \fBOLDPWD\fP

The previous working directory.

Unset if \fBcd\fP has not successfully changed directories since the

shell started, or if the shell doesn't know where it is.

.\"}}}

.\"{{{ OPTARG

.IP \fBOPTARG\fP

When using \fBgetopts\fP, it contains the argument for a parsed option,

if it requires one.

.\"}}}

.\"{{{ OPTIND

.IP \fBOPTIND\fP

The index of the last argument processed when using \fBgetopts\fP.

Assigning 1 to this parameter causes \fBgetopts\fP to

process arguments from the beginning the next time it is invoked.

.\"}}}

.\"{{{ PATH

.IP \fBPATH\fP

A colon separated list of directories that are searched when looking

for commands and \fB.\fP'd files.

An empty string resulting from a leading or trailing colon, or two adjacent

colons is treated as a `.', the current directory.

.\"}}}

.\"{{{ POSIXLY_CORRECT

.IP \fBPOSIXLY_CORRECT\fP

If set, this parameter causes the \fBposix\fP option to be enabled.

See POSIX Mode below.

.\"}}}

.\"{{{ PPID

.IP \fBPPID\fP

The process ID of the shell's parent (readonly).

.\"}}}

.\"{{{ PS1

.IP \fBPS1\fP

\fBPS1\fP is the primary prompt for interactive shells.

.ksh(

Parameter, command and arithmetic substitutions are performed, and

\fB!\fP is replaced with the current command number (see \fBfc\fP

command below).

A literal ! can be put in the prompt by placing !! in PS1.

Note that since the command line editors try to figure out how long the

prompt is (so they know how far it is to edge of the screen),

escape codes in the prompt tend to mess things up.

You can tell the shell not to count certain sequences (such as escape codes)

by prefixing your prompt with a non-printing character (such as control-A)

followed by a carriage return and then delimiting the escape codes with

this non-printing character.

If you don't have any non-printing characters, you're out of luck...

BTW, don't blame me for this hack; it's in the original ksh.

.ksh)

.sh(

The prompt is printed verbatim (\fIi.e.\fP, no substitutions are done).

.sh)

Default is `\fB$\ \fP' for non-root users, `\fB#\ \fP' for root.

.\"}}}