man-pages/man1p/ex.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "EX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" ex 
.SH NAME
ex \- text editor
.SH SYNOPSIS
.LP
\fBex\fP \fB[\fP\fB-rR\fP\fB][\fP\fB-s | -v\fP\fB][\fP\fB-c\fP
\fIcommand\fP\fB][\fP\fB-t\fP \fItagstring\fP\fB][\fP\fB-w\fP \fIsize\fP\fB][\fP\fIfile\fP
\fB\&...\fP\fB]\fP\fB\fP
.SH DESCRIPTION
.LP
The \fIex\fP utility is a line-oriented text editor. There are two
other modes of the editor-open and visual-in which
screen-oriented editing is available. This is described more fully
by the \fIex\fP \fBopen\fP and \fBvisual\fP commands and in
\fIvi\fP .
.LP
This section uses the term \fIedit buffer\fP to describe the current
working text. No specific implementation is implied by
this term. All editing changes are performed on the edit buffer, and
no changes to it shall affect any file until an editor command
writes the file.
.LP
Certain terminals do not have all the capabilities necessary to support
the complete \fIex\fP definition, such as the
full-screen editing commands ( \fIvisual mode\fP or \fIopen mode\fP).
When these commands cannot be supported on such terminals,
this condition shall not produce an error message such as "not an
editor command" or report a syntax error. The implementation
may either accept the commands and produce results on the screen that
are the result of an unsuccessful attempt to meet the
requirements of this volume of IEEE\ Std\ 1003.1-2001 or report an
error describing the terminal-related deficiency.
.SH OPTIONS
.LP
The \fIex\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-c\ \fP \fIcommand\fP
Specify an initial command to be executed in the first edit buffer
loaded from an existing file (see the EXTENDED DESCRIPTION
section). Implementations may support more than a single \fB-c\fP
option. In such implementations, the specified commands shall be
executed in the order specified on the command line.
.TP 7
\fB-r\fP
Recover the named files (see the EXTENDED DESCRIPTION section). Recovery
information for a file shall be saved during an editor
or system crash (for example, when the editor is terminated by a signal
which the editor can catch), or after the use of an
\fIex\fP \fBpreserve\fP command. 
.LP
A \fIcrash\fP in this context is an unexpected failure of the system
or utility that requires restarting the failed system or
utility. A system crash implies that any utilities running at the
time also crash. In the case of an editor or system crash, the
number of changes to the edit buffer (since the most recent \fBpreserve\fP
command) that will be recovered is unspecified.
.LP
If no \fIfile\fP operands are given and the \fB-t\fP option is not
specified, all other options, the \fIEXINIT\fP variable,
and any \fB.exrc\fP files shall be ignored; a list of all recoverable
files available to the invoking user shall be written, and
the editor shall exit normally without further action.
.TP 7
\fB-R\fP
Set \fBreadonly\fP edit option.
.TP 7
\fB-s\fP
Prepare \fIex\fP for batch use by taking the following actions: 
.RS
.IP " *" 3
Suppress writing prompts and informational (but not diagnostic) messages.
.LP
.IP " *" 3
Ignore the value of \fITERM\fP and any implementation default terminal
type and assume the terminal is a type incapable of
supporting open or visual modes; see the \fBvisual\fP command and
the description of \fIvi\fP .
.LP
.IP " *" 3
Suppress the use of the \fIEXINIT\fP environment variable and the
reading of any \fB.exrc\fP file; see the EXTENDED
DESCRIPTION section.
.LP
.IP " *" 3
Suppress autoindentation, ignoring the value of the \fBautoindent\fP
edit option.
.LP
.RE
.TP 7
\fB-t\ \fP \fItagstring\fP
Edit the file containing the specified \fItagstring\fP; see \fIctags\fP
\&. The tags feature
represented by \fB-t\fP \fItagstring\fP and the \fBtag\fP command
is optional. It shall be provided on any system that also
provides a conforming implementation of \fIctags\fP; otherwise, the
use of \fB-t\fP
produces undefined results. On any system, it shall be an error to
specify more than a single \fB-t\fP option.
.TP 7
\fB-v\fP
Begin in visual mode (see \fIvi\fP ).
.TP 7
\fB-w\ \fP \fIsize\fP
Set the value of the \fIwindow\fP editor option to \fIsize\fP.
.sp
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIfile\fP
A pathname of a file to be edited.
.sp
.SH STDIN
.LP
The standard input consists of a series of commands and input text,
as described in the EXTENDED DESCRIPTION section. The
implementation may limit each line of standard input to a length of
{LINE_MAX}.
.LP
If the standard input is not a terminal device, it shall be as if
the \fB-s\fP option had been specified.
.LP
If a read from the standard input returns an error, or if the editor
detects an end-of-file condition from the standard input,
it shall be equivalent to a SIGHUP asynchronous event.
.SH INPUT FILES
.LP
Input files shall be text files or files that would be text files
except for an incomplete last line that is not longer than
{LINE_MAX}-1 bytes in length and contains no NUL characters. By default,
any incomplete last line shall be treated as if it had a
trailing <newline>. The editing of other forms of files may optionally
be allowed by \fIex\fP implementations.
.LP
The \fB.exrc\fP files and source files shall be text files consisting
of \fIex\fP commands; see the EXTENDED DESCRIPTION
section.
.LP
By default, the editor shall read lines from the files to be edited
without interpreting any of those lines as any form of
editor command.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIex\fP:
.TP 7
\fICOLUMNS\fP
Override the system-selected horizontal screen size. See the Base
Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment
Variables for valid values and results when it is unset or null.
.TP 7
\fIEXINIT\fP
Determine a list of \fIex\fP commands that are executed on editor
start-up. See the EXTENDED DESCRIPTION section for more
details of the initialization phase.
.TP 7
\fIHOME\fP
Determine a pathname of a directory that shall be searched for an
editor start-up file named \fB.exrc\fP; see the EXTENDED
DESCRIPTION section.
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_COLLATE\fP
.sp
Determine the locale for the behavior of ranges, equivalence classes,
and multi-character collating elements within regular
expressions.
.TP 7
\fILC_CTYPE\fP
Determine the locale for the interpretation of sequences of bytes
of text data as characters (for example, single-byte as
opposed to multi-byte characters in arguments and input files), the
behavior of character classes within regular expressions, the
classification of characters as uppercase or lowercase letters, the
case conversion of letters, and the detection of word
boundaries.
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fILINES\fP
Override the system-selected vertical screen size, used as the number
of lines in a screenful and the vertical screen size in
visual mode. See the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Chapter 8,
Environment Variables for valid values and results when it is unset
or null.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.TP 7
\fIPATH\fP
Determine the search path for the shell command specified in the \fIex\fP
editor commands \fB!\fP, \fBshell\fP, \fBread\fP,
and \fBwrite\fP, and the open and visual mode command \fB!\fP; see
the description of command search and execution in \fICommand Search
and Execution\fP .
.TP 7
\fISHELL\fP
Determine the preferred command line interpreter for use as the default
value of the \fBshell\fP edit option.
.TP 7
\fITERM\fP
Determine the name of the terminal type. If this variable is unset
or null, an unspecified default terminal type shall be
used.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
The following term is used in this and following sections to specify
command and asynchronous event actions:
.TP 7
\fIcomplete\ write\fP
.sp
A complete write is a write of the entire contents of the edit buffer
to a file of a type other than a terminal device, or the
saving of the edit buffer caused by the user executing the \fIex\fP
\fBpreserve\fP command. Writing the contents of the edit
buffer to a temporary file that will be removed when the editor exits
shall not be considered a complete write.
.sp
.LP
The following actions shall be taken upon receipt of signals:
.TP 7
SIGINT
If the standard input is not a terminal device, \fIex\fP shall not
write the file or return to command or text input mode, and
shall exit with a non-zero exit status. 
.LP
Otherwise, if executing an open or visual text input mode command,
\fIex\fP in receipt of SIGINT shall behave identically to
its receipt of the <ESC> character.
.LP
Otherwise:
.RS
.IP " 1." 4
If executing an \fIex\fP text input mode command, all input lines
that have been completely entered shall be resolved into the
edit buffer, and any partially entered line shall be discarded.
.LP
.IP " 2." 4
If there is a currently executing command, it shall be aborted and
a message displayed. Unless otherwise specified by the
\fIex\fP or \fIvi\fP command descriptions, it is unspecified whether
any lines modified by the
executing command appear modified, or as they were before being modified
by the executing command, in the buffer.
.LP
If the currently executing command was a motion command, its associated
command shall be discarded.
.LP
.IP " 3." 4
If in open or visual command mode, the terminal shall be alerted.
.LP
.IP " 4." 4
The editor shall then return to command mode.
.LP
.RE
.TP 7
SIGCONT
The screen shall be refreshed if in open or visual mode.
.TP 7
SIGHUP
If the edit buffer has been modified since the last complete write,
\fIex\fP shall attempt to save the edit buffer so that it
can be recovered later using the \fB-r\fP option or the \fIex\fP \fBrecover\fP
command. The editor shall not write the file or
return to command or text input mode, and shall terminate with a non-zero
exit status.
.TP 7
SIGTERM
Refer to SIGHUP.
.sp
.LP
The action taken for all other signals is unspecified.
.SH STDOUT
.LP
The standard output shall be used only for writing prompts to the
user, for informational messages, and for writing lines from
the file.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
The output from \fIex\fP shall be text files.
.SH EXTENDED DESCRIPTION
.LP
Only the \fIex\fP mode of the editor is described in this section.
See \fIvi\fP for additional editing
capabilities available in \fIex\fP.
.LP
When an error occurs, \fIex\fP shall write a message. If the terminal
supports a standout mode (such as inverse video), the
message shall be written in standout mode. If the terminal does not
support a standout mode, and the edit option \fBerrorbells\fP
is set, an alert action shall precede the error message.
.LP
By default, \fIex\fP shall start in command mode, which shall be indicated
by a \fB:\fP prompt; see the \fBprompt\fP command.
Text input mode can be entered by the \fBappend\fP, \fBinsert\fP,
or \fBchange\fP commands; it can be exited (and command mode
re-entered) by typing a period ( \fB'.'\fP ) alone at the beginning
of a line.
.SS Initialization in ex and vi
.LP
The following symbols are used in this and following sections to specify
locations in the edit buffer:
.TP 7
\fIalternate\ and\ current\ pathnames\fP
.sp
Two pathnames, named \fIcurrent\fP and \fIalternate\fP, are maintained
by the editor. Any \fIex\fP commands that take filenames
as arguments shall set them as follows: 
.RS
.IP " 1." 4
If a \fIfile\fP argument is specified to the \fIex\fP \fBedit\fP,
\fBex\fP, or \fBrecover\fP commands, or if an \fIex\fP
\fBtag\fP command replaces the contents of the edit buffer.
.RS
.IP " a." 4
If the command replaces the contents of the edit buffer, the current
pathname shall be set to the \fIfile\fP argument or the
file indicated by the tag, and the alternate pathname shall be set
to the previous value of the current pathname.
.LP
.IP " b." 4
Otherwise, the alternate pathname shall be set to the \fIfile\fP argument.
.LP
.RE
.LP
.IP " 2." 4
If a \fIfile\fP argument is specified to the \fIex\fP \fBnext\fP command:
.RS
.IP " a." 4
If the command replaces the contents of the edit buffer, the current
pathname shall be set to the first \fIfile\fP argument,
and the alternate pathname shall be set to the previous value of the
current pathname.
.LP
.RE
.LP
.IP " 3." 4
If a \fIfile\fP argument is specified to the \fIex\fP \fBfile\fP command,
the current pathname shall be set to the
\fIfile\fP argument, and the alternate pathname shall be set to the
previous value of the current pathname.
.LP
.IP " 4." 4
If a \fIfile\fP argument is specified to the \fIex\fP \fBread\fP and
\fBwrite\fP commands (that is, when reading or writing
a file, and not to the program named by the \fBshell\fP edit option),
or a \fIfile\fP argument is specified to the \fIex\fP
\fBxit\fP command:
.RS
.IP " a." 4
If the current pathname has no value, the current pathname shall be
set to the \fIfile\fP argument.
.LP
.IP " b." 4
Otherwise, the alternate pathname shall be set to the \fIfile\fP argument.
.LP
.RE
.LP
.RE
.LP
If the alternate pathname is set to the previous value of the current
pathname when the current pathname had no previous value,
then the alternate pathname shall have no value as a result.
.TP 7
\fIcurrent\ line\fP
.sp
The line of the edit buffer referenced by the cursor. Each command
description specifies the current line after the command has
been executed, as the \fIcurrent line value\fP. When the edit buffer
contains no lines, the current line shall be zero; see Addressing
in ex .
.TP 7
\fIcurrent\ column\fP
.sp
The current display line column occupied by the cursor. (The columns
shall be numbered beginning at 1.) Each command description
specifies the current column after the command has been executed,
as the \fIcurrent column\fP value. This column is an
\fIideal\fP column that is remembered over the lifetime of the editor.
The actual display line column upon which the cursor rests
may be different from the current column; see the cursor positioning
discussion in \fICommand
Descriptions in vi\fP .
.TP 7
\fIset\ to\ non-<blank>\fP
.sp
A description for a current column value, meaning that the current
column shall be set to the last display line column on which is
displayed any part of the first non- <blank> of the line. If the line
has no non- <blank> non- <newline>s, the
current column shall be set to the last display line column on which
is displayed any part of the last non- <newline> in the
line. If the line is empty, the current column shall be set to column
position 1.
.sp
.LP
The length of lines in the edit buffer may be limited to {LINE_MAX}
bytes. In open and visual mode, the length of lines in the
edit buffer may be limited to the number of characters that will fit
in the display. If either limit is exceeded during editing, an
error message shall be written. If either limit is exceeded by a line
read in from a file, an error message shall be written and
the edit session may be terminated.
.LP
If the editor stops running due to any reason other than a user command,
and the edit buffer has been modified since the last
complete write, it shall be equivalent to a SIGHUP asynchronous event.
If the system crashes, it shall be equivalent to a SIGHUP
asynchronous event.
.LP
During initialization (before the first file is copied into the edit
buffer or any user commands from the terminal are
processed) the following shall occur:
.IP " 1." 4
If the environment variable \fIEXINIT\fP is set, the editor shall
execute the \fIex\fP commands contained in that
variable.
.LP
.IP " 2." 4
If the \fIEXINIT\fP variable is not set, and all of the following
are true:
.RS
.IP " a." 4
The \fIHOME\fP environment variable is not null and not empty.
.LP
.IP " b." 4
The file \fB.exrc\fP in the directory referred to by the \fIHOME\fP
environment variable:
.RS
.IP " 1." 4
Exists
.LP
.IP " 2." 4
Is owned by the same user ID as the real user ID of the process or
the process has appropriate privileges
.LP
.IP " 3." 4
Is not writable by anyone other than the owner
.LP
.RE
.LP
.RE
.LP
the editor shall execute the \fIex\fP commands contained in that file.
.LP
.IP " 3." 4
If and only if all of the following are true:
.RS
.IP " a." 4
The current directory is not referred to by the \fIHOME\fP environment
variable.
.LP
.IP " b." 4
A command in the \fIEXINIT\fP environment variable or a command in
the \fB.exrc\fP file in the directory referred to by the
\fIHOME\fP environment variable sets the editor option \fBexrc\fP.
.LP
.IP " c." 4
The \fB.exrc\fP file in the current directory:
.RS
.IP " 1." 4
Exists
.LP
.IP " 2." 4
Is owned by the same user ID as the real user ID of the process, or
by one of a set of implementation-defined user IDs
.LP
.IP " 3." 4
Is not writable by anyone other than the owner
.LP
.RE
.LP
.RE
.LP
the editor shall attempt to execute the \fIex\fP commands contained
in that file.
.LP
.LP
Lines in any \fB.exrc\fP file that are blank lines shall be ignored.
If any \fB.exrc\fP file exists, but is not read for
ownership or permission reasons, it shall be an error.
.LP
After the \fIEXINIT\fP variable and any \fB.exrc\fP files are processed,
the first file specified by the user shall be edited,
as follows:
.IP " 1." 4
If the user specified the \fB-t\fP option, the effect shall be as
if the \fIex\fP \fBtag\fP command was entered with the
specified argument, with the exception that if tag processing does
not result in a file to edit, the effect shall be as described
in step 3. below.
.LP
.IP " 2." 4
Otherwise, if the user specified any command line \fIfile\fP arguments,
the effect shall be as if the \fIex\fP \fBedit\fP
command was entered with the first of those arguments as its \fIfile\fP
argument.
.LP
.IP " 3." 4
Otherwise, the effect shall be as if the \fIex\fP \fBedit\fP command
was entered with a nonexistent filename as its
\fIfile\fP argument. It is unspecified whether this action shall set
the current pathname. In an implementation where this action
does not set the current pathname, any editor command using the current
pathname shall fail until an editor command sets the
current pathname.
.LP
.LP
If the \fB-r\fP option was specified, the first time a file in the
initial argument list or a file specified by the \fB-t\fP
option is edited, if recovery information has previously been saved
about it, that information shall be recovered and the editor
shall behave as if the contents of the edit buffer have already been
modified. If there are multiple instances of the file to be
recovered, the one most recently saved shall be recovered, and an
informational message that there are previous versions of the
file that can be recovered shall be written. If no recovery information
about a file is available, an informational message to this
effect shall be written, and the edit shall proceed as usual.
.LP
If the \fB-c\fP option was specified, the first time a file that already
exists (including a file that might not exist but for
which recovery information is available, when the \fB-r\fP option
is specified) replaces or initializes the contents of the edit
buffer, the current line shall be set to the last line of the edit
buffer, the current column shall be set to non- <blank>,
and the \fIex\fP commands specified with the \fB-c\fP option shall
be executed. In this case, the current line and current column
shall not be set as described for the command associated with the
replacement or initialization of the edit buffer contents.
However, if the \fB-t\fP option or a \fBtag\fP command is associated
with this action, the \fB-c\fP option commands shall be
executed and then the movement to the tag shall be performed.
.LP
The current argument list shall initially be set to the filenames
specified by the user on the command line. If no filenames are
specified by the user, the current argument list shall be empty. If
the \fB-t\fP option was specified, it is unspecified whether
any filename resulting from tag processing shall be prepended to the
current argument list. In the case where the filename is added
as a prefix to the current argument list, the current argument list
reference shall be set to that filename. In the case where the
filename is not added as a prefix to the current argument list, the
current argument list reference shall logically be located
before the first of the filenames specified on the command line (for
example, a subsequent \fIex\fP \fBnext\fP command shall edit
the first filename from the command line). If the \fB-t\fP option
was not specified, the current argument list reference shall be
to the first of the filenames on the command line.
.SS Addressing in ex
.LP
Addressing in \fIex\fP relates to the current line and the current
column; the address of a line is its 1-based line number,
the address of a column is its 1-based count from the beginning of
the line. Generally, the current line is the last line affected
by a command. The current line number is the address of the current
line. In each command description, the effect of the command on
the current line number and the current column is described.
.LP
Addresses are constructed as follows:
.IP " 1." 4
The character \fB'.'\fP (period) shall address the current line.
.LP
.IP " 2." 4
The character \fB'$'\fP shall address the last line of the edit buffer.
.LP
.IP " 3." 4
The positive decimal number \fIn\fP shall address the \fIn\fPth line
of the edit buffer.
.LP
.IP " 4." 4
The address \fB"'x"\fP refers to the line marked with the mark name
character \fB'x'\fP , which shall be a lowercase
letter from the portable character set or one of the characters \fB'`'\fP
or \fB'"\fP . It shall be an error if the line
that was marked is not currently present in the edit buffer or the
mark has not been set. Lines can be marked with the \fIex\fP
\fBmark\fP or \fBk\fP commands, or the \fIvi\fP \fBm\fP command.
.LP
.IP " 5." 4
A regular expression enclosed by slashes ( \fB'/'\fP ) shall address
the first line found by searching forwards from the line
following the current line toward the end of the edit buffer and stopping
at the first line for which the line excluding the
terminating <newline> matches the regular expression. As stated in
Regular Expressions in ex ,
an address consisting of a null regular expression delimited by slashes
\fB"//"\fP shall address the next line for which the
line excluding the terminating <newline> matches the last regular
expression encountered. In addition, the second slash can
be omitted at the end of a command line. If the \fBwrapscan\fP edit
option is set, the search shall wrap around to the beginning
of the edit buffer and continue up to and including the current line,
so that the entire edit buffer is searched. Within the
regular expression, the sequence \fB"\\/"\fP shall represent a literal
slash instead of the regular expression delimiter.
.LP
.IP " 6." 4
A regular expression enclosed in question marks ( \fB'?'\fP ) shall
address the first line found by searching backwards from
the line preceding the current line toward the beginning of the edit
buffer and stopping at the first line for which the line
excluding the terminating <newline> matches the regular expression.
An address consisting of a null regular expression
delimited by question marks \fB"??"\fP shall address the previous
line for which the line excluding the terminating
<newline> matches the last regular expression encountered. In addition,
the second question mark can be omitted at the end of
a command line. If the \fBwrapscan\fP edit option is set, the search
shall wrap around from the beginning of the edit buffer to
the end of the edit buffer and continue up to and including the current
line, so that the entire edit buffer is searched. Within
the regular expression, the sequence \fB"\\?"\fP shall represent a
literal question mark instead of the RE delimiter.
.LP
.IP " 7." 4
A plus sign ( \fB'+'\fP ) or a minus sign ( \fB'-'\fP ) followed by
a decimal number shall address the current line plus
or minus the number. A \fB'+'\fP or \fB'-'\fP not followed by a decimal
number shall address the current line plus or minus
1.
.LP
.LP
Addresses can be followed by zero or more address offsets, optionally
<blank>-separated. Address offsets are constructed
as follows:
.IP " 1." 4
A \fB'+'\fP or \fB'-'\fP immediately followed by a decimal number
shall add (subtract) the indicated number of lines to
(from) the address. A \fB'+'\fP or \fB'-'\fP not followed by a decimal
number shall add (subtract) 1 to (from) the
address.
.LP
.IP " 2." 4
A decimal number shall add the indicated number of lines to the address.
.LP
.LP
It shall not be an error for an intermediate address value to be less
than zero or greater than the last line in the edit
buffer. It shall be an error for the final address value to be less
than zero or greater than the last line in the edit buffer.
.LP
Commands take zero, one, or two addresses; see the descriptions of
\fI1addr\fP and \fI2addr\fP in Command Descriptions in ex . If more
than the required number of addresses are provided to a command that
requires zero addresses, it shall be an error. Otherwise, if more
than the required number of addresses are provided to a command,
the addresses specified first shall be evaluated and then discarded
until the maximum number of valid addresses remain.
.LP
Addresses shall be separated from each other by a comma ( \fB','\fP
) or a semicolon ( \fB';'\fP ). If no address is
specified before or after a comma or semicolon separator, it shall
be as if the address of the current line was specified before or
after the separator. In the case of a semicolon separator, the current
line ( \fB'.'\fP ) shall be set to the first address, and
only then will the next address be calculated. This feature can be
used to determine the starting line for forwards and backwards
searches (see rules 5. and 6.).
.LP
A percent sign ( \fB'%'\fP ) shall be equivalent to entering the two
addresses \fB"1,$"\fP .
.LP
Any delimiting <blank>s between addresses, address separators, or
address offsets shall be discarded.
.SS Command Line Parsing in ex
.LP
The following symbol is used in this and following sections to describe
parsing behavior:
.TP 7
\fIescape\fP
If a character is referred to as "backslash-escaped" or " <control>-V-escaped,"
it shall mean that the character
acquired or lost a special meaning by virtue of being preceded, respectively,
by a backslash or <control>-V character. Unless
otherwise specified, the escaping character shall be discarded at
that time and shall not be further considered for any
purpose.
.sp
.LP
Command-line parsing shall be done in the following steps. For each
step, characters already evaluated shall be ignored; that
is, the phrase "leading character" refers to the next character that
has not yet been evaluated.
.IP " 1." 4
Leading colon characters shall be skipped.
.LP
.IP " 2." 4
Leading <blank>s shall be skipped.
.LP
.IP " 3." 4
If the leading character is a double-quote character, the characters
up to and including the next non-backslash-escaped
<newline> shall be discarded, and any subsequent characters shall
be parsed as a separate command.
.LP
.IP " 4." 4
Leading characters that can be interpreted as addresses shall be evaluated;
see Addressing in ex
\&.
.LP
.IP " 5." 4
Leading <blank>s shall be skipped.
.LP
.IP " 6." 4
If the next character is a vertical-line character or a <newline>:
.RS
.IP " a." 4
If the next character is a <newline>:
.RS
.IP " 1." 4
If \fIex\fP is in open or visual mode, the current line shall be set
to the last address specified, if any.
.LP
.IP " 2." 4
Otherwise, if the last command was terminated by a vertical-line character,
no action shall be taken; for example, the command
\fB"||<newline>"\fP shall execute two implied commands, not three.
.LP
.IP " 3." 4
Otherwise, step 6.b. shall apply.
.LP
.RE
.LP
.IP " b." 4
Otherwise, the implied command shall be the \fBprint\fP command. The
last \fB#\fP, \fBp\fP, and \fBl\fP flags specified to
any \fIex\fP command shall be remembered and shall apply to this implied
command. Executing the \fIex\fP \fBnumber\fP,
\fBprint\fP, or \fBlist\fP command shall set the remembered flags
to \fB#\fP, nothing, and \fBl\fP, respectively, plus any
other flags specified for that execution of the \fBnumber\fP, \fBprint\fP,
or \fBlist\fP command.
.LP
If \fIex\fP is not currently performing a \fBglobal\fP or \fBv\fP
command, and no address or count is specified, the current
line shall be incremented by 1 before the command is executed. If
incrementing the current line would result in an address past the
last line in the edit buffer, the command shall fail, and the increment
shall not happen.
.LP
.IP " c." 4
The <newline> or vertical-line character shall be discarded and any
subsequent characters shall be parsed as a separate
command.
.LP
.RE
.LP
.IP " 7." 4
The command name shall be comprised of the next character (if the
character is not alphabetic), or the next character and any
subsequent alphabetic characters (if the character is alphabetic),
with the following exceptions:
.RS
.IP " a." 4
Commands that consist of any prefix of the characters in the command
name \fBdelete\fP, followed immediately by any of the
characters \fB'l'\fP , \fB'p'\fP , \fB'+'\fP , \fB'-'\fP , or \fB'#'\fP
shall be interpreted as a \fBdelete\fP
command, followed by a <blank>, followed by the characters that were
not part of the prefix of the \fBdelete\fP command. The
maximum number of characters shall be matched to the command name
\fBdelete\fP; for example, \fB"del"\fP shall not be treated
as \fB"de"\fP followed by the flag \fBl\fP.
.LP
.IP " b." 4
Commands that consist of the character \fB'k'\fP , followed by a character
that can be used as the name of a mark, shall be
equivalent to the mark command followed by a <blank>, followed by
the character that followed the \fB'k'\fP .
.LP
.IP " c." 4
Commands that consist of the character \fB's'\fP , followed by characters
that could be interpreted as valid options to the
\fBs\fP command, shall be the equivalent of the \fBs\fP command, without
any pattern or replacement values, followed by a
<blank>, followed by the characters after the \fB's'\fP .
.LP
.RE
.LP
.IP " 8." 4
The command name shall be matched against the possible command names,
and a command name that contains a prefix matching the
characters specified by the user shall be the executed command. In
the case of commands where the characters specified by the user
could be ambiguous, the executed command shall be as follows:
.TS C
center; l l l l l l l l.
\fBa\fP	\fBappend\fP	n	\fBnext\fP	\fBt\fP	t	\fB\ \fP	\fB\ \fP
\fBc\fP	\fBchange\fP	p	\fBprint\fP	\fBu\fP	undo	\fB\ \fP	\fB\ \fP
\fBch\fP	\fBchange\fP	pr	\fBprint\fP	\fBun\fP	undo	\fB\ \fP	\fB\ \fP
\fBe\fP	\fBedit\fP	r	\fBread\fP	\fBv\fP	v	\fB\ \fP	\fB\ \fP
\fBm\fP	\fBmove\fP	re	\fBread\fP	\fBw\fP	write	\fB\ \fP	\fB\ \fP
\fBma\fP	\fBmark\fP	s	\fBs\fP	\fB\ \fP	\ 	\fB\ \fP	\fB\ \fP
.TE
.LP
Implementation extensions with names causing similar ambiguities shall
not be checked for a match until all possible matches for
commands specified by IEEE\ Std\ 1003.1-2001 have been checked.
.LP
.IP " 9." 4
If the command is a \fB!\fP command, or if the command is a \fBread\fP
command followed by zero or more <blank>s and a
\fB!\fP, or if the command is a \fBwrite\fP command followed by one
or more <blank>s and a \fB!\fP, the rest of the
command shall include all characters up to a non-backslash-escaped
<newline>. The <newline> shall be discarded and any
subsequent characters shall be parsed as a separate \fIex\fP command.
.LP
.IP "10." 4
Otherwise, if the command is an \fBedit\fP, \fBex\fP, or \fBnext\fP
command, or a \fBvisual\fP command while in open or
visual mode, the next part of the command shall be parsed as follows:
.RS
.IP " a." 4
Any \fB'!'\fP character immediately following the command shall be
skipped and be part of the command.
.LP
.IP " b." 4
Any leading <blank>s shall be skipped and be part of the command.
.LP
.IP " c." 4
If the next character is a \fB'+'\fP , characters up to the first
non-backslash-escaped <newline> or
non-backslash-escaped <blank> shall be skipped and be part of the
command.
.LP
.IP " d." 4
The rest of the command shall be determined by the steps specified
in paragraph 12.
.LP
.RE
.LP
.IP "11." 4
Otherwise, if the command is a \fBglobal\fP, \fBopen\fP, \fBs\fP,
or \fBv\fP command, the next part of the command shall be
parsed as follows:
.RS
.IP " a." 4
Any leading <blank>s shall be skipped and be part of the command.
.LP
.IP " b." 4
If the next character is not an alphanumeric, double-quote, <newline>,
backslash, or vertical-line character:
.RS
.IP " 1." 4
The next character shall be used as a command delimiter.
.LP
.IP " 2." 4
If the command is a \fBglobal\fP, \fBopen\fP, or \fBv\fP command,
characters up to the first non-backslash-escaped
<newline>, or first non-backslash-escaped delimiter character, shall
be skipped and be part of the command.
.LP
.IP " 3." 4
If the command is an \fBs\fP command, characters up to the first non-backslash-escaped
<newline>, or second
non-backslash-escaped delimiter character, shall be skipped and be
part of the command.
.LP
.RE
.LP
.IP " c." 4
If the command is a \fBglobal\fP or \fBv\fP command, characters up
to the first non-backslash-escaped <newline> shall be
skipped and be part of the command.
.LP
.IP " d." 4
Otherwise, the rest of the command shall be determined by the steps
specified in paragraph 12.
.LP
.RE
.LP
.IP "12." 4
Otherwise:
.RS
.IP " a." 4
If the command was a \fBmap\fP, \fBunmap\fP, \fBabbreviate\fP, or
\fBunabbreviate\fP command, characters up to the first
non- <control>-V-escaped <newline>, vertical-line, or double-quote
character shall be skipped and be part of the
command.
.LP
.IP " b." 4
Otherwise, characters up to the first non-backslash-escaped <newline>,
vertical-line, or double-quote character shall be
skipped and be part of the command.
.LP
.IP " c." 4
If the command was an \fBappend\fP, \fBchange\fP, or \fBinsert\fP
command, and the step 12.b. ended at a vertical-line
character, any subsequent characters, up to the next non-backslash-escaped
<newline> shall be used as input text to the
command.
.LP
.IP " d." 4
If the command was ended by a double-quote character, all subsequent
characters, up to the next non-backslash-escaped
<newline>, shall be discarded.
.LP
.IP " e." 4
The terminating <newline> or vertical-line character shall be discarded
and any subsequent characters shall be parsed as a
separate \fIex\fP command.
.LP
.RE
.LP
.LP
Command arguments shall be parsed as described by the Synopsis and
Description of each individual \fIex\fP command. This
parsing shall not be <blank>-sensitive, except for the \fB!\fP argument,
which must follow the command name without
intervening <blank>s, and where it would otherwise be ambiguous. For
example, \fIcount\fP and \fIflag\fP arguments need not
be <blank>-separated because \fB"d22p"\fP is not ambiguous, but \fIfile\fP
arguments to the \fIex\fP \fBnext\fP command
must be separated by one or more <blank>s. Any <blank> in command
arguments for the \fBabbreviate\fP,
\fBunabbreviate\fP, \fBmap\fP, and \fBunmap\fP commands can be <control>-V-escaped,
in which case the <blank> shall
not be used as an argument delimiter. Any <blank> in the command argument
for any other command can be backslash-escaped, in
which case that <blank> shall not be used as an argument delimiter.
.LP
Within command arguments for the \fBabbreviate\fP, \fBunabbreviate\fP,
\fBmap\fP, and \fBunmap\fP commands, any character
can be <control>-V-escaped. All such escaped characters shall be treated
literally and shall have no special meaning. Within
command arguments for all other \fIex\fP commands that are not regular
expressions or replacement strings, any character that
would otherwise have a special meaning can be backslash-escaped. Escaped
characters shall be treated literally, without special
meaning as shell expansion characters or \fB'!'\fP , \fB'%'\fP , and
\fB'#'\fP expansion characters. See Regular Expressions in ex and
Replacement Strings in ex for descriptions of
command arguments that are regular expressions or replacement strings.
.LP
Non-backslash-escaped \fB'%'\fP characters appearing in \fIfile\fP
arguments to any \fIex\fP command shall be replaced by
the current pathname; unescaped \fB'#'\fP characters shall be replaced
by the alternate pathname. It shall be an error if
\fB'%'\fP or \fB'#'\fP characters appear unescaped in an argument
and their corresponding values are not set.
.LP
Non-backslash-escaped \fB'!'\fP characters in the arguments to either
the \fIex\fP \fB!\fP command or the open and visual
mode \fB!\fP command, or in the arguments to the \fIex\fP \fBread\fP
command, where the first non- <blank> after the
command name is a \fB'!'\fP character, or in the arguments to the
\fIex\fP \fBwrite\fP command where the command name is
followed by one or more <blank>s and the first non- <blank> after
the command name is a \fB'!'\fP character, shall
be replaced with the arguments to the last of those three commands
as they appeared after all unescaped \fB'%'\fP , \fB'#'\fP
, and \fB'!'\fP characters were replaced. It shall be an error if
\fB'!'\fP characters appear unescaped in one of these
commands and there has been no previous execution of one of these
commands.
.LP
If an error occurs during the parsing or execution of an \fIex\fP
command:
.IP " *" 3
An informational message to this effect shall be written. Execution
of the \fIex\fP command shall stop, and the cursor (for
example, the current line and column) shall not be further modified.
.LP
.IP " *" 3
If the \fIex\fP command resulted from a map expansion, all characters
from that map expansion shall be discarded, except as
otherwise specified by the \fBmap\fP command.
.LP
.IP " *" 3
Otherwise, if the \fIex\fP command resulted from the processing of
an \fIEXINIT\fP environment variable, a \fB.exrc\fP file,
a \fB:source\fP command, a \fB-c\fP option, or a \fB+\fP \fIcommand\fP
specified to an \fIex\fP \fBedit\fP, \fBex\fP,
\fBnext\fP, or \fBvisual\fP command, no further commands from the
source of the commands shall be executed.
.LP
.IP " *" 3
Otherwise, if the \fIex\fP command resulted from the execution of
a buffer or a \fBglobal\fP or \fBv\fP command, no further
commands caused by the execution of the buffer or the \fBglobal\fP
or \fBv\fP command shall be executed.
.LP
.IP " *" 3
Otherwise, if the \fIex\fP command was not terminated by a <newline>,
all characters up to and including the next
non-backslash-escaped <newline> shall be discarded.
.LP
.SS Input Editing in ex
.LP
The following symbol is used in this and the following sections to
specify command actions:
.TP 7
\fIword\fP
In the POSIX locale, a word consists of a maximal sequence of letters,
digits, and underscores, delimited at both ends by
characters other than letters, digits, or underscores, or by the beginning
or end of a line or the edit buffer.
.sp
.LP
When accepting input characters from the user, in either \fIex\fP
command mode or \fIex\fP text input mode, \fIex\fP shall
enable canonical mode input processing, as defined in the System Interfaces
volume of IEEE\ Std\ 1003.1-2001.
.LP
If in \fIex\fP text input mode:
.IP " 1." 4
If the \fBnumber\fP edit option is set, \fIex\fP shall prompt for
input using the line number that would be assigned to the
line if it is entered, in the format specified for the \fIex\fP \fBnumber\fP
command.
.LP
.IP " 2." 4
If the \fBautoindent\fP edit option is set, \fIex\fP shall prompt
for input using \fBautoindent\fP characters, as described
by the \fBautoindent\fP edit option. \fBautoindent\fP characters shall
follow the line number, if any.
.LP
.LP
If in \fIex\fP command mode:
.IP " 1." 4
If the \fBprompt\fP edit option is set, input shall be prompted for
using a single \fB':'\fP character; otherwise, there
shall be no prompt.
.LP
.LP
The input characters in the following sections shall have the following
effects on the input line.
.SS Scroll
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBeof
\fP
.fi
.RE
.sp
.LP
See the description of the \fIstty\fP \fIeof\fP character in \fIstty\fP
\&.
.LP
If in \fIex\fP command mode:
If the \fIeof\fP character is the first character entered on the line,
the line shall be evaluated as if it contained
two characters: a <control>-D and a <newline>. 
.LP
Otherwise, the \fIeof\fP character shall have no special meaning.
.sp
.LP
If in \fIex\fP text input mode:
If the cursor follows an \fBautoindent\fP character, the \fBautoindent\fP
characters in the line shall be modified so
that a part of the next text input character will be displayed on
the first column in the line after the previous \fBshiftwidth\fP
edit option column boundary, and the user shall be prompted again
for input for the same line. 
.LP
Otherwise, if the cursor follows a \fB'0'\fP , which follows an \fBautoindent\fP
character, and the \fB'0'\fP was the
previous text input character, the \fB'0'\fP and all \fBautoindent\fP
characters in the line shall be discarded, and the user
shall be prompted again for input for the same line.
.LP
Otherwise, if the cursor follows a \fB'^'\fP , which follows an \fBautoindent\fP
character, and the \fB'^'\fP was the
previous text input character, the \fB'^'\fP and all \fBautoindent\fP
characters in the line shall be discarded, and the user
shall be prompted again for input for the same line. In addition,
the \fBautoindent\fP level for the next input line shall be
derived from the same line from which the \fBautoindent\fP level for
the current input line was derived.
.LP
Otherwise, if there are no \fBautoindent\fP or text input characters
in the line, the \fIeof\fP character shall be
discarded.
.LP
Otherwise, the \fIeof\fP character shall have no special meaning.
.SS <newline>
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB<newline>
.sp

<control>-J
\fP
.fi
.RE
.sp
.LP
If in \fIex\fP command mode:
Cause the command line to be parsed; <control>-J shall be mapped to
the <newline> for this
purpose.
.LP
If in \fIex\fP text input mode:
Terminate the current line. If there are no characters other than
\fBautoindent\fP characters on the line, all
characters on the line shall be discarded. 
.LP
Prompt for text input on a new line after the current line. If the
\fBautoindent\fP edit option is set, an appropriate number
of \fBautoindent\fP characters shall be added as a prefix to the line
as described by the \fIex\fP \fBautoindent\fP edit
option.
.SS <backslash>
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB<backslash>
\fP
.fi
.RE
.sp
.LP
Allow the entry of a subsequent <newline> or <control>-J as a literal
character, removing any special meaning that
it may have to the editor during text input mode. The backslash character
shall be retained and evaluated when the command line is
parsed, or retained and included when the input text becomes part
of the edit buffer.
.SS <control>-V
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB<control>-V
\fP
.fi
.RE
.sp
.LP
Allow the entry of any subsequent character as a literal character,
removing any special meaning that it may have to the editor
during text input mode. The <control>-V character shall be discarded
before the command line is parsed or the input text
becomes part of the edit buffer.
.LP
If the "literal next" functionality is performed by the underlying
system, it is implementation-defined whether a character
other than <control>-V performs this function.
.SS <control>-W
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB<control>-W
\fP
.fi
.RE
.sp
.LP
Discard the <control>-W, and the word previous to it in the input
line, including any <blank>s following the word
and preceding the <control>-W. If the "word erase" functionality is
performed by the underlying system, it is
implementation-defined whether a character other than <control>-W
performs this function.
.SS Command Descriptions in ex
.LP
The following symbols are used in this section to represent command
modifiers. Some of these modifiers can be omitted, in which
case the specified defaults shall be used.
.TP 7
\fI1addr\fP
A single line address, given in any of the forms described in Addressing
in ex ; the default
shall be the current line ( \fB'.'\fP ), unless otherwise specified.
.LP
If the line address is zero, it shall be an error, unless otherwise
specified in the following command descriptions.
.LP
If the edit buffer is empty, and the address is specified with a command
other than \fB=\fP, \fBappend\fP, \fBinsert\fP,
\fBopen\fP, \fBput\fP, \fBread\fP, or \fBvisual\fP, or the address
is not zero, it shall be an error.
.TP 7
\fI2addr\fP
Two addresses specifying an inclusive range of lines. If no addresses
are specified, the default for \fI2addr\fP shall be the
current line only ( \fB".,."\fP ), unless otherwise specified in the
following command descriptions. If one address is
specified, \fI2addr\fP shall specify that line only, unless otherwise
specified in the following command descriptions. 
.LP
It shall be an error if the first address is greater than the second
address.
.LP
If the edit buffer is empty, and the two addresses are specified with
a command other than the \fB!\fP, \fBwrite\fP,
\fBwq\fP, or \fBxit\fP commands, or either address is not zero, it
shall be an error.
.TP 7
\fIcount\fP
A positive decimal number. If \fIcount\fP is specified, it shall be
equivalent to specifying an additional address to the
command, unless otherwise specified by the following command descriptions.
The additional address shall be equal to the last
address specified to the command (either explicitly or by default)
plus \fIcount\fP-1. 
.LP
If this would result in an address greater than the last line of the
edit buffer, it shall be corrected to equal the last line
of the edit buffer.
.TP 7
\fIflags\fP
One or more of the characters \fB'+'\fP , \fB'-'\fP , \fB'#'\fP ,
\fB'p'\fP , or \fB'l'\fP (ell). The flag
characters can be <blank>-separated, and in any order or combination.
The characters \fB'#'\fP , \fB'p'\fP , and
\fB'l'\fP shall cause lines to be written in the format specified
by the \fBprint\fP command with the specified \fIflags\fP. 
.LP
The lines to be written are as follows:
.RS
.IP " 1." 4
All edit buffer lines written during the execution of the \fIex\fP
\fB&\fP, \fB~\fP, \fBlist\fP, \fBnumber\fP,
\fBopen\fP, \fBprint\fP, \fBs\fP, \fBvisual\fP, and \fBz\fP commands
shall be written as specified by \fIflags\fP.
.LP
.IP " 2." 4
After the completion of an \fIex\fP command with a flag as an argument,
the current line shall be written as specified by
\fIflags\fP, unless the current line was the last line written by
the command.
.LP
.RE
.LP
The characters \fB'+'\fP and \fB'-'\fP cause the value of the current
line after the execution of the \fIex\fP command to
be adjusted by the offset address as described in Addressing in ex
\&. This adjustment shall occur
before the current line is written as described in 2. above.
.LP
The default for \fIflags\fP shall be none.
.TP 7
\fIbuffer\fP
One of a number of named areas for holding text. The named buffers
are specified by the alphanumeric characters of the POSIX
locale. There shall also be one "unnamed" buffer. When no buffer is
specified for editor commands that use a buffer, the unnamed
buffer shall be used. Commands that store text into buffers shall
store the text as it was before the command took effect, and
shall store text occurring earlier in the file before text occurring
later in the file, regardless of how the text region was
specified. Commands that store text into buffers shall store the text
into the unnamed buffer as well as any specified buffer. 
.LP
In \fIex\fP commands, buffer names are specified as the name by itself.
In open or visual mode commands the name is preceded by
a double quote ( \fB' )'\fP character.
.LP
If the specified buffer name is an uppercase character, and the buffer
contents are to be modified, the buffer shall be appended
to rather than being overwritten. If the buffer is not being modified,
specifying the buffer name in lowercase and uppercase shall
have identical results.
.LP
There shall also be buffers named by the numbers 1 through 9. In open
and visual mode, if a region of text including characters
from more than a single line is being modified by the \fIvi\fP \fBc\fP
or \fBd\fP commands,
the motion character associated with the \fBc\fP or \fBd\fP commands
specifies that the buffer text shall be in line mode, or the
commands \fB%\fP, \fB`\fP, \fB/\fP, \fB?\fP, \fB(\fP, \fB)\fP, \fBN\fP,
\fBn\fP, \fB{\fP, or \fB}\fP are used to define a
region of text for the \fBc\fP or \fBd\fP commands, the contents of
buffers 1 through 8 shall be moved into the buffer named by
the next numerically greater value, the contents of buffer 9 shall
be discarded, and the region of text shall be copied into buffer
1. This shall be in addition to copying the text into a user-specified
buffer or unnamed buffer, or both. Numeric buffers can be
specified as a source buffer for open and visual mode commands; however,
specifying a numeric buffer as the write target of an open
or visual mode command shall have unspecified results.
.LP
The text of each buffer shall have the characteristic of being in
either line or character mode. Appending text to a non-empty
buffer shall set the mode to match the characteristic of the text
being appended. Appending text to a buffer shall cause the
creation of at least one additional line in the buffer. All text stored
into buffers by \fIex\fP commands shall be in line mode.
The \fIex\fP commands that use buffers as the source of text specify
individually how buffers of different modes are handled. Each
open or visual mode command that uses buffers for any purpose specifies
individually the mode of the text stored into the buffer
and how buffers of different modes are handled.
.TP 7
\fIfile\fP
Command text used to derive a pathname. The default shall be the current
pathname, as defined previously, in which case, if no
current pathname has yet been established it shall be an error, except
where specifically noted in the individual command
descriptions that follow. If the command text contains any of the
characters \fB'~'\fP , \fB'{'\fP , \fB'['\fP ,
\fB'*'\fP , \fB'?'\fP , \fB'$'\fP , \fB'`'\fP , \fB'"\fP , \fB' ,'\fP
and \fB'\\'\fP , it shall be subjected
to the process of "shell expansions", as described below; if more
than a single pathname results and the command expects only
one, it shall be an error. 
.LP
The process of shell expansions in the editor shall be done as follows.
The \fIex\fP utility shall pass two arguments to the
program named by the shell edit option; the first shall be \fB-c\fP,
and the second shall be the string \fB"echo"\fP and the
command text as a single argument. The standard output and standard
error of that command shall replace the command text.
.TP 7
\fB!\fP
A character that can be appended to the command name to modify its
operation, as detailed in the individual command
descriptions. With the exception of the \fIex\fP \fBread\fP, \fBwrite\fP,
and \fB!\fP commands, the \fB'!'\fP character
shall only act as a modifier if there are no <blank>s between it and
the command name.
.TP 7
\fIremembered\ search\ direction\fP
.sp
The \fIvi\fP commands \fBN\fP and \fBn\fP begin searching in a forwards
or backwards
direction in the edit buffer based on a remembered search direction,
which is initially unset, and is set by the \fIex\fP
\fBglobal\fP, \fBv\fP, \fBs\fP, and \fBtag\fP commands, and the \fIvi\fP
\fB/\fP and
\fB?\fP commands.
.sp
.SS Abbreviate
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBab\fP\fB[\fP\fIbreviate\fP\fB][\fP\fIlhs rhs\fP\fB]\fP
.fi
.RE
.sp
.LP
If \fIlhs\fP and \fIrhs\fP are not specified, write the current list
of abbreviations and do nothing more.
.LP
Implementations may restrict the set of characters accepted in \fIlhs\fP
or \fIrh\fP, except that printable characters and
<blank>s shall not be restricted. Additional restrictions shall be
implementation-defined.
.LP
In both \fIlhs\fP and \fIrhs\fP, any character may be escaped with
a <control>-V, in which case the character shall not
be used to delimit \fIlhs\fP from \fIrhs\fP, and the escaping <control>-V
shall be discarded.
.LP
In open and visual text input mode, if a non-word or <ESC> character
that is not escaped by a <control>-V character
is entered after a word character, a check shall be made for a set
of characters matching \fIlhs\fP, in the text input entered
during this command. If it is found, the effect shall be as if \fIrhs\fP
was entered instead of \fIlhs\fP.
.LP
The set of characters that are checked is defined as follows:
.IP " 1." 4
If there are no characters inserted before the word and non-word or
<ESC> characters that triggered the check, the set of
characters shall consist of the word character.
.LP
.IP " 2." 4
If the character inserted before the word and non-word or <ESC> characters
that triggered the check is a word character,
the set of characters shall consist of the characters inserted immediately
before the triggering characters that are word
characters, plus the triggering word character.
.LP
.IP " 3." 4
If the character inserted before the word and non-word or <ESC> characters
that triggered the check is not a word
character, the set of characters shall consist of the characters that
were inserted before the triggering characters that are
neither <blank>s nor word characters, plus the triggering word character.
.LP
.LP
It is unspecified whether the \fIlhs\fP argument entered for the \fIex\fP
\fBabbreviate\fP and \fBunabbreviate\fP commands
is replaced in this fashion. Regardless of whether or not the replacement
occurs, the effect of the command shall be as if the
replacement had not occurred.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Append
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI1addr\fP\fB]\fP \fBa\fP\fB[\fP\fBppend\fP\fB][\fP\fB!\fP\fB]\fP
.fi
.RE
.sp
.LP
Enter \fIex\fP text input mode; the input text shall be placed after
the specified line. If line zero is specified, the text
shall be placed at the beginning of the edit buffer.
.LP
This command shall be affected by the \fBnumber\fP and \fBautoindent\fP
edit options; following the command name with
\fB'!'\fP shall cause the \fBautoindent\fP edit option setting to
be toggled for the duration of this command only.
.LP
\fICurrent line\fP: Set to the last input line; if no lines were input,
set to the specified line, or to the first line of the
edit buffer if a line of zero was specified, or zero if the edit buffer
is empty.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Arguments
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBar\fP\fB[\fP\fIgs\fP\fB]\fP
.fi
.RE
.sp
.LP
Write the current argument list, with the current argument-list entry,
if any, between \fB'['\fP and \fB']'\fP
characters.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Change
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBc\fP\fB[\fP\fBhange\fP\fB][\fP\fB!\fP\fB][\fP\fIcount\fP\fB]\fP
.fi
.RE
.sp
.LP
Enter \fIex\fP text input mode; the input text shall replace the specified
lines. The specified lines shall be copied into the
unnamed buffer, which shall become a line mode buffer.
.LP
This command shall be affected by the \fBnumber\fP and \fBautoindent\fP
edit options; following the command name with
\fB'!'\fP shall cause the \fBautoindent\fP edit option setting to
be toggled for the duration of this command only.
.LP
\fICurrent line\fP: Set to the last input line; if no lines were input,
set to the line before the first address, or to the
first line of the edit buffer if there are no lines preceding the
first address, or to zero if the edit buffer is empty.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Change Directory
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBchd\fP\fB[\fP\fBir\fP\fB][\fP\fB!\fP\fB][\fP\fIdirectory\fP\fB]\fP\fBcd\fP\fB[\fP\fB!\fP\fB][\fP\fIdirectory\fP\fB]\fP
.fi
.RE
.sp
.LP
Change the current working directory to \fIdirectory\fP.
.LP
If no \fIdirectory\fP argument is specified, and the \fIHOME\fP environment
variable is set to a non-null and non-empty value,
\fIdirectory\fP shall default to the value named in the \fIHOME\fP
environment variable. If the \fIHOME\fP environment variable
is empty or is undefined, the default value of \fIdirectory\fP is
implementation-defined.
.LP
If no \fB'!'\fP is appended to the command name, and the edit buffer
has been modified since the last complete write, and the
current pathname does not begin with a \fB'/'\fP , it shall be an
error.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Copy
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBco\fP\fB[\fP\fBpy\fP\fB]\fP \fI1addr\fP \fB[\fP\fIflags\fP\fB]
[\fP\fI2addr\fP\fB]\fP \fBt\fP \fI1addr\fP \fB[\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
Copy the specified lines after the specified destination line; line
zero specifies that the lines shall be placed at the
beginning of the edit buffer.
.LP
\fICurrent line\fP: Set to the last line copied.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Delete
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBd\fP\fB[\fP\fBelete\fP\fB][\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
Delete the specified lines into a buffer (defaulting to the unnamed
buffer), which shall become a line-mode buffer.
.LP
Flags can immediately follow the command name; see Command Line Parsing
in ex .
.LP
\fICurrent line\fP: Set to the line following the deleted lines, or
to the last line in the edit buffer if that line is past
the end of the edit buffer, or to zero if the edit buffer is empty.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Edit
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBe\fP\fB[\fP\fBdit\fP\fB][\fP\fB!\fP\fB][\fP\fB+\fP\fIcommand\fP\fB][\fP\fIfile\fP\fB]\fP\fBex\fP\fB[\fP\fB!\fP\fB][\fP\fB+\fP\fIcommand\fP\fB][\fP\fIfile\fP\fB]\fP
.fi
.RE
.sp
.LP
If no \fB'!'\fP is appended to the command name, and the edit buffer
has been modified since the last complete write, it
shall be an error.
.LP
If \fIfile\fP is specified, replace the current contents of the edit
buffer with the current contents of \fIfile\fP, and set
the current pathname to \fIfile\fP. If \fIfile\fP is not specified,
replace the current contents of the edit buffer with the
current contents of the file named by the current pathname. If for
any reason the current contents of the file cannot be accessed,
the edit buffer shall be empty.
.LP
The \fB+\fP \fIcommand\fP option shall be <blank>-delimited; <blank>s
within \fB+\fP \fIcommand\fP can be
escaped by preceding them with a backslash character. The \fB+\fP
\fIcommand\fP shall be interpreted as an \fIex\fP command
immediately after the contents of the edit buffer have been replaced
and the current line and column have been set.
.LP
If the edit buffer is empty:
.LP
\fICurrent line\fP: Set to 0.
.LP
\fICurrent column\fP: Set to 1.
.LP
Otherwise, if executed while in \fIex\fP command mode or if the \fB+\fP
\fIcommand\fP argument is specified:
.LP
\fICurrent line\fP: Set to the last line of the edit buffer.
.LP
\fICurrent column\fP: Set to non- <blank>.
.LP
Otherwise, if \fIfile\fP is omitted or results in the current pathname:
.LP
\fICurrent line\fP: Set to the first line of the edit buffer.
.LP
\fICurrent column\fP: Set to non- <blank>.
.LP
Otherwise, if \fIfile\fP is the same as the last file edited, the
line and column shall be set as follows; if the file was
previously edited, the line and column may be set as follows:
.LP
\fICurrent line\fP: Set to the last value held when that file was
last edited. If this value is not a valid line in the new
edit buffer, set to the first line of the edit buffer.
.LP
\fICurrent column\fP: If the current line was set to the last value
held when the file was last edited, set to the last value
held when the file was last edited. Otherwise, or if the last value
is not a valid column in the new edit buffer, set to non-
<blank>.
.LP
Otherwise:
.LP
\fICurrent line\fP: Set to the first line of the edit buffer.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS File
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBf\fP\fB[\fP\fBile\fP\fB][\fP\fIfile\fP\fB]\fP
.fi
.RE
.sp
.LP
If a \fIfile\fP argument is specified, the alternate pathname shall
be set to the current pathname, and the current pathname
shall be set to \fIfile\fP.
.LP
Write an informational message. If the file has a current pathname,
it shall be included in this message; otherwise, the message
shall indicate that there is no current pathname. If the edit buffer
contains lines, the current line number and the number of
lines in the edit buffer shall be included in this message; otherwise,
the message shall indicate that the edit buffer is empty. If
the edit buffer has been modified since the last complete write, this
fact shall be included in this message. If the
\fBreadonly\fP edit option is set, this fact shall be included in
this message. The message may contain other unspecified
information.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Global
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBg\fP\fB[\fP\fBlobal\fP\fB]\fP \fB/\fP\fIpattern\fP\fB/\fP \fB[\fP\fIcommands\fP\fB]
[\fP\fI2addr\fP\fB]\fP \fBv /\fP\fIpattern\fP\fB/\fP \fB[\fP\fIcommands\fP\fB]\fP
.fi
.RE
.sp
.LP
The optional \fB'!'\fP character after the \fBglobal\fP command shall
be the same as executing the \fBv\fP command.
.LP
If \fIpattern\fP is empty (for example, \fB"//"\fP ) or not specified,
the last regular expression used in the editor
command shall be used as the \fIpattern\fP. The \fIpattern\fP can
be delimited by slashes (shown in the Synopsis), as well as any
non-alphanumeric or non- <blank> other than backslash, vertical line,
double quote, or <newline>.
.LP
If no lines are specified, the lines shall default to the entire file.
.LP
The \fBglobal\fP and \fBv\fP commands are logically two-pass operations.
First, mark the lines within the specified lines for
which the line excluding the terminating <newline> matches ( \fBglobal\fP)
or does not match ( \fBv\fP or \fBglobal!\fP)
the specified pattern. Second, execute the \fIex\fP commands given
by \fIcommands\fP, with the current line ( \fB'.'\fP ) set
to each marked line. If an error occurs during this process, or the
contents of the edit buffer are replaced (for example, by the
\fIex\fP \fB:edit\fP command) an error message shall be written and
no more commands resulting from the execution of this command
shall be processed.
.LP
Multiple \fIex\fP commands can be specified by entering multiple commands
on a single line using a vertical line to delimit
them, or one per line, by escaping each <newline> with a backslash.
.LP
If no commands are specified:
.IP " 1." 4
If in \fIex\fP command mode, it shall be as if the \fBprint\fP command
were specified.
.LP
.IP " 2." 4
Otherwise, no command shall be executed.
.LP
.LP
For the \fBappend\fP, \fBchange\fP, and \fBinsert\fP commands, the
input text shall be included as part of the command, and
the terminating period can be omitted if the command ends the list
of commands. The \fBopen\fP and \fBvisual\fP commands can be
specified as one of the commands, in which case each marked line shall
cause the editor to enter open or visual mode. If open or
visual mode is exited using the \fIvi\fP \fBQ\fP command, the current
line shall be set to the
next marked line, and open or visual mode reentered, until the list
of marked lines is exhausted.
.LP
The \fBglobal\fP, \fBv\fP, and \fBundo\fP commands cannot be used
in \fIcommands\fP. Marked lines may be deleted by commands
executed for lines occurring earlier in the file than the marked lines.
In this case, no commands shall be executed for the deleted
lines.
.LP
If the remembered search direction is not set, the \fBglobal\fP and
\fBv\fP commands shall set it to forward.
.LP
The \fBautoprint\fP and \fBautoindent\fP edit options shall be inhibited
for the duration of the \fBg\fP or \fBv\fP
command.
.LP
\fICurrent line\fP: If no commands executed, set to the last marked
line. Otherwise, as specified for the executed \fIex\fP
commands.
.LP
\fICurrent column\fP: If no commands are executed, set to non- <blank>;
otherwise, as specified for the individual
\fIex\fP commands.
.SS Insert
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI1addr\fP\fB]\fP \fBi\fP\fB[\fP\fBnsert\fP\fB][\fP\fB!\fP\fB]\fP
.fi
.RE
.sp
.LP
Enter \fIex\fP text input mode; the input text shall be placed before
the specified line. If the line is zero or 1, the text
shall be placed at the beginning of the edit buffer.
.LP
This command shall be affected by the \fBnumber\fP and \fBautoindent\fP
edit options; following the command name with
\fB'!'\fP shall cause the \fBautoindent\fP edit option setting to
be toggled for the duration of this command only.
.LP
\fICurrent line\fP: Set to the last input line; if no lines were input,
set to the line before the specified line, or to the
first line of the edit buffer if there are no lines preceding the
specified line, or zero if the edit buffer is empty.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Join
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBj\fP\fB[\fP\fBoin\fP\fB][\fP\fB!\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
If \fIcount\fP is specified:
If no address was specified, the \fBjoin\fP command shall behave as
if \fI2addr\fP were the current line and the
current line plus \fIcount\fP (.,. + \fIcount\fP). 
.LP
If one address was specified, the \fBjoin\fP command shall behave
as if \fI2addr\fP were the specified address and the
specified address plus \fIcount\fP ( \fIaddr\fP, \fIaddr\fP + \fIcount\fP).
.LP
If two addresses were specified, the \fBjoin\fP command shall behave
as if an additional address, equal to the last address
plus \fIcount\fP -1 ( \fIaddr1\fP, \fIaddr2\fP, \fIaddr2\fP + \fIcount\fP
-1), was specified.
.LP
If this would result in a second address greater than the last line
of the edit buffer, it shall be corrected to be equal to the
last line of the edit buffer.
.LP
If no \fIcount\fP is specified:
If no address was specified, the \fBjoin\fP command shall behave as
if \fI2addr\fP were the current line and the next
line (.,. +1). 
.LP
If one address was specified, the \fBjoin\fP command shall behave
as if \fI2addr\fP were the specified address and the next
line ( \fIaddr\fP, \fIaddr\fP +1).
.LP
Join the text from the specified lines together into a single line,
which shall replace the specified lines.
.LP
If a \fB'!'\fP character is appended to the command name, the \fBjoin\fP
shall be without modification of any line,
independent of the current locale.
.LP
Otherwise, in the POSIX locale, set the current line to the first
of the specified lines, and then, for each subsequent line,
proceed as follows:
.IP " 1." 4
Discard leading <space>s from the line to be joined.
.LP
.IP " 2." 4
If the line to be joined is now empty, delete it, and skip steps 3
through 5.
.LP
.IP " 3." 4
If the current line ends in a <blank>, or the first character of the
line to be joined is a \fB')'\fP character, join
the lines without further modification.
.LP
.IP " 4." 4
If the last character of the current line is a \fB'.'\fP , join the
lines with two <space>s between them.
.LP
.IP " 5." 4
Otherwise, join the lines with a single <space> between them.
.LP
.LP
\fICurrent line\fP: Set to the first line specified.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS List
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBl\fP\fB[\fP\fBist\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
This command shall be equivalent to the \fIex\fP command:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBp\fP\fB[\fP\fBrint\fP\fB][\fP\fIcount\fP\fB]\fP \fBl\fP\fB[\fP\fIflags\fP\fB]\fP
.fi
.RE
.LP
See Print .
.SS Map
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBmap\fP\fB[\fP\fB!\fP\fB][\fP\fIlhs rhs\fP\fB]\fP
.fi
.RE
.sp
.LP
If \fIlhs\fP and \fIrhs\fP are not specified:
.IP " 1." 4
If \fB'!'\fP is specified, write the current list of text input mode
maps.
.LP
.IP " 2." 4
Otherwise, write the current list of command mode maps.
.LP
.IP " 3." 4
Do nothing more.
.LP
.LP
Implementations may restrict the set of characters accepted in \fIlhs\fP
or \fIrhs\fP, except that printable characters and
<blank>s shall not be restricted. Additional restrictions shall be
implementation-defined. In both \fIlhs\fP and \fIrhs\fP,
any character can be escaped with a <control>-V, in which case the
character shall not be used to delimit \fIlhs\fP from
\fIrhs\fP, and the escaping <control>-V shall be discarded.
.LP
If the character \fB'!'\fP is appended to the \fBmap\fP command name,
the mapping shall be effective during open or visual
text input mode rather than \fBopen\fP or \fBvisual\fP command mode.
This allows \fIlhs\fP to have two different \fBmap\fP
definitions at the same time: one for command mode and one for text
input mode.
.LP
For command mode mappings:
When the \fIlhs\fP is entered as any part of a \fIvi\fP command in
open or visual
mode (but not as part of the arguments to the command), the action
shall be as if the corresponding \fIrhs\fP had been entered. 
.LP
If any character in the command, other than the first, is escaped
using a <control>-V character, that character shall not
be part of a match to an \fIlhs\fP.
.LP
It is unspecified whether implementations shall support \fBmap\fP
commands where the \fIlhs\fP is more than a single character
in length, where the first character of the \fIlhs\fP is printable.
.LP
If \fIlhs\fP contains more than one character and the first character
is \fB'#'\fP , followed by a sequence of digits
corresponding to a numbered function key, then when this function
key is typed it shall be mapped to \fIrhs\fP. Characters other
than digits following a \fB'#'\fP character also represent the function
key named by the characters in the \fIlhs\fP following
the \fB'#'\fP and may be mapped to \fIrhs\fP. It is unspecified how
function keys are named or what function keys are
supported.
.LP
For text input mode mappings:
When the \fIlhs\fP is entered as any part of text entered in open
or visual text input modes, the action shall be as
if the corresponding \fIrhs\fP had been entered. 
.LP
If any character in the input text is escaped using a <control>-V
character, that character shall not be part of a match
to an \fIlhs\fP.
.LP
It is unspecified whether the \fIlhs\fP text entered for subsequent
\fBmap\fP or \fBunmap\fP commands is replaced with the
\fIrhs\fP text for the purposes of the screen display; regardless
of whether or not the display appears as if the corresponding
\fIrhs\fP text was entered, the effect of the command shall be as
if the \fIlhs\fP text was entered.
.LP
If only part of the \fIlhs\fP is entered, it is unspecified how long
the editor will wait for additional, possibly matching
characters before treating the already entered characters as not matching
the \fIlhs\fP.
.LP
The \fIrhs\fP characters shall themselves be subject to remapping,
unless otherwise specified by the \fBremap\fP edit option,
except that if the characters in \fIlhs\fP occur as prefix characters
in \fIrhs\fP, those characters shall not be remapped.
.LP
On block-mode terminals, the mapping need not occur immediately (for
example, it may occur after the terminal transmits a group
of characters to the system), but it shall achieve the same results
as if it occurred immediately.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Mark
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI1addr\fP\fB]\fP \fBma\fP\fB[\fP\fBrk\fP\fB]\fP \fIcharacter
\fP\fB[\fP\fI1addr\fP\fB]\fP \fBk\fP \fIcharacter\fP
.fi
.RE
.sp
.LP
Implementations shall support \fIcharacter\fP values of a single lowercase
letter of the POSIX locale and the characters
\fB'`'\fP and \fB'"\fP ; support of other characters is implementation-defined.
.LP
If executing the \fIvi\fP \fBm\fP command, set the specified mark
to the current line and
1-based numbered character referenced by the current column, if any;
otherwise, column position 1.
.LP
Otherwise, set the specified mark to the specified line and 1-based
numbered first non- <blank> non- <newline> in
the line, if any; otherwise, the last non- <newline> in the line,
if any; otherwise, column position 1.
.LP
The mark shall remain associated with the line until the mark is reset
or the line is deleted. If a deleted line is restored by
a subsequent \fBundo\fP command, any marks previously associated with
the line, which have not been reset, shall be restored as
well. Any use of a mark not associated with a current line in the
edit buffer shall be an error.
.LP
The marks \fB`\fP and \fB'\fP shall be set as described previously,
immediately before the following events occur in the
editor:
.IP " 1." 4
The use of \fB'$'\fP as an \fIex\fP address
.LP
.IP " 2." 4
The use of a positive decimal number as an \fIex\fP address
.LP
.IP " 3." 4
The use of a search command as an \fIex\fP address
.LP
.IP " 4." 4
The use of a mark reference as an \fIex\fP address
.LP
.IP " 5." 4
The use of the following open and visual mode commands: <control>-],
\fB%\fP, \fB(\fP, \fB)\fP, \fB[\fP, \fB]\fP,
\fB{\fP, \fB}\fP
.LP
.IP " 6." 4
The use of the following open and visual mode commands: \fB'\fP, \fBG\fP,
\fBH\fP, \fBL\fP, \fBM\fP, \fBz\fP if the
current line will change as a result of the command
.LP
.IP " 7." 4
The use of the open and visual mode commands: \fB/\fP, \fB?\fP, \fBN\fP,
\fB`\fP, \fBn\fP if the current line or column
will change as a result of the command
.LP
.IP " 8." 4
The use of the \fIex\fP mode commands: \fBz\fP, \fBundo\fP, \fBglobal\fP,
\fBv\fP
.LP
.LP
For rules 1., 2., 3., and 4., the \fB`\fP and \fB'\fP marks shall
not be set if the \fIex\fP command is parsed as specified
by rule 6.a. in Command Line Parsing in ex .
.LP
For rules 5., 6., and 7., the \fB`\fP and \fB'\fP marks shall not
be set if the commands are used as motion commands in open
and visual mode.
.LP
For rules 1., 2., 3., 4., 5., 6., 7., and 8., the \fB`\fP and \fB'\fP
marks shall not be set if the command fails.
.LP
The \fB`\fP and \fB'\fP marks shall be set as described previously,
each time the contents of the edit buffer are replaced
(including the editing of the initial buffer), if in open or visual
mode, or if in \fBex\fP mode and the edit buffer is not empty,
before any commands or movements (including commands or movements
specified by the \fB-c\fP or \fB-t\fP options or the \fB+\fP
\fIcommand\fP argument) are executed on the edit buffer. If in open
or visual mode, the marks shall be set as if executing the \fIvi\fP
\fBm\fP command; otherwise, as if executing the \fIex\fP \fBmark\fP
command.
.LP
When changing from \fBex\fP mode to open or visual mode, if the \fB`\fP
and \fB'\fP marks are not already set, the \fB`\fP
and \fB'\fP marks shall be set as described previously.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Move
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBm\fP\fB[\fP\fBove\fP\fB]\fP \fI1addr\fP \fB\fP\fB[\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
Move the specified lines after the specified destination line. A destination
of line zero specifies that the lines shall be
placed at the beginning of the edit buffer. It shall be an error if
the destination line is within the range of lines to be
moved.
.LP
\fICurrent line\fP: Set to the last of the moved lines.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Next
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBn\fP\fB[\fP\fBext\fP\fB][\fP\fB!\fP\fB][\fP\fB+\fP\fIcommand\fP\fB][\fP\fIfile\fP \fB...\fP\fB]\fP
.fi
.RE
.sp
.LP
If no \fB'!'\fP is appended to the command name, and the edit buffer
has been modified since the last complete write, it
shall be an error, unless the file is successfully written as specified
by the \fBautowrite\fP option.
.LP
If one or more files is specified:
.IP " 1." 4
Set the argument list to the specified filenames.
.LP
.IP " 2." 4
Set the current argument list reference to be the first entry in the
argument list.
.LP
.IP " 3." 4
Set the current pathname to the first filename specified.
.LP
.LP
Otherwise:
.IP " 1." 4
It shall be an error if there are no more filenames in the argument
list after the filename currently referenced.
.LP
.IP " 2." 4
Set the current pathname and the current argument list reference to
the filename after the filename currently referenced in the
argument list.
.LP
.LP
Replace the contents of the edit buffer with the contents of the file
named by the current pathname. If for any reason the
contents of the file cannot be accessed, the edit buffer shall be
empty.
.LP
This command shall be affected by the \fBautowrite\fP and \fBwriteany\fP
edit options.
.LP
The \fB+\fP \fIcommand\fP option shall be <blank>-delimited; <blank>s
can be escaped by preceding them with a
backslash character. The \fB+\fP \fIcommand\fP shall be interpreted
as an \fIex\fP command immediately after the contents of the
edit buffer have been replaced and the current line and column have
been set.
.LP
\fICurrent line\fP: Set as described for the \fBedit\fP command.
.LP
\fICurrent column\fP: Set as described for the \fBedit\fP command.
.SS Number
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBnu\fP\fB[\fP\fBmber\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]
[\fP\fI2addr\fP\fB]\fP \fB#\fP\fB[\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
These commands shall be equivalent to the \fIex\fP command:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBp\fP\fB[\fP\fBrint\fP\fB][\fP\fIcount\fP\fB]\fP \fB#\fP\fB[\fP\fIflags\fP\fB]\fP
.fi
.RE
.LP
See Print .
.SS Open
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI1addr\fP\fB]\fP \fBo\fP\fB[\fP\fBpen\fP\fB]\fP \fB/\fP\fIpattern\fP\fB/\fP \fB[\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
This command need not be supported on block-mode terminals or terminals
with insufficient capabilities. If standard input,
standard output, or standard error are not terminal devices, the results
are unspecified.
.LP
Enter open mode.
.LP
The trailing delimiter can be omitted from \fIpattern\fP at the end
of the command line. If \fIpattern\fP is empty (for
example, \fB"//"\fP ) or not specified, the last regular expression
used in the editor shall be used as the pattern. The pattern
can be delimited by slashes (shown in the Synopsis), as well as any
alphanumeric, or non- <blank> other than backslash,
vertical line, double quote, or <newline>.
.LP
\fICurrent line\fP: Set to the specified line.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Preserve
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBpre\fP\fB[\fP\fBserve\fP\fB]\fP
.fi
.RE
.sp
.LP
Save the edit buffer in a form that can later be recovered by using
the \fB-r\fP option or by using the \fIex\fP
\fBrecover\fP command. After the file has been preserved, a mail message
shall be sent to the user. This message shall be readable
by invoking the \fImailx\fP utility. The message shall contain the
name of the file, the
time of preservation, and an \fIex\fP command that could be used to
recover the file. Additional information may be included in
the mail message.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Print
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBp\fP\fB[\fP\fBrint\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
Write the addressed lines. The behavior is unspecified if the number
of columns on the display is less than the number of
columns required to write any single character in the lines being
written.
.LP
Non-printable characters, except for the <tab>, shall be written as
implementation-defined multi-character sequences.
.LP
If the \fB#\fP flag is specified or the \fBnumber\fP edit option is
set, each line shall be preceded by its line number in the
following format:
.sp
.RS
.nf

\fB"%6d  ", <\fP\fIline number\fP\fB>
\fP
.fi
.RE
.LP
If the \fBl\fP flag is specified or the \fBlist\fP edit option is
set:
.IP " 1." 4
The characters listed in the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Table 5-1, Escape Sequences and
Associated Actions shall be written as the corresponding escape sequence.
.LP
.IP " 2." 4
Non-printable characters not in the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Table 5-1, Escape Sequences and
Associated Actions shall be written as one three-digit octal number
(with a preceding backslash) for each byte in the character
(most significant byte first). If the size of a byte on the system
is greater than 9 bits, the format used for non-printable
characters is implementation-defined.
.LP
.IP " 3." 4
The end of each line shall be marked with a \fB'$'\fP , and literal
\fB'$'\fP characters within the line shall be written
with a preceding backslash.
.LP
.LP
Long lines shall be folded; the length at which folding occurs is
unspecified, but should be appropriate for the output
terminal, considering the number of columns of the terminal.
.LP
If a line is folded, and the \fBl\fP flag is not specified and the
\fBlist\fP edit option is not set, it is unspecified
whether a multi-column character at the folding position is separated;
it shall not be discarded.
.LP
\fICurrent line\fP: Set to the last written line.
.LP
\fICurrent column\fP: Unchanged if the current line is unchanged;
otherwise, set to non- <blank>.
.SS Put
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI1addr\fP\fB]\fP \fBpu\fP\fB[\fP\fBt\fP\fB][\fP\fIbuffer\fP\fB]\fP
.fi
.RE
.sp
.LP
Append text from the specified buffer (by default, the unnamed buffer)
to the specified line; line zero specifies that the text
shall be placed at the beginning of the edit buffer. Each portion
of a line in the buffer shall become a new line in the edit
buffer, regardless of the mode of the buffer.
.LP
\fICurrent line\fP: Set to the last line entered into the edit buffer.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Quit
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBq\fP\fB[\fP\fBuit\fP\fB][\fP\fB!\fP\fB]\fP
.fi
.RE
.sp
.LP
If no \fB'!'\fP is appended to the command name:
.IP " 1." 4
If the edit buffer has been modified since the last complete write,
it shall be an error.
.LP
.IP " 2." 4
If there are filenames in the argument list after the filename currently
referenced, and the last command was not a \fBquit\fP,
\fBwq\fP, \fBxit\fP, or \fBZZ\fP (see \fIExit\fP ) command, it shall
be an error.
.LP
.LP
Otherwise, terminate the editing session.
.SS Read
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI1addr\fP\fB]\fP \fBr\fP\fB[\fP\fBead\fP\fB][\fP\fB!\fP\fB][\fP\fIfile\fP\fB]\fP
.fi
.RE
.sp
.LP
If \fB'!'\fP is not the first non- <blank> to follow the command name,
a copy of the specified file shall be appended
into the edit buffer after the specified line; line zero specifies
that the copy shall be placed at the beginning of the edit
buffer. The number of lines and bytes read shall be written. If no
\fIfile\fP is named, the current pathname shall be the default.
If there is no current pathname, then \fIfile\fP shall become the
current pathname. If there is no current pathname or \fIfile\fP
operand, it shall be an error. Specifying a \fIfile\fP that is not
of type regular shall have unspecified results.
.LP
Otherwise, if \fIfile\fP is preceded by \fB'!'\fP , the rest of the
line after the \fB'!'\fP shall have \fB'%'\fP ,
\fB'#'\fP , and \fB'!'\fP characters expanded as described in Command
Line Parsing in ex .
.LP
The \fIex\fP utility shall then pass two arguments to the program
named by the shell edit option; the first shall be \fB-c\fP
and the second shall be the expanded arguments to the \fBread\fP command
as a single argument. The standard input of the program
shall be set to the standard input of the \fIex\fP program when it
was invoked. The standard error and standard output of the
program shall be appended into the edit buffer after the specified
line.
.LP
Each line in the copied file or program output (as delimited by <newline>s
or the end of the file or output if it is not
immediately preceded by a <newline>), shall be a separate line in
the edit buffer. Any occurrences of <carriage-return>
and <newline> pairs in the output shall be treated as single <newline>s.
.LP
The special meaning of the \fB'!'\fP following the \fBread\fP command
can be overridden by escaping it with a backslash
character.
.LP
\fICurrent line\fP: If no lines are added to the edit buffer, unchanged.
Otherwise, if in open or visual mode, set to the first
line entered into the edit buffer. Otherwise, set to the last line
entered into the edit buffer.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Recover
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBrec\fP\fB[\fP\fBover\fP\fB][\fP\fB!\fP\fB]\fP \fIfile\fP
.fi
.RE
.sp
.LP
If no \fB'!'\fP is appended to the command name, and the edit buffer
has been modified since the last complete write, it
shall be an error.
.LP
If no \fIfile\fP operand is specified, then the current pathname shall
be used. If there is no current pathname or \fIfile\fP
operand, it shall be an error.
.LP
If no recovery information has previously been saved about \fIfile\fP,
the \fBrecover\fP command shall behave identically to
the \fBedit\fP command, and an informational message to this effect
shall be written.
.LP
Otherwise, set the current pathname to \fIfile\fP, and replace the
current contents of the edit buffer with the recovered
contents of \fIfile\fP. If there are multiple instances of the file
to be recovered, the one most recently saved shall be
recovered, and an informational message that there are previous versions
of the file that can be recovered shall be written. The
editor shall behave as if the contents of the edit buffer have already
been modified.
.LP
\fICurrent file\fP: Set as described for the \fBedit\fP command.
.LP
\fICurrent column\fP: Set as described for the \fBedit\fP command.
.SS Rewind
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBrew\fP\fB[\fP\fBind\fP\fB][\fP\fB!\fP\fB]\fP
.fi
.RE
.sp
.LP
If no \fB'!'\fP is appended to the command name, and the edit buffer
has been modified since the last complete write, it
shall be an error, unless the file is successfully written as specified
by the \fBautowrite\fP option.
.LP
If the argument list is empty, it shall be an error.
.LP
The current argument list reference and the current pathname shall
be set to the first filename in the argument list.
.LP
Replace the contents of the edit buffer with the contents of the file
named by the current pathname. If for any reason the
contents of the file cannot be accessed, the edit buffer shall be
empty.
.LP
This command shall be affected by the \fBautowrite\fP and \fBwriteany\fP
edit options.
.LP
\fICurrent line\fP: Set as described for the \fBedit\fP command.
.LP
\fICurrent column\fP: Set as described for the \fBedit\fP command.
.SS Set
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBse\fP\fB[\fP\fBt\fP\fB][\fP\fIoption\fP\fB[\fP\fB=\fP\fB[\fP\fIvalue\fP\fB]]\fP \fB...\fP\fB][\fP\fBno\fP\fIoption\fP \fB...\fP\fB][\fP\fIoption\fP\fB? ...\fP\fB][\fP\fBall\fP\fB]\fP
.fi
.RE
.sp
.LP
When no arguments are specified, write the value of the \fBterm\fP
edit option and those options whose values have been changed
from the default settings; when the argument \fIall\fP is specified,
write all of the option values.
.LP
Giving an option name followed by the character \fB'?'\fP shall cause
the current value of that option to be written. The
\fB'?'\fP can be separated from the option name by zero or more <blank>s.
The \fB'?'\fP shall be necessary only for
Boolean valued options. Boolean options can be given values by the
form \fBset\fP \fIoption\fP to turn them on or \fBset\fP
\fBno\fP \fIoption\fP to turn them off; string and numeric options
can be assigned by the form \fBset\fP \fIoption\fP=
\fIvalue\fP. Any <blank>s in strings can be included as is by preceding
each <blank> with an escaping backslash. More
than one option can be set or listed by a single set command by specifying
multiple arguments, each separated from the next by one
or more <blank>s.
.LP
See Edit Options in ex for details about specific options.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Shell
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBsh\fP\fB[\fP\fBell\fP\fB]\fP
.fi
.RE
.sp
.LP
Invoke the program named in the \fBshell\fP edit option with the single
argument \fB-i\fP (interactive mode). Editing shall be
resumed when the program exits.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Source
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBso\fP\fB[\fP\fBurce\fP\fB]\fP \fIfile\fP
.fi
.RE
.sp
.LP
Read and execute \fIex\fP commands from \fIfile\fP. Lines in the file
that are blank lines shall be ignored.
.LP
\fICurrent line\fP: As specified for the individual \fIex\fP commands.
.LP
\fICurrent column\fP: As specified for the individual \fIex\fP commands.
.SS Substitute
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBs\fP\fB[\fP\fBubstitute\fP\fB][\fP\fB/\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB/\fP\fB[\fP\fIoptions\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]]\fP\fB
.br

\fP\fB[\fP\fI2addr\fP\fB]\fP \fB&\fP\fB[\fP\fIoptions\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]]\fP\fB
.br

\fP\fB[\fP\fI2addr\fP\fB]\fP \fB~\fP\fB[\fP\fIoptions\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]]\fP
.fi
.RE
.sp
.LP
Replace the first instance of the pattern \fIpattern\fP by the string
\fIrepl\fP on each specified line. (See Regular Expressions in ex
and Replacement Strings in ex .) Any
non-alphabetic, non- <blank> delimiter other than \fB'\\'\fP , \fB'|'\fP
, double quote, or <newline> can be used
instead of \fB'/'\fP . Backslash characters can be used to escape
delimiters, backslash characters, and other special
characters.
.LP
The trailing delimiter can be omitted from \fIpattern\fP or from \fIrepl\fP
at the end of the command line. If both
\fIpattern\fP and \fIrepl\fP are not specified or are empty (for example,
\fB"//"\fP ), the last \fBs\fP command shall be
repeated. If only \fIpattern\fP is not specified or is empty, the
last regular expression used in the editor shall be used as the
pattern. If only \fIrepl\fP is not specified or is empty, the pattern
shall be replaced by nothing. If the entire replacement
pattern is \fB'%'\fP , the last replacement pattern to an \fBs\fP
command shall be used.
.LP
Entering a <carriage-return> in \fIrepl\fP (which requires an escaping
backslash in \fIex\fP mode and an escaping
<control>-V in open or \fIvi\fP mode) shall split the line at that
point, creating a new
line in the edit buffer. The <carriage-return> shall be discarded.
.LP
If \fIoptions\fP includes the letter \fB'g'\fP ( \fBglobal\fP), all
non-overlapping instances of the pattern in the line
shall be replaced.
.LP
If \fIoptions\fP includes the letter \fB'c'\fP ( \fBconfirm\fP), then
before each substitution the line shall be written;
the written line shall reflect all previous substitutions. On the
following line, <space>s shall be written beneath the
characters from the line that are before the \fIpattern\fP to be replaced,
and \fB'^'\fP characters written beneath the
characters included in the \fIpattern\fP to be replaced. The \fIex\fP
utility shall then wait for a response from the user. An
affirmative response shall cause the substitution to be done, while
any other input shall not make the substitution. An affirmative
response shall consist of a line with the affirmative response (as
defined by the current locale) at the beginning of the line.
This line shall be subject to editing in the same way as the \fIex\fP
command line.
.LP
If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications
confirmed by the user shall be preserved in the edit
buffer after the interrupt.
.LP
If the remembered search direction is not set, the \fBs\fP command
shall set it to forward.
.LP
In the second Synopsis, the \fB&\fP command shall repeat the previous
substitution, as if the \fB&\fP command were
replaced by:
.sp
.RS
.nf

\fBs/\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB/
\fP
.fi
.RE
.LP
where \fIpattern\fP and \fIrepl\fP are as specified in the previous
\fBs\fP, \fB&\fP, or \fB~\fP command.
.LP
In the third Synopsis, the \fB~\fP command shall repeat the previous
substitution, as if the \fB'~'\fP were
replaced by:
.sp
.RS
.nf

\fBs/\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB/
\fP
.fi
.RE
.LP
where \fIpattern\fP shall be the last regular expression specified
to the editor, and \fIrepl\fP shall be from the previous
substitution (including \fB&\fP and \fB~\fP) command.
.LP
These commands shall be affected by the \fILC_MESSAGES\fP environment
variable.
.LP
\fICurrent line\fP: Set to the last line in which a substitution occurred,
or, unchanged if no substitution occurred.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Suspend
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBsu\fP\fB[\fP\fBspend\fP\fB][\fP\fB!\fP\fB]\fP\fBst\fP\fB[\fP\fBop\fP\fB][\fP\fB!\fP\fB]\fP
.fi
.RE
.sp
.LP
Allow control to return to the invoking process; \fIex\fP shall suspend
itself as if it had received the SIGTSTP signal. The
suspension shall occur only if job control is enabled in the invoking
shell (see the description of \fIset\fP \fB-m\fP).
.LP
These commands shall be affected by the \fBautowrite\fP and \fBwriteany\fP
edit options.
.LP
The current \fBsusp\fP character (see \fIstty\fP ) shall be equivalent
to the \fBsuspend\fP
command.
.SS Tag
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBta\fP\fB[\fP\fBg\fP\fB][\fP\fB!\fP\fB]\fP \fItagstring\fP
.fi
.RE
.sp
.LP
The results are unspecified if the format of a tags file is not as
specified by the \fIctags\fP utility (see \fIctags\fP ) description.
.LP
The \fBtag\fP command shall search for \fItagstring\fP in the tag
files referred to by the \fBtag\fP edit option, in the
order they are specified, until a reference to \fItagstring\fP is
found. Files shall be searched from beginning to end. If no
reference is found, it shall be an error and an error message to this
effect shall be written. If the reference is not found, or if
an error occurs while processing a file referred to in the \fBtag\fP
edit option, it shall be an error, and an error message shall
be written at the first occurrence of such an error.
.LP
Otherwise, if the tags file contained a pattern, the pattern shall
be treated as a regular expression used in the editor; for
example, for the purposes of the \fBs\fP command.
.LP
If the \fItagstring\fP is in a file with a different name than the
current pathname, set the current pathname to the name of
that file, and replace the contents of the edit buffer with the contents
of that file. In this case, if no \fB'!'\fP is appended
to the command name, and the edit buffer has been modified since the
last complete write, it shall be an error, unless the file is
successfully written as specified by the \fBautowrite\fP option.
.LP
This command shall be affected by the \fBautowrite\fP, \fBtag\fP,
\fBtaglength\fP, and \fBwriteany\fP edit options.
.LP
\fICurrent line\fP: If the tags file contained a line number, set
to that line number. If the line number is larger than the
last line in the edit buffer, an error message shall be written and
the current line shall be set as specified for the \fBedit\fP
command.
.LP
If the tags file contained a pattern, set to the first occurrence
of the pattern in the file. If no matching pattern is found,
an error message shall be written and the current line shall be set
as specified for the \fBedit\fP command.
.LP
\fICurrent column\fP: If the tags file contained a line-number reference
and that line-number was not larger than the last line
in the edit buffer, or if the tags file contained a pattern and that
pattern was found, set to non- <blank>. Otherwise, set
as specified for the \fBedit\fP command.
.SS Unabbreviate
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBuna\fP\fB[\fP\fBbbrev\fP\fB]\fP \fIlhs\fP
.fi
.RE
.sp
.LP
If \fIlhs\fP is not an entry in the current list of abbreviations
(see Abbreviate ), it shall be
an error. Otherwise, delete \fIlhs\fP from the list of abbreviations.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Undo
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBu\fP\fB[\fP\fBndo\fP\fB]\fP
.fi
.RE
.sp
.LP
Reverse the changes made by the last command that modified the contents
of the edit buffer, including \fBundo\fP. For this
purpose, the \fBglobal\fP, \fBv\fP, \fBopen\fP, and \fBvisual\fP commands,
and commands resulting from buffer executions and
mapped character expansions, are considered single commands.
.LP
If no action that can be undone preceded the \fBundo\fP command, it
shall be an error.
.LP
If the \fBundo\fP command restores lines that were marked, the mark
shall also be restored unless it was reset subsequent to
the deletion of the lines.
.LP
\fICurrent line\fP:
.IP " 1." 4
If lines are added or changed in the file, set to the first line added
or changed.
.LP
.IP " 2." 4
Set to the line before the first line deleted, if it exists.
.LP
.IP " 3." 4
Set to 1 if the edit buffer is not empty.
.LP
.IP " 4." 4
Set to zero.
.LP
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Unmap
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBunm\fP\fB[\fP\fBap\fP\fB][\fP\fB!\fP\fB]\fP \fIlhs\fP
.fi
.RE
.sp
.LP
If \fB'!'\fP is appended to the command name, and if \fIlhs\fP is
not an entry in the list of text input mode map
definitions, it shall be an error. Otherwise, delete \fIlhs\fP from
the list of text input mode map definitions.
.LP
If no \fB'!'\fP is appended to the command name, and if \fIlhs\fP
is not an entry in the list of command mode map
definitions, it shall be an error. Otherwise, delete \fIlhs\fP from
the list of command mode map definitions.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Version
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBve\fP\fB[\fP\fBrsion\fP\fB]\fP
.fi
.RE
.sp
.LP
Write a message containing version information for the editor. The
format of the message is unspecified.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Visual
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI1addr\fP\fB]\fP \fBvi\fP\fB[\fP\fBsual\fP\fB][\fP\fItype\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
If \fIex\fP is currently in open or visual mode, the Synopsis and
behavior of the visual command shall be the same as the
\fBedit\fP command, as specified by Edit .
.LP
Otherwise, this command need not be supported on block-mode terminals
or terminals with insufficient capabilities. If standard
input, standard output, or standard error are not terminal devices,
the results are unspecified.
.LP
If \fIcount\fP is specified, the value of the \fBwindow\fP edit option
shall be set to \fIcount\fP (as described in window ). If the \fB'^'\fP
type character was also specified, the \fBwindow\fP edit option shall
be set
before being used by the type character.
.LP
Enter visual mode. If \fItype\fP is not specified, it shall be as
if a \fItype\fP of \fB'+'\fP was specified. The
\fItype\fP shall cause the following effects:
.TP 7
\fB+\fP
Place the beginning of the specified line at the top of the display.
.TP 7
\fB-\fP
Place the end of the specified line at the bottom of the display.
.TP 7
\fB\&.\fP
Place the beginning of the specified line in the middle of the display.
.TP 7
\fB^\fP
If the specified line is less than or equal to the value of the \fBwindow\fP
edit option, set the line to 1; otherwise,
decrement the line by the value of the \fBwindow\fP edit option minus
1. Place the beginning of this line as close to the bottom
of the displayed lines as possible, while still displaying the value
of the \fBwindow\fP edit option number of lines.
.sp
.LP
\fICurrent line\fP: Set to the specified line.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Write
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBw\fP\fB[\fP\fBrite\fP\fB][\fP\fB!\fP\fB][\fP\fB>>\fP\fB][\fP\fIfile\fP\fB]
[\fP\fI2addr\fP\fB]\fP \fBw\fP\fB[\fP\fBrite\fP\fB][\fP\fB!\fP\fB][\fP\fIfile\fP\fB]
[\fP\fI2addr\fP\fB]\fP \fBwq\fP\fB[\fP\fB!\fP\fB][\fP\fB>>\fP\fB][\fP\fIfile\fP\fB]\fP
.fi
.RE
.sp
.LP
If no lines are specified, the lines shall default to the entire file.
.LP
The command \fBwq\fP shall be equivalent to a \fBwrite\fP command
followed by a \fBquit\fP command; \fBwq!\fP shall be
equivalent to \fBwrite!\fP followed by \fBquit\fP. In both cases,
if the \fBwrite\fP command fails, the \fBquit\fP shall not be
attempted.
.LP
If the command name is not followed by one or more <blank>s, or \fIfile\fP
is not preceded by a \fB'!'\fP character,
the \fBwrite\fP shall be to a file.
.IP " 1." 4
If the \fB>>\fP argument is specified, and the file already exists,
the lines shall be appended to the file instead of
replacing its contents. If the \fB>>\fP argument is specified, and
the file does not already exist, it is unspecified
whether the write shall proceed as if the \fB>>\fP argument had not
been specified or if the write shall fail.
.LP
.IP " 2." 4
If the \fBreadonly\fP edit option is set (see readonly ), the \fBwrite\fP
shall fail.
.LP
.IP " 3." 4
If \fIfile\fP is specified, and is not the current pathname, and the
file exists, the \fBwrite\fP shall fail.
.LP
.IP " 4." 4
If \fIfile\fP is not specified, the current pathname shall be used.
If there is no current pathname, the \fBwrite\fP command
shall fail.
.LP
.IP " 5." 4
If the current pathname is used, and the current pathname has been
changed by the \fBfile\fP or \fBread\fP commands, and the
file exists, the \fBwrite\fP shall fail. If the \fBwrite\fP is successful,
subsequent \fBwrite\fPs shall not fail for this
reason (unless the current pathname is changed again).
.LP
.IP " 6." 4
If the whole edit buffer is not being written, and the file to be
written exists, the \fBwrite\fP shall fail.
.LP
.LP
For rules 1., 2., 4., and 5., the \fBwrite\fP can be forced by appending
the character \fB'!'\fP to the command name.
.LP
For rules 2., 4., and 5., the \fBwrite\fP can be forced by setting
the \fBwriteany\fP edit option.
.LP
Additional, implementation-defined tests may cause the \fBwrite\fP
to fail.
.LP
If the edit buffer is empty, a file without any contents shall be
written.
.LP
An informational message shall be written noting the number of lines
and bytes written.
.LP
Otherwise, if the command is followed by one or more <blank>s, and
the file is preceded by \fB'!'\fP , the rest of the
line after the \fB'!'\fP shall have \fB'%'\fP , \fB'#'\fP , and \fB'!'\fP
characters expanded as described in Command Line Parsing in ex .
.LP
The \fIex\fP utility shall then pass two arguments to the program
named by the \fBshell\fP edit option; the first shall be
\fB-c\fP and the second shall be the expanded arguments to the \fBwrite\fP
command as a single argument. The specified lines
shall be written to the standard input of the command. The standard
error and standard output of the program, if any, shall be
written as described for the \fBprint\fP command. If the last character
in that output is not a <newline>, a <newline>
shall be written at the end of the output.
.LP
The special meaning of the \fB'!'\fP following the \fBwrite\fP command
can be overridden by escaping it with a backslash
character.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Write and Exit
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBx\fP\fB[\fP\fBit\fP\fB][\fP\fB!\fP\fB][\fP\fIfile\fP\fB]\fP
.fi
.RE
.sp
.LP
If the edit buffer has not been modified since the last complete \fBwrite\fP,
\fBxit\fP shall be equivalent to the \fBquit\fP
command, or if a \fB'!'\fP is appended to the command name, to \fBquit!\fP.
.LP
Otherwise, \fBxit\fP shall be equivalent to the \fBwq\fP command,
or if a \fB'!'\fP is appended to the command name, to
\fBwq!\fP.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Yank
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fBya\fP\fB[\fP\fBnk\fP\fB][\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP
.fi
.RE
.sp
.LP
Copy the specified lines to the specified buffer (by default, the
unnamed buffer), which shall become a line-mode buffer.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Adjust Window
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI1addr\fP\fB]\fP \fBz\fP\fB[\fP\fB!\fP\fB][\fP\fItype\fP \fB...\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
If no line is specified, the current line shall be the default; if
\fItype\fP is omitted as well, the current line value shall
first be incremented by 1. If incrementing the current line would
cause it to be greater than the last line in the edit buffer, it
shall be an error.
.LP
If there are <blank>s between the \fItype\fP argument and the preceding
\fBz\fP command name or optional \fB'!'\fP
character, it shall be an error.
.LP
If \fIcount\fP is specified, the value of the \fBwindow\fP edit option
shall be set to \fIcount\fP (as described in window ). If \fIcount\fP
is omitted, it shall default to 2 times the value of the \fBscroll\fP
edit
option, or if \fB!\fP was specified, the number of lines in the display
minus 1.
.LP
If \fItype\fP is omitted, then \fIcount\fP lines starting with the
specified line shall be written. Otherwise, \fIcount\fP
lines starting with the line specified by the \fItype\fP argument
shall be written.
.LP
The \fItype\fP argument shall change the lines to be written. The
possible values of \fItype\fP are as follows:
.TP 7
\fB-\fP
The specified line shall be decremented by the following value: 
.sp
.RS
.nf

\fB(((number of "-" characters) x\fP \fIcount\fP\fB) -1)
\fP
.fi
.RE
.LP
If the calculation would result in a number less than 1, it shall
be an error. Write lines from the edit buffer, starting at the
new value of line, until \fIcount\fP lines or the last line in the
edit buffer has been written.
.TP 7
\fB+\fP
The specified line shall be incremented by the following value: 
.sp
.RS
.nf

\fB(((number of "+" characters) -1) x\fP \fIcount\fP\fB) +1
\fP
.fi
.RE
.LP
If the calculation would result in a number greater than the last
line in the edit buffer, it shall be an error. Write lines
from the edit buffer, starting at the new value of line, until \fIcount\fP
lines or the last line in the edit buffer has been
written.
.TP 7
\fB=\fP,\fB.\fP
If more than a single \fB'.'\fP or \fB'='\fP is specified, it shall
be an error. The following steps shall be taken: 
.RS
.IP " 1." 4
If \fIcount\fP is zero, nothing shall be written.
.LP
.IP " 2." 4
Write as many of the \fIN\fP lines before the current line in the
edit buffer as exist. If \fIcount\fP or \fB'!'\fP was
specified, \fIN\fP shall be:
.sp
.RS
.nf

\fB(\fP\fIcount\fP \fB-1) /2
\fP
.fi
.RE
.LP
Otherwise, \fIN\fP shall be:
.sp
.RS
.nf

\fB(\fP\fIcount\fP \fB-3) /2
\fP
.fi
.RE
.LP
If \fIN\fP is a number less than 3, no lines shall be written.
.LP
.IP " 3." 4
If \fB'='\fP was specified as the type character, write a line consisting
of the smaller of the number of columns in the
display divided by two, or 40 \fB'-'\fP characters.
.LP
.IP " 4." 4
Write the current line.
.LP
.IP " 5." 4
Repeat step 3.
.LP
.IP " 6." 4
Write as many of the \fIN\fP lines after the current line in the edit
buffer as exist. \fIN\fP shall be defined as in step 2.
If \fIN\fP is a number less than 3, no lines shall be written. If
\fIcount\fP is less than 3, no lines shall be written.
.LP
.RE
.TP 7
\fB^\fP
The specified line shall be decremented by the following value: 
.sp
.RS
.nf

\fB(((number of "^" characters) +1) x\fP \fIcount\fP\fB) -1
\fP
.fi
.RE
.LP
If the calculation would result in a number less than 1, it shall
be an error. Write lines from the edit buffer, starting at the
new value of line, until \fIcount\fP lines or the last line in the
edit buffer has been written.
.sp
.LP
\fICurrent line\fP: Set to the last line written, unless the type
is \fB=\fP, in which case, set to the specified line.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Escape
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB!\fP \fIcommand
\fP\fB[\fP\fIaddr\fP\fB]\fP\fB!\fP \fIcommand\fP
.fi
.RE
.sp
.LP
The contents of the line after the \fB'!'\fP shall have \fB'%'\fP
, \fB'#'\fP , and \fB'!'\fP characters expanded as
described in Command Line Parsing in ex . If the expansion causes
the text of the line to change, it
shall be redisplayed, preceded by a single \fB'!'\fP character.
.LP
The \fIex\fP utility shall execute the program named by the \fBshell\fP
edit option. It shall pass two arguments to the
program; the first shall be \fB-c\fP, and the second shall be the
expanded arguments to the \fB!\fP command as a single
argument.
.LP
If no lines are specified, the standard input, standard output, and
standard error of the program shall be set to the standard
input, standard output, and standard error of the \fIex\fP program
when it was invoked. In addition, a warning message shall be
written if the edit buffer has been modified since the last complete
write, and the \fBwarn\fP edit option is set.
.LP
If lines are specified, they shall be passed to the program as standard
input, and the standard output and standard error of the
program shall replace those lines in the edit buffer. Each line in
the program output (as delimited by <newline>s or the end
of the output if it is not immediately preceded by a <newline>), shall
be a separate line in the edit buffer. Any occurrences
of <carriage-return> and <newline> pairs in the output shall be treated
as single <newline>s. The specified lines
shall be copied into the unnamed buffer before they are replaced,
and the unnamed buffer shall become a line-mode buffer.
.LP
If in \fIex\fP mode, a single \fB'!'\fP character shall be written
when the program completes.
.LP
This command shall be affected by the \fBshell\fP and \fBwarn\fP edit
options. If no lines are specified, this command shall
be affected by the \fBautowrite\fP and \fBwriteany\fP edit options.
If lines are specified, this command shall be affected by the
\fBautoprint\fP edit option.
.LP
\fICurrent line\fP:
.IP " 1." 4
If no lines are specified, unchanged.
.LP
.IP " 2." 4
Otherwise, set to the last line read in, if any lines are read in.
.LP
.IP " 3." 4
Otherwise, set to the line before the first line of the lines specified,
if that line exists.
.LP
.IP " 4." 4
Otherwise, set to the first line of the edit buffer if the edit buffer
is not empty.
.LP
.IP " 5." 4
Otherwise, set to zero.
.LP
.LP
\fICurrent column\fP: If no lines are specified, unchanged. Otherwise,
set to non- <blank>.
.SS Shift Left
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fB<\fP\fB[\fP\fB< ...\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
Shift the specified lines to the start of the line; the number of
column positions to be shifted shall be the number of command
characters times the value of the \fBshiftwidth\fP edit option. Only
leading <blank>s shall be deleted or changed into other
<blank>s in shifting; other characters shall not be affected.
.LP
Lines to be shifted shall be copied into the unnamed buffer, which
shall become a line-mode buffer.
.LP
This command shall be affected by the \fBautoprint\fP edit option.
.LP
\fICurrent line\fP: Set to the last line in the lines specified.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Shift Right
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fB>\fP\fB[\fP\fB> ...\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
Shift the specified lines away from the start of the line; the number
of column positions to be shifted shall be the number of
command characters times the value of the \fBshiftwidth\fP edit option.
The shift shall be accomplished by adding <blank>s
as a prefix to the line or changing leading <blank>s into other <blank>s.
Empty lines shall not be changed.
.LP
Lines to be shifted shall be copied into the unnamed buffer, which
shall become a line-mode buffer.
.LP
This command shall be affected by the \fBautoprint\fP edit option.
.LP
\fICurrent line\fP: Set to the last line in the lines specified.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS <control>-D
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB<control>-D
\fP
.fi
.RE
.sp
.LP
Write the next \fIn\fP lines, where \fIn\fP is the minimum of the
values of the \fBscroll\fP edit option and the number of
lines after the current line in the edit buffer. If the current line
is the last line of the edit buffer it shall be an error.
.LP
\fICurrent line\fP: Set to the last line written.
.LP
\fICurrent column\fP: Set to non- <blank>.
.SS Write Line Number
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI1addr\fP\fB]\fP \fB=\fP \fB[\fP\fIflags\fP\fB]\fP
.fi
.RE
.sp
.LP
If \fIline\fP is not specified, it shall default to the last line
in the edit buffer. Write the line number of the specified
line.
.LP
\fICurrent line\fP: Unchanged.
.LP
\fICurrent column\fP: Unchanged.
.SS Execute
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fI2addr\fP\fB]\fP \fB@\fP \fIbuffer\fP\fB[\fP\fI2addr\fP\fB]\fP \fB*\fP \fIbuffer\fP
.fi
.RE
.sp
.LP
If no buffer is specified or is specified as \fB'@'\fP or \fB'*'\fP
, the last buffer executed shall be used. If no
previous buffer has been executed, it shall be an error.
.LP
For each line specified by the addresses, set the current line ( \fB'.'\fP
) to the specified line, and execute the contents
of the named \fIbuffer\fP (as they were at the time the \fB@\fP command
was executed) as \fIex\fP commands. For each line of a
line-mode buffer, and all but the last line of a character-mode buffer,
the \fIex\fP command parser shall behave as if the line
was terminated by a <newline>.
.LP
If an error occurs during this process, or a line specified by the
addresses does not exist when the current line would be set
to it, or more than a single line was specified by the addresses,
and the contents of the edit buffer are replaced (for example, by
the \fIex\fP \fB:edit\fP command) an error message shall be written,
and no more commands resulting from the execution of this
command shall be processed.
.LP
\fICurrent line\fP: As specified for the individual \fIex\fP commands.
.LP
\fICurrent column\fP: As specified for the individual \fIex\fP commands.
.SS Regular Expressions in ex
.LP
The \fIex\fP utility shall support regular expressions that are a
superset of the basic regular expressions described in the
Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 9.3, Basic
Regular Expressions. A null regular expression ( \fB"//"\fP ) shall
be equivalent to the last regular expression
encountered.
.LP
Regular expressions can be used in addresses to specify lines and,
in some commands (for example, the \fBsubstitute\fP
command), to specify portions of a line to be substituted.
.LP
The following constructs can be used to enhance the basic regular
expressions:
.TP 7
\fB\\<\fP
Match the beginning of a \fIword\fP. (See the definition of \fIword\fP
at the beginning of Command
Descriptions in ex .)
.TP 7
\fB\\>\fP
Match the end of a \fIword\fP.
.TP 7
\fB~\fP
Match the replacement part of the last \fBsubstitute\fP command. The
tilde ( \fB'~'\fP ) character can be escaped in a
regular expression to become a normal character with no special meaning.
The backslash shall be discarded.
.sp
.LP
When the editor option \fBmagic\fP is not set, the only characters
with special meanings shall be \fB'^'\fP at the beginning
of a pattern, \fB'$'\fP at the end of a pattern, and \fB'\\'\fP .
The characters \fB'.'\fP , \fB'*'\fP , \fB'['\fP ,
and \fB'~'\fP shall be treated as ordinary characters unless preceded
by a \fB'\\'\fP ; when preceded by a \fB'\\'\fP
they shall regain their special meaning, or in the case of backslash,
be handled as a single backslash. Backslashes used to escape
other characters shall be discarded.
.SS Replacement Strings in ex
.LP
The character \fB'&'\fP ( \fB'\\&'\fP if the editor option \fBmagic\fP
is not set) in the replacement string shall
stand for the text matched by the pattern to be replaced. The character
\fB'~'\fP ( \fB'\\~'\fP if \fBmagic\fP is
not set) shall be replaced by the replacement part of the previous
\fBsubstitute\fP command. The sequence \fB'\\n'\fP , where
\fIn\fP is an integer, shall be replaced by the text matched by the
pattern enclosed in the \fIn\fPth set of parentheses
\fB'\\('\fP and \fB'\\)'\fP .
.LP
The strings \fB'\\l'\fP , \fB'\\u'\fP , \fB'\\L'\fP , and \fB'\\U'\fP
can be used to modify the case of elements in the
replacement string (using the \fB'\\&'\fP or \fB"\\"\fP digit) notation.
The string \fB'\\l'\fP ( \fB'\\u'\fP ) shall
cause the character that follows to be converted to lowercase (uppercase).
The string \fB'\\L'\fP ( \fB'\\U'\fP ) shall cause
all characters subsequent to it to be converted to lowercase (uppercase)
as they are inserted by the substitution until the string
\fB'\\e'\fP or \fB'\\E'\fP , or the end of the replacement string,
is encountered.
.LP
Otherwise, any character following a backslash shall be treated as
that literal character, and the escaping backslash shall be
discarded.
.LP
An example of case conversion with the \fBs\fP command is as follows:
.sp
.RS
.nf

\fB:\fP\fBp
\fP\fBThe cat sat on the mat.
:\fP\fBs/\\<.at\\>/\\u&/gp
\fP\fBThe Cat Sat on the Mat.
:\fP\fBs/S\\(.*\\)M/S\\U\\1\\eM/p
\fP\fBThe Cat SAT ON THE Mat.\fP
.fi
.RE
.SS Edit Options in ex
.LP
The \fIex\fP utility has a number of options that modify its behavior.
These options have default settings, which can be
changed using the \fBset\fP command.
.LP
Options are Boolean unless otherwise specified.
.SS autoindent, ai
.LP
[Default \fIunset\fP]
.LP
If \fBautoindent\fP is set, each line in input mode shall be indented
(using first as many <tab>s as possible, as
determined by the editor option \fBtabstop\fP, and then using <space>s)
to align with another line, as follows:
.IP " 1." 4
If in open or visual mode and the text input is part of a line-oriented
command (see the EXTENDED DESCRIPTION in \fIvi\fP ), align to the
first column.
.LP
.IP " 2." 4
Otherwise, if in open or visual mode, indentation for each line shall
be set as follows:
.RS
.IP " a." 4
If a line was previously inserted as part of this command, it shall
be set to the indentation of the last inserted line by
default, or as otherwise specified for the <control>-D character in
\fIInput Mode Commands
in vi\fP .
.LP
.IP " b." 4
Otherwise, it shall be set to the indentation of the previous current
line, if any; otherwise, to the first column.
.LP
.RE
.LP
.IP " 3." 4
For the \fIex\fP \fBa\fP, \fBi\fP, and \fBc\fP commands, indentation
for each line shall be set as follows:
.RS
.IP " a." 4
If a line was previously inserted as part of this command, it shall
be set to the indentation of the last inserted line by
default, or as otherwise specified for the \fIeof\fP character in
Scroll .
.LP
.IP " b." 4
Otherwise, if the command is the \fIex\fP \fBa\fP command, it shall
be set to the line appended after, if any; otherwise to
the first column.
.LP
.IP " c." 4
Otherwise, if the command is the \fIex\fP \fBi\fP command, it shall
be set to the line inserted before, if any; otherwise to
the first column.
.LP
.IP " d." 4
Otherwise, if the command is the \fIex\fP \fBc\fP command, it shall
be set to the indentation of the line replaced.
.LP
.RE
.LP
.SS autoprint, ap
.LP
[Default \fIset\fP]
.LP
If \fBautoprint\fP is set, the current line shall be written after
each \fIex\fP command that modifies the contents of the
current edit buffer, and after each \fBtag\fP command for which the
tag search pattern was found or tag line number was valid,
unless:
.IP " 1." 4
The command was executed while in open or visual mode.
.LP
.IP " 2." 4
The command was executed as part of a \fBglobal\fP or \fBv\fP command
or \fB@\fP buffer execution.
.LP
.IP " 3." 4
The command was the form of the \fBread\fP command that reads a file
into the edit buffer.
.LP
.IP " 4." 4
The command was the \fBappend\fP, \fBchange\fP, or \fBinsert\fP command.
.LP
.IP " 5." 4
The command was not terminated by a <newline>.
.LP
.IP " 6." 4
The current line shall be written by a flag specified to the command;
for example, \fBdelete #\fP shall write the current line
as specified for the flag modifier to the \fBdelete\fP command, and
not as specified by the \fBautoprint\fP edit option.
.LP
.SS autowrite, aw
.LP
[Default \fIunset\fP]
.LP
If \fBautowrite\fP is set, and the edit buffer has been modified since
it was last completely written to any file, the contents
of the edit buffer shall be written as if the \fIex\fP \fBwrite\fP
command had been specified without arguments, before each
command affected by the \fBautowrite\fP edit option is executed. Appending
the character \fB'!'\fP to the command name of any
of the \fIex\fP commands except \fB'!'\fP shall prevent the write.
If the write fails, it shall be an error and the command
shall not be executed.
.SS beautify, bf
.LP
[Default \fIunset\fP]
.LP
If \fBbeautify\fP is set, all non-printable characters, other than
<tab>s, <newline>s, and <form-feed>s,
shall be discarded from text read in from files. 
.SS directory, dir
.LP
[Default \fIimplementation-defined\fP]
.LP
The value of this option specifies the directory in which the editor
buffer is to be placed. If this directory is not writable
by the user, the editor shall quit.
.SS edcompatible, ed
.LP
[Default \fIunset\fP]
.LP
Causes the presence of \fBg\fP and \fBc\fP suffixes on substitute
commands to be remembered, and toggled by repeating the
suffixes.
.SS errorbells, eb
.LP
[Default \fIunset\fP]
.LP
If the editor is in \fIex\fP mode, and the terminal does not support
a standout mode (such as inverse video), and
\fBerrorbells\fP is set, error messages shall be preceded by alerting
the terminal.
.SS exrc
.LP
[Default \fIunset\fP]
.LP
If \fBexrc\fP is set, \fIex\fP shall access any \fB.exrc\fP file in
the current directory, as described in Initialization in ex and vi
\&. If \fBexrc\fP is not set, \fIex\fP shall ignore any \fB.exrc\fP
file in the
current directory during initialization, unless the current directory
is that named by the \fIHOME\fP environment variable.
.SS ignorecase, ic
.LP
[Default \fIunset\fP]
.LP
If \fBignorecase\fP is set, characters that have uppercase and lowercase
representations shall have those representations
considered as equivalent for purposes of regular expression comparison.
.LP
The \fBignorecase\fP edit option shall affect all remembered regular
expressions; for example, unsetting the \fBignorecase\fP
edit option shall cause a subsequent \fIvi\fP \fBn\fP command to search
for the last basic
regular expression in a case-sensitive fashion.
.SS list
.LP
[Default \fIunset\fP]
.LP
If \fBlist\fP is set, edit buffer lines written while in \fIex\fP
command mode shall be written as specified for the
\fBprint\fP command with the \fBl\fP flag specified. In open or visual
mode, each edit buffer line shall be displayed as
specified for the \fIex\fP \fBprint\fP command with the \fBl\fP flag
specified. In open or visual text input mode, when the
cursor does not rest on any character in the line, it shall rest on
the \fB'$'\fP marking the end of the line.
.SS magic
.LP
[Default \fIset\fP]
.LP
If \fBmagic\fP is set, modify the interpretation of characters in
regular expressions and substitution replacement strings (see
Regular Expressions in ex and Replacement Strings in ex ).
.SS mesg
.LP
[Default \fIset\fP]
.LP
If \fBmesg\fP is set, the permission for others to use the \fBwrite\fP
or \fBtalk\fP commands to write to the terminal shall
be turned on while in open or visual mode. The shell-level command
\fImesg\fP \fBn\fP shall
take precedence over any setting of the \fIex\fP \fBmesg\fP option;
that is, if \fBmesg y\fP was issued before the editor
started (or in a shell escape), such as:
.sp
.RS
.nf

\fB:!mesg y
\fP
.fi
.RE
.LP
the \fBmesg\fP option in \fIex\fP shall suppress incoming messages,
but the \fBmesg\fP option shall not enable incoming
messages if \fBmesg n\fP was issued.
.SS number, nu
.LP
[Default \fIunset\fP]
.LP
If \fBnumber\fP is set, edit buffer lines written while in \fIex\fP
command mode shall be written with line numbers, in the
format specified by the \fBprint\fP command with the \fB#\fP flag
specified. In \fIex\fP text input mode, each line shall be
preceded by the line number it will have in the file.
.LP
In open or visual mode, each edit buffer line shall be displayed with
a preceding line number, in the format specified by the
\fIex\fP \fBprint\fP command with the \fB#\fP flag specified. This
line number shall not be considered part of the line for the
purposes of evaluating the current column; that is, column position
1 shall be the first column position after the format specified
by the \fBprint\fP command.
.SS paragraphs, para
.LP
[Default in the POSIX locale \fBIPLPPPQPP LIpplpipbp\fP]
.LP
The \fBparagraphs\fP edit option shall define additional paragraph
boundaries for the open and visual mode commands. The
\fBparagraphs\fP edit option can be set to a character string consisting
of zero or more character pairs. It shall be an error to
set it to an odd number of characters.
.SS prompt
.LP
[Default \fIset\fP]
.LP
If \fBprompt\fP is set, \fIex\fP command mode input shall be prompted
for with a colon ( \fB':'\fP ); when unset, no prompt
shall be written.
.SS readonly
.LP
[Default \fIsee text\fP]
.LP
If the \fBreadonly\fP edit option is set, read-only mode shall be
enabled (see Write ). The
\fBreadonly\fP edit option shall be initialized to set if either of
the following conditions are true:
.IP " *" 3
The command-line option -R was specified.
.LP
.IP " *" 3
Performing actions equivalent to the \fIaccess\fP() function called
with the following
arguments indicates that the file lacks write permission:
.RS
.IP " 1." 4
The current pathname is used as the \fIpath\fP argument.
.LP
.IP " 2." 4
The constant \fBW_OK\fP is used as the \fIamode\fP argument.
.LP
.RE
.LP
.LP
The \fBreadonly\fP edit option may be initialized to set for other,
implementation-defined reasons. The \fBreadonly\fP edit
option shall not be initialized to unset based on any special privileges
of the user or process. The \fBreadonly\fP edit option
shall be reinitialized each time that the contents of the edit buffer
are replaced (for example, by an \fBedit\fP or \fBnext\fP
command) unless the user has explicitly set it, in which case it shall
remain set until the user explicitly unsets it. Once unset,
it shall again be reinitialized each time that the contents of the
edit buffer are replaced.
.SS redraw
.LP
[Default \fIunset\fP]
.LP
The editor simulates an intelligent terminal on a dumb terminal. (Since
this is likely to require a large amount of output to
the terminal, it is useful only at high transmission speeds.)
.SS remap
.LP
[Default \fIset\fP]
.LP
If \fBremap\fP is set, map translation shall allow for maps defined
in terms of other maps; translation shall continue until a
final product is obtained. If unset, only a one-step translation shall
be done.
.SS report
.LP
[Default 5]
.LP
The value of this \fBreport\fP edit option specifies what number of
lines being added, copied, deleted, or modified in the edit
buffer will cause an informational message to be written to the user.
The following conditions shall cause an informational
message. The message shall contain the number of lines added, copied,
deleted, or modified, but is otherwise unspecified.
.IP " *" 3
An \fIex\fP or \fIvi\fP editor command, other than \fBopen\fP, \fBundo\fP,
or
\fBvisual\fP, that modifies at least the value of the \fBreport\fP
edit option number of lines, and which is not part of an
\fIex\fP \fBglobal\fP or \fBv\fP command, or \fIex\fP or \fIvi\fP
buffer execution, shall
cause an informational message to be written.
.LP
.IP " *" 3
An \fIex\fP \fByank\fP or \fIvi\fP \fBy\fP or \fBY\fP command, that
copies at least the
value of the \fBreport\fP edit option plus 1 number of lines, and
which is not part of an \fIex\fP \fBglobal\fP or \fBv\fP
command, or \fIex\fP or \fIvi\fP buffer execution, shall cause an
informational message to be
written.
.LP
.IP " *" 3
An \fIex\fP \fBglobal\fP, \fBv\fP, \fBopen\fP, \fBundo\fP, or \fBvisual\fP
command or \fIex\fP or \fIvi\fP buffer execution, that adds or deletes
a total of at least the value of the \fBreport\fP edit
option number of lines, and which is not part of an \fIex\fP \fBglobal\fP
or \fBv\fP command, or \fIex\fP or \fIvi\fP buffer execution, shall
cause an informational message to be written. (For example, if 3 lines
were added and 8 lines deleted during an \fIex\fP \fBvisual\fP command,
5 would be the number compared against the \fBreport\fP
edit option after the command completed.)
.LP
.SS scroll, scr
.LP
[Default (number of lines in the display -1)/2]
.LP
The value of the \fBscroll\fP edit option shall determine the number
of lines scrolled by the \fIex\fP <control>-D and
\fBz\fP commands. For the \fIvi\fP <control>-D and <control>-U commands,
it shall
be the initial number of lines to scroll when no previous <control>-D
or <control>-U command has been executed.
.SS sections
.LP
[Default in the POSIX locale \fBNHSHH HUnhsh\fP]
.LP
The \fBsections\fP edit option shall define additional section boundaries
for the open and visual mode commands. The
\fBsections\fP edit option can be set to a character string consisting
of zero or more character pairs; it shall be an error to
set it to an odd number of characters.
.SS shell, sh
.LP
[Default from the environment variable \fISHELL ]\fP
.LP
The value of this option shall be a string. The default shall be taken
from the \fISHELL\fP environment variable. If the
\fISHELL\fP environment variable is null or empty, the \fIsh\fP (see
\fIsh\fP ) utility shall be the default.
.SS shiftwidth, sw
.LP
[Default 8]
.LP
The value of this option shall give the width in columns of an indentation
level used during autoindentation and by the shift
commands ( \fB<\fP and \fB>\fP).
.SS showmatch, sm
.LP
[Default \fIunset\fP]
.LP
The functionality described for the \fBshowmatch\fP edit option need
not be supported on block-mode terminals or terminals with
insufficient capabilities.
.LP
If \fBshowmatch\fP is set, in open or visual mode, when a \fB')'\fP
or \fB'}'\fP is typed, if the matching \fB'('\fP
or \fB'{'\fP is currently visible on the display, the matching \fB'('\fP
or \fB'{'\fP shall be flagged moving the cursor
to its location for an unspecified amount of time.
.SS showmode
.LP
[Default \fIunset\fP]
.LP
If \fBshowmode\fP is set, in open or visual mode, the current mode
that the editor is in shall be displayed on the last line of
the display. Command mode and text input mode shall be differentiated;
other unspecified modes and implementation-defined
information may be displayed.
.SS slowopen
.LP
[Default \fIunset\fP]
.LP
If \fBslowopen\fP is set during open and visual text input modes,
the editor shall not update portions of the display other
than those display line columns that display the characters entered
by the user (see \fIInput
Mode Commands in vi\fP ).
.SS tabstop, ts
.LP
[Default 8]
.LP
The value of this edit option shall specify the column boundary used
by a <tab> in the display (see autoprint, ap and \fIInput Mode Commands
in vi\fP ).
.SS taglength, tl
.LP
[Default zero]
.LP
The value of this edit option shall specify the maximum number of
characters that are considered significant in the
user-specified tag name and in the tag name from the tags file. If
the value is zero, all characters in both tag names shall be
significant.
.SS tags
.LP
[Default \fIsee text\fP]
.LP
The value of this edit option shall be a string of <blank>-delimited
pathnames of files used by the \fBtag\fP command.
The default value is unspecified.
.SS term
.LP
[Default from the environment variable \fITERM ]\fP
.LP
The value of this edit option shall be a string. The default shall
be taken from the \fITERM\fP variable in the environment. If
the \fITERM\fP environment variable is empty or null, the default
is unspecified. The editor shall use the value of this edit
option to determine the type of the display device.
.LP
The results are unspecified if the user changes the value of the term
edit option after editor initialization.
.SS terse
.LP
[Default \fIunset\fP]
.LP
If \fBterse\fP is set, error messages may be less verbose. However,
except for this caveat, error messages are unspecified.
Furthermore, not all error messages need change for different settings
of this option.
.SS warn
.LP
[Default \fIset\fP]
.LP
If \fBwarn\fP is set, and the contents of the edit buffer have been
modified since they were last completely written, the
editor shall write a warning message before certain \fB!\fP commands
(see Escape ).
.SS window
.LP
[Default \fIsee text\fP]
.LP
A value used in open and visual mode, by the <control>-B and <control>-F
commands, and, in visual mode, to specify
the number of lines displayed when the screen is repainted.
.LP
If the \fB-w\fP command-line option is not specified, the default
value shall be set to the value of the \fILINES\fP
environment variable. If the \fILINES\fP environment variable is empty
or null, the default shall be the number of lines in the
display minus 1.
.LP
Setting the \fBwindow\fP edit option to zero or to a value greater
than the number of lines in the display minus 1 (either
explicitly or based on the \fB-w\fP option or the \fILINES\fP environment
variable) shall cause the \fBwindow\fP edit option to
be set to the number of lines in the display minus 1.
.LP
The baud rate of the terminal line may change the default in an implementation-defined
manner.
.SS wrapmargin, wm
.LP
[Default 0]
.LP
If the value of this edit option is zero, it shall have no effect.
.LP
If not in the POSIX locale, the effect of this edit option is implementation-defined.
.LP
Otherwise, it shall specify a number of columns from the ending margin
of the terminal.
.LP
During open and visual text input modes, for each character for which
any part of the character is displayed in a column that is
less than \fBwrapmargin\fP columns from the ending margin of the display
line, the editor shall behave as follows:
.IP " 1." 4
If the character triggering this event is a <blank>, it, and all immediately
preceding <blank>s on the current line
entered during the execution of the current text input command, shall
be discarded, and the editor shall behave as if the user had
entered a single <newline> instead. In addition, if the next user-entered
character is a <space>, it shall be discarded
as well.
.LP
.IP " 2." 4
Otherwise, if there are one or more <blank>s on the current line immediately
preceding the last group of inserted non-
<blank>s which was entered during the execution of the current text
input command, the <blank>s shall be replaced as if
the user had entered a single <newline> instead.
.LP
.LP
If the \fBautoindent\fP edit option is set, and the events described
in 1. or 2. are performed, any <blank>s at or after
the cursor in the current line shall be discarded.
.LP
The ending margin shall be determined by the system or overridden
by the user, as described for \fICOLUMNS\fP in the
ENVIRONMENT VARIABLES section and the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Chapter 8, Environment Variables.
.SS wrapscan, ws
.LP
[Default \fIset\fP]
.LP
If \fBwrapscan\fP is set, searches (the \fIex\fP \fB/\fP or \fB?\fP
addresses, or open and visual mode \fB/\fP, \fB?\fP,
\fBN\fP, and \fBn\fP commands) shall wrap around the beginning or
end of the edit buffer; when unset, searches shall stop at the
beginning or end of the edit buffer.
.SS writeany, wa
.LP
[Default \fIunset\fP]
.LP
If \fBwriteany\fP is set, some of the checks performed when executing
the \fIex\fP \fBwrite\fP commands shall be inhibited,
as described in editor option \fBautowrite\fP.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
When any error is encountered and the standard input is not a terminal
device file, \fIex\fP shall not write the file or return
to command or text input mode, and shall terminate with a non-zero
exit status.
.LP
Otherwise, when an unrecoverable error is encountered, it shall be
equivalent to a SIGHUP asynchronous event.
.LP
Otherwise, when an error is encountered, the editor shall behave as
specified in Command Line Parsing
in ex .
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
If a SIGSEGV signal is received while \fIex\fP is saving a file, the
file might not be successfully saved.
.LP
The \fBnext\fP command can accept more than one file, so usage such
as:
.sp
.RS
.nf

\fBnext `ls [abc]*`
\fP
.fi
.RE
.LP
is valid; it would not be valid for the \fBedit\fP or \fBread\fP commands,
for example, because they expect only one file and
unspecified results occur.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
The \fIex\fP/ \fIvi\fP specification is based on the historical practice
found in the 4 BSD
and System V implementations of \fIex\fP and \fIvi\fP. A freely redistributable
implementation
of \fIex\fP/ \fIvi\fP, which is tracking IEEE\ Std\ 1003.1-2001 fairly
closely, and
demonstrates the intended changes between historical implementations
and IEEE\ Std\ 1003.1-2001, may be obtained by
anonymous FTP from:
.sp
.RS
.nf

\fBftp://ftp.rdg.opengroup.org/pub/mirrors/nvi
\fP
.fi
.RE
.LP
A \fIrestricted editor\fP (both the historical \fIred\fP utility and
modifications to \fIex\fP) were considered and rejected
for inclusion. Neither option provided the level of security that
users might expect.
.LP
It is recognized that \fIex\fP visual mode and related features would
be difficult, if not impossible, to implement
satisfactorily on a block-mode terminal, or a terminal without any
form of cursor addressing; thus, it is not a mandatory
requirement that such features should work on all terminals. It is
the intention, however, that an \fIex\fP implementation should
provide the full set of capabilities on all terminals capable of supporting
them.
.SS Options
.LP
The \fB-c\fP replacement for \fB+\fP \fIcommand\fP was inspired by
the \fB-e\fP option of \fIsed\fP. Historically, all such commands
(see \fBedit\fP and \fBnext\fP as well) were executed
from the last line of the edit buffer. This meant, for example, that
\fB"+/pattern"\fP would fail unless the \fBwrapscan\fP
option was set. IEEE\ Std\ 1003.1-2001 requires conformance to historical
practice. Historically, some implementations
restricted the \fIex\fP commands that could be listed as part of the
command line arguments. For consistency,
IEEE\ Std\ 1003.1-2001 does not permit these restrictions.
.LP
In historical implementations of the editor, the \fB-R\fP option (and
the \fBreadonly\fP edit option) only prevented
overwriting of files; appending to files was still permitted, mapping
loosely into the \fIcsh\fP \fBnoclobber\fP variable. Some
implementations, however, have not followed this semantic, and \fBreadonly\fP
does not permit appending either.
IEEE\ Std\ 1003.1-2001 follows the latter practice, believing that
it is a more obvious and intuitive meaning of
\fBreadonly\fP.
.LP
The \fB-s\fP option suppresses all interactive user feedback and is
useful for editing scripts in batch jobs. The list of
specific effects is historical practice. The terminal type "incapable
of supporting open and visual modes" has historically been
named "dumb".
.LP
The \fB-t\fP option was required because the \fIctags\fP utility appears
in
IEEE\ Std\ 1003.1-2001 and the option is available in all historical
implementations of \fIex\fP.
.LP
Historically, the \fIex\fP and \fIvi\fP utilities accepted a \fB-x\fP
option, which did
encryption based on the algorithm found in the historical \fIcrypt\fP
utility. The \fB-x\fP option for encryption, and the
associated \fIcrypt\fP utility, were omitted because the algorithm
used was not specifiable and the export control laws of some
nations make it difficult to export cryptographic technology. In addition,
it did not historically provide the level of security
that users might expect.
.SS Standard Input
.LP
An end-of-file condition is not equivalent to an end-of-file character.
A common end-of-file character, <control>-D, is
historically an \fIex\fP command.
.LP
There was no maximum line length in historical implementations of
\fIex\fP. Specifically, as it was parsed in chunks, the
addresses had a different maximum length than the filenames. Further,
the maximum line buffer size was declared as BUFSIZ, which
was different lengths on different systems. This version selected
the value of {LINE_MAX} to impose a reasonable restriction on
portable usage of \fIex\fP and to aid test suite writers in their
development of realistic tests that exercise this limit.
.SS Input Files
.LP
It was an explicit decision by the standard developers that a <newline>
be added to any file lacking one. It was believed
that this feature of \fIex\fP and \fIvi\fP was relied on by users
in order to make text files
lacking a trailing <newline> more portable. It is recognized that
this will require a user-specified option or extension for
implementations that permit \fIex\fP and \fIvi\fP to edit files of
type other than text if
such files are not otherwise identified by the system. It was agreed
that the ability to edit files of arbitrary type can be
useful, but it was not considered necessary to mandate that an \fIex\fP
or \fIvi\fP
implementation be required to handle files other than text files.
.LP
The paragraph in the INPUT FILES section, "By default, ...", is intended
to close a long-standing security problem in
\fIex\fP and \fIvi\fP; that of the "modeline" or "modelines" edit
option. This feature
allows any line in the first or last five lines of the file containing
the strings \fB"ex:"\fP or \fB"vi:"\fP (and,
apparently, \fB"ei:"\fP or \fB"vx:"\fP ) to be a line containing editor
commands, and \fIex\fP interprets all the text up to
the next \fB':'\fP or <newline> as a command. Consider the consequences,
for example, of an unsuspecting user using
\fIex\fP or \fIvi\fP as the editor when replying to a mail message
in which a line such
as:
.sp
.RS
.nf

\fBex:! rm -rf :
\fP
.fi
.RE
.LP
appeared in the signature lines. The standard developers believed
strongly that an editor should not by default interpret any
lines of a file. Vendors are strongly urged to delete this feature
from their implementations of \fIex\fP and \fIvi\fP.
.SS Asynchronous Events
.LP
The intention of the phrase "complete write" is that the entire edit
buffer be written to stable storage. The note regarding
temporary files is intended for implementations that use temporary
files to back edit buffers unnamed by the user.
.LP
Historically, SIGQUIT was ignored by \fIex\fP, but was the equivalent
of the \fBQ\fP command in visual mode; that is, it
exited visual mode and entered \fIex\fP mode. IEEE\ Std\ 1003.1-2001
permits, but does not require, this behavior.
Historically, SIGINT was often used by \fIvi\fP users to terminate
text input mode (
<control>-C is often easier to enter than <ESC>). Some implementations
of \fIvi\fP
alerted the terminal on this event, and some did not. IEEE\ Std\ 1003.1-2001
requires that SIGINT behave identically to
<ESC>, and that the terminal not be alerted.
.LP
Historically, suspending the \fIex\fP editor during text input mode
was similar to SIGINT, as completed lines were retained,
but any partial line discarded, and the editor returned to command
mode. IEEE\ Std\ 1003.1-2001 is silent on this issue;
implementations are encouraged to follow historical practice, where
possible.
.LP
Historically, the \fIvi\fP editor did not treat SIGTSTP as an asynchronous
event, and it was
therefore impossible to suspend the editor in visual text input mode.
There are two major reasons for this. The first is that
SIGTSTP is a broadcast signal on UNIX systems, and the chain of events
where the shell \fIexec\fPs an application that then \fIexec\fPs \fIvi\fP
usually caused confusion for the
terminal state if SIGTSTP was delivered to the process group in the
default manner. The second was that most implementations of the
UNIX \fIcurses\fP package are not reentrant, and the receipt of SIGTSTP
at the wrong time will cause them to crash.
IEEE\ Std\ 1003.1-2001 is silent on this issue; implementations are
encouraged to treat suspension as an asynchronous event
if possible.
.LP
Historically, modifications to the edit buffer made before SIGINT
interrupted an operation were retained; that is, anywhere from
zero to all of the lines to be modified might have been modified by
the time the SIGINT arrived. These changes were not discarded
by the arrival of SIGINT. IEEE\ Std\ 1003.1-2001 permits this behavior,
noting that the \fBundo\fP command is required to
be able to undo these partially completed commands.
.LP
The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and
SIGTERM is unspecified because some implementations attempt
to save the edit buffer in a useful state when other signals are received.
.SS Standard Error
.LP
For \fIex\fP/ \fIvi\fP, diagnostic messages are those messages reported
as a result of a
failed attempt to invoke \fIex\fP or \fIvi\fP, such as invalid options
or insufficient
resources, or an abnormal termination condition. Diagnostic messages
should not be confused with the error messages generated by
inappropriate or illegal user commands.
.SS Initialization in ex and vi
.LP
If an \fIex\fP command (other than \fBcd\fP, \fBchdir\fP, or \fBsource\fP)
has a filename argument, one or both of the
alternate and current pathnames will be set. Informally, they are
set as follows:
.IP " 1." 4
If the \fIex\fP command is one that replaces the contents of the edit
buffer, and it succeeds, the current pathname will be set
to the filename argument (the first filename argument in the case
of the \fBnext\fP command) and the alternate pathname will be
set to the previous current pathname, if there was one.
.LP
.IP " 2." 4
In the case of the file read/write forms of the \fBread\fP and \fBwrite\fP
commands, if there is no current pathname, the
current pathname will be set to the filename argument.
.LP
.IP " 3." 4
Otherwise, the alternate pathname will be set to the filename argument.
.LP
.LP
For example, \fB:edit foo\fP and \fB:recover foo\fP, when successful,
set the current pathname, and, if there was a previous
current pathname, the alternate pathname. The commands \fB:write\fP,
\fB!command\fP, and \fB:edit\fP set neither the current or
alternate pathnames. If the \fB:edit foo\fP command were to fail for
some reason, the alternate pathname would be set. The
\fBread\fP and \fBwrite\fP commands set the alternate pathname to
their \fIfile\fP argument, unless the current pathname is not
set, in which case they set the current pathname to their \fIfile\fP
arguments. The alternate pathname was not historically set by
the \fB:source\fP command. IEEE\ Std\ 1003.1-2001 requires conformance
to historical practice. Implementations adding
commands that take filenames as arguments are encouraged to set the
alternate pathname as described here.
.LP
Historically, \fIex\fP and \fIvi\fP read the \fB.exrc\fP file in the
\fI$HOME\fP
directory twice, if the editor was executed in the \fI$HOME\fP directory.
IEEE\ Std\ 1003.1-2001 prohibits this
behavior.
.LP
Historically, the 4 BSD \fIex\fP and \fIvi\fP read the \fI$HOME\fP
and local \fB.exrc\fP
files if they were owned by the real ID of the user, or the \fBsourceany\fP
option was set, regardless of other considerations.
This was a security problem because it is possible to put normal UNIX
system commands inside a \fB.exrc\fP file.
IEEE\ Std\ 1003.1-2001 does not specify the \fBsourceany\fP option,
and historical implementations are encouraged to
delete it.
.LP
The \fB.exrc\fP files must be owned by the real ID of the user, and
not writable by anyone other than the owner. The
appropriate privileges exception is intended to permit users to acquire
special privileges, but continue to use the \fB.exrc\fP
files in their home directories.
.LP
System V Release 3.2 and later \fIvi\fP implementations added the
option \fB[no]exrc\fP.
The behavior is that local \fB.exrc\fP files are read-only if the
\fBexrc\fP option is set. The default for the \fBexrc\fP
option was off, so by default, local \fB.exrc\fP files were not read.
The problem this was intended to solve was that System V
permitted users to give away files, so there is no possible ownership
or writeability test to ensure that the file is safe. This is
still a security problem on systems where users can give away files,
but there is nothing additional that
IEEE\ Std\ 1003.1-2001 can do. The implementation-defined exception
is intended to permit groups to have local \fB.exrc\fP
files that are shared by users, by creating pseudo-users to own the
shared files.
.LP
IEEE\ Std\ 1003.1-2001 does not mention system-wide \fIex\fP and \fIvi\fP
start-up
files. While they exist in several implementations of \fIex\fP and
\fIvi\fP, they are not
present in any implementations considered historical practice by IEEE\ Std\ 1003.1-2001.
Implementations that have such
files should use them only if they are owned by the real user ID or
an appropriate user (for example, root on UNIX systems) and if
they are not writable by any user other than their owner. System-wide
start-up files should be read before the \fIEXINIT\fP
variable, \fB$HOME/.exrc\fP, or local \fB.exrc\fP files are evaluated.
.LP
Historically, any \fIex\fP command could be entered in the \fIEXINIT\fP
variable or the \fB.exrc\fP file, although ones
requiring that the edit buffer already contain lines of text generally
caused historical implementations of the editor to drop
\fBcore\fP. IEEE\ Std\ 1003.1-2001 requires that any \fIex\fP command
be permitted in the \fIEXINIT\fP variable and
\fB\&.exrc\fP files, for simplicity of specification and consistency,
although many of them will obviously fail under many
circumstances.
.LP
The initialization of the contents of the edit buffer uses the phrase
"the effect shall be" with regard to various \fIex\fP
commands. The intent of this phrase is that edit buffer contents loaded
during the initialization phase not be lost; that is,
loading the edit buffer should fail if the \fB.exrc\fP file read in
the contents of a file and did not subsequently write the edit
buffer. An additional intent of this phrase is to specify that the
initial current line and column is set as specified for the
individual \fIex\fP commands.
.LP
Historically, the \fB-t\fP option behaved as if the tag search were
a \fB+\fP \fIcommand\fP; that is, it was executed from
the last line of the file specified by the tag. This resulted in the
search failing if the pattern was a forward search pattern and
the \fBwrapscan\fP edit option was not set. IEEE\ Std\ 1003.1-2001
does not permit this behavior, requiring that the
search for the tag pattern be performed on the entire file, and, if
not found, that the current line be set to a more reasonable
location in the file.
.LP
Historically, the empty edit buffer presented for editing when a file
was not specified by the user was unnamed. This is
permitted by IEEE\ Std\ 1003.1-2001; however, implementations are
encouraged to provide users a temporary filename for this
buffer because it permits them the use of \fIex\fP commands that use
the current pathname during temporary edit sessions.
.LP
Historically, the file specified using the \fB-t\fP option was not
part of the current argument list. This practice is
permitted by IEEE\ Std\ 1003.1-2001; however, implementations are
encouraged to include its name in the current argument
list for consistency.
.LP
Historically, the \fB-c\fP command was generally not executed until
a file that already exists was edited.
IEEE\ Std\ 1003.1-2001 requires conformance to this historical practice.
Commands that could cause the \fB-c\fP command to
be executed include the \fIex\fP commands \fBedit\fP, \fBnext\fP,
\fBrecover\fP, \fBrewind\fP, and \fBtag\fP, and the \fIvi\fP commands
<control>-^ and <control>-]. Historically, reading a file into an
edit buffer did not cause the \fB-c\fP command to be executed (even
though it might set the current pathname) with the exception
that it did cause the \fB-c\fP command to be executed if: the editor
was in \fIex\fP mode, the edit buffer had no current
pathname, the edit buffer was empty, and no read commands had yet
been attempted. For consistency and simplicity of specification,
IEEE\ Std\ 1003.1-2001 does not permit this behavior.
.LP
Historically, the \fB-r\fP option was the same as a normal edit session
if there was no recovery information available for the
file. This allowed users to enter:
.sp
.RS
.nf

\fBvi -r *.c
\fP
.fi
.RE
.LP
and recover whatever files were recoverable. In some implementations,
recovery was attempted only on the first file named, and
the file was not entered into the argument list; in others, recovery
was attempted for each file named. In addition, some
historical implementations ignored \fB-r\fP if \fB-t\fP was specified
or did not support command line \fIfile\fP arguments with
the \fB-t\fP option. For consistency and simplicity of specification,
IEEE\ Std\ 1003.1-2001 disallows these special
cases, and requires that recovery be attempted the first time each
file is edited.
.LP
Historically, \fIvi\fP initialized the \fB`\fP and \fB'\fP marks,
but \fIex\fP did not.
This meant that if the first command in \fIex\fP mode was \fBvisual\fP
or if an \fIex\fP command was executed first (for
example, \fIvi\fP +10 \fIfile\fP), \fIvi\fP was entered
without the marks being initialized. Because the standard developers
believed the marks to be generally useful, and for consistency
and simplicity of specification, IEEE\ Std\ 1003.1-2001 requires that
they always be initialized if in open or visual mode,
or if in \fIex\fP mode and the edit buffer is not empty. Not initializing
it in \fIex\fP mode if the edit buffer is empty is
historical practice; however, it has always been possible to set (and
use) marks in empty edit buffers in open and visual mode edit
sessions.
.SS Addressing
.LP
Historically, \fIex\fP and \fIvi\fP accepted the additional addressing
forms \fB'\\/'\fP
and \fB'\\?'\fP . They were equivalent to \fB"//"\fP and \fB"??"\fP
, respectively. They are not required by
IEEE\ Std\ 1003.1-2001, mostly because nobody can remember whether
they ever did anything different historically.
.LP
Historically, \fIex\fP and \fIvi\fP permitted an address of zero for
several commands, and
permitted the \fB%\fP address in empty files for others. For consistency,
IEEE\ Std\ 1003.1-2001 requires support for the
former in the few commands where it makes sense, and disallows it
otherwise. In addition, because IEEE\ Std\ 1003.1-2001
requires that \fB%\fP be logically equivalent to \fB"1,$"\fP , it
is also supported where it makes sense and disallowed
otherwise.
.LP
Historically, the \fB%\fP address could not be followed by further
addresses. For consistency and simplicity of specification,
IEEE\ Std\ 1003.1-2001 requires that additional addresses be supported.
.LP
All of the following are valid \fIaddresses\fP:
.TP 7
\fB+++\fP
Three lines after the current line.
.TP 7
\fB/\fP\fIre\fP\fB/-\fP
One line before the next occurrence of \fIre\fP.
.TP 7
\fB-2\fP
Two lines before the current line.
.TP 7
\fB3\ ----\ 2\fP
Line one (note intermediate negative address).
.TP 7
\fB1\ 2\ 3\fP
Line six.
.sp
.LP
Any number of addresses can be provided to commands taking addresses;
for example, \fB"1,2,3,4,5p"\fP prints lines 4 and 5,
because two is the greatest valid number of addresses accepted by
the \fBprint\fP command. This, in combination with the semicolon
delimiter, permits users to create commands based on ordered patterns
in the file. For example, the command \fB3;/foo/;+2print\fP
will display the first line after line 3 that contains the pattern
\fIfoo\fP, plus the next two lines. Note that the address
\fB3;\fP must be evaluated before being discarded because the search
origin for the \fB/foo/\fP command depends on this.
.LP
Historically, values could be added to addresses by including them
after one or more <blank>s; for example,
\fB3\ -\ 5p\fP wrote the seventh line of the file, and \fB/foo/\ 5\fP
was the same as \fB/foo/+5\fP. However, only
absolute values could be added; for example, \fB5\ /foo/\fP was an
error. IEEE\ Std\ 1003.1-2001 requires conformance
to historical practice. Address offsets are separately specified from
addresses because they could historically be provided to
visual mode search commands.
.LP
Historically, any missing addresses defaulted to the current line.
This was true for leading and trailing comma-delimited
addresses, and for trailing semicolon-delimited addresses. For consistency,
IEEE\ Std\ 1003.1-2001 requires it for leading
semicolon addresses as well.
.LP
Historically, \fIex\fP and \fIvi\fP accepted the \fB'^'\fP character
as both an address
and as a flag offset for commands. In both cases it was identical
to the \fB'-'\fP character. IEEE\ Std\ 1003.1-2001
does not require or prohibit this behavior.
.LP
Historically, the enhancements to basic regular expressions could
be used in addressing; for example, \fB'~'\fP ,
\fB'\\<'\fP , and \fB'\\>'\fP . IEEE\ Std\ 1003.1-2001 requires conformance
to historical practice; that is, that
regular expression usage be consistent, and that regular expression
enhancements be supported wherever regular expressions are
used.
.SS Command Line Parsing in ex
.LP
Historical \fIex\fP command parsing was even more complex than that
described here. IEEE\ Std\ 1003.1-2001 requires the
subset of the command parsing that the standard developers believed
was documented and that users could reasonably be expected to
use in a portable fashion, and that was historically consistent between
implementations. (The discarded functionality is obscure,
at best.) Historical implementations will require changes in order
to comply with IEEE\ Std\ 1003.1-2001; however, users
are not expected to notice any of these changes. Most of the complexity
in \fIex\fP parsing is to handle three special termination
cases:
.IP " 1." 4
The \fB!\fP, \fBglobal\fP, \fBv\fP, and the filter versions of the
\fBread\fP and \fBwrite\fP commands are delimited by
<newline>s (they can contain vertical-line characters that are usually
shell pipes).
.LP
.IP " 2." 4
The \fBex\fP, \fBedit\fP, \fBnext\fP, and \fBvisual\fP in open and
visual mode commands all take \fIex\fP commands,
optionally containing vertical-line characters, as their first arguments.
.LP
.IP " 3." 4
The \fBs\fP command takes a regular expression as its first argument,
and uses the delimiting characters to delimit the
command.
.LP
.LP
Historically, vertical-line characters in the \fB+\fP \fIcommand\fP
argument of the \fBex\fP, \fBedit\fP, \fBnext\fP,
\fBvi\fP, and \fBvisual\fP commands, and in the \fIpattern\fP and
\fIreplacement\fP parts of the \fBs\fP command, did not
delimit the command, and in the filter cases for \fBread\fP and \fBwrite\fP,
and the \fB!\fP, \fBglobal\fP, and \fBv\fP
commands, they did not delimit the command at all. For example, the
following commands are all valid:
.sp
.RS
.nf

\fB:\fP\fBedit +25 | s/abc/ABC/ file.c
\fP\fB:\fP\fBs/ | /PIPE/
\fP\fB:\fP\fBread !spell % | columnate
\fP\fB:\fP\fBglobal/pattern/p | l
\fP\fB:\fP\fBs/a/b/ | s/c/d | set
\fP
.fi
.RE
.LP
Historically, empty or <blank> filled lines in \fB.exrc\fP files and
\fBsource\fPd files (as well as \fIEXINIT\fP
variables and \fIex\fP command scripts) were treated as default commands;
that is, \fBprint\fP commands.
IEEE\ Std\ 1003.1-2001 specifically requires that they be ignored
when encountered in \fB.exrc\fP and \fBsource\fPd files
to eliminate a common source of new user error.
.LP
Historically, \fIex\fP commands with multiple adjacent (or <blank>-separated)
vertical lines were handled oddly when
executed from \fIex\fP mode. For example, the command \fB|||\fP <carriage-return>,
when the cursor was on line 1, displayed
lines 2, 3, and 5 of the file. In addition, the command \fB|\fP would
only display the line after the next line, instead of the
next two lines. The former worked more logically when executed from
\fIvi\fP mode, and
displayed lines 2, 3, and 4. IEEE\ Std\ 1003.1-2001 requires the \fIvi\fP
behavior;
that is, a single default command and line number increment for each
command separator, and trailing <newline>s after
vertical-line separators are discarded.
.LP
Historically, \fIex\fP permitted a single extra colon as a leading
command character; for example, \fB:g/pattern/:p\fP was a
valid command. IEEE\ Std\ 1003.1-2001 generalizes this to require
that any number of leading colon characters be
stripped.
.LP
Historically, any prefix of the \fBdelete\fP command could be followed
without intervening <blank>s by a flag character
because in the command \fBd\ p\fP, \fIp\fP is interpreted as the buffer
\fIp\fP. IEEE\ Std\ 1003.1-2001 requires
conformance to historical practice.
.LP
Historically, the \fBk\fP command could be followed by the mark name
without intervening <blank>s.
IEEE\ Std\ 1003.1-2001 requires conformance to historical practice.
.LP
Historically, the \fBs\fP command could be immediately followed by
flag and option characters; for example,
\fBs/e/E/|s|sgc3p\fP was a valid command. However, flag characters
could not stand alone; for example, the commands \fBsp\fP and
\fBs\ l\fP would fail, while the command \fBsgp\fP and \fBs\ gl\fP
would succeed. (Obviously, the \fB'#'\fP flag
character was used as a delimiter character if it followed the command.)
Another issue was that option characters had to precede
flag characters even when the command was fully specified; for example,
the command \fBs/e/E/pg\fP would fail, while the command
\fBs/e/E/gp\fP would succeed. IEEE\ Std\ 1003.1-2001 requires conformance
to historical practice.
.LP
Historically, the first command name that had a prefix matching the
input from the user was the executed command; for example,
\fBve\fP, \fBver\fP, and \fBvers\fP all executed the \fBversion\fP
command. Commands were in a specific order, however, so that
\fBa\fP matched \fBappend\fP, not \fBabbreviate\fP. IEEE\ Std\ 1003.1-2001
requires conformance to historical practice.
The restriction on command search order for implementations with extensions
is to avoid the addition of commands such that the
historical prefixes would fail to work portably.
.LP
Historical implementations of \fIex\fP and \fIvi\fP did not correctly
handle multiple
\fIex\fP commands, separated by vertical-line characters, that entered
or exited visual mode or the editor. Because
implementations of \fIvi\fP exist that do not exhibit this failure
mode,
IEEE\ Std\ 1003.1-2001 does not permit it.
.LP
The requirement that alphabetic command names consist of all following
alphabetic characters up to the next non-alphabetic
character means that alphabetic command names must be separated from
their arguments by one or more non-alphabetic characters,
normally a <blank> or \fB'!'\fP character, except as specified for
the exceptions, the \fBdelete\fP, \fBk\fP, and
\fBs\fP commands.
.LP
Historically, the repeated execution of the \fIex\fP default \fBprint\fP
commands ( <control>-D, \fIeof\fP,
<newline>, <carriage-return>) erased any prompting character and displayed
the next lines without scrolling the
terminal; that is, immediately below any previously displayed lines.
This provided a cleaner presentation of the lines in the file
for the user. IEEE\ Std\ 1003.1-2001 does not require this behavior
because it may be impossible in some situations;
however, implementations are strongly encouraged to provide this semantic
if possible.
.LP
Historically, it was possible to change files in the middle of a command,
and have the rest of the command executed in the new
file; for example:
.sp
.RS
.nf

\fB:edit +25 file.c | s/abc/ABC/ | 1
\fP
.fi
.RE
.LP
was a valid command, and the substitution was attempted in the newly
edited file. IEEE\ Std\ 1003.1-2001 requires
conformance to historical practice. The following commands are examples
that exercise the \fIex\fP parser:
.sp
.RS
.nf

\fBecho 'foo | bar' > file1; echo 'foo/bar' > file2;
vi
:edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\\//SLASH/ | wq
\fP
.fi
.RE
.LP
Historically, there was no protection in editor implementations to
avoid \fIex\fP \fBglobal\fP, \fBv\fP, \fB@\fP, or
\fB*\fP commands changing edit buffers during execution of their associated
commands. Because this would almost invariably result
in catastrophic failure of the editor, and implementations exist that
do exhibit these problems, IEEE\ Std\ 1003.1-2001
requires that changing the edit buffer during a \fBglobal\fP or \fBv\fP
command, or during a \fB@\fP or \fB*\fP command for
which there will be more than a single execution, be an error. Implementations
supporting multiple edit buffers simultaneously are
strongly encouraged to apply the same semantics to switching between
buffers as well.
.LP
The \fIex\fP command quoting required by IEEE\ Std\ 1003.1-2001 is
a superset of the quoting in historical
implementations of the editor. For example, it was not historically
possible to escape a <blank> in a filename; for example,
\fB:edit\ foo\\\\\\\ bar\fP would report that too many filenames had
been entered for the edit command, and there was no
method of escaping a <blank> in the first argument of an \fBedit\fP,
\fBex\fP, \fBnext\fP, or \fBvisual\fP command at
all. IEEE\ Std\ 1003.1-2001 extends historical practice, requiring
that quoting behavior be made consistent across all
\fIex\fP commands, except for the \fBmap\fP, \fBunmap\fP, \fBabbreviate\fP,
and \fBunabbreviate\fP commands, which
historically used <control>-V instead of backslashes for quoting.
For those four commands, IEEE\ Std\ 1003.1-2001
requires conformance to historical practice.
.LP
Backslash quoting in \fIex\fP is non-intuitive. Backslash escapes
are ignored unless they escape a special character; for
example, when performing \fIfile\fP argument expansion, the string
\fB"\\\\%"\fP is equivalent to \fB'\\%'\fP , not
\fB"\\<\fP\fIcurrent\ pathname\fP\fB>"\fP. This can be confusing for
users because backslash is usually one of the
characters that causes shell expansion to be performed, and therefore
shell quoting rules must be taken into consideration.
Generally, quoting characters are only considered if they escape a
special character, and a quoting character must be provided for
each layer of parsing for which the character is special. As another
example, only a single backslash is necessary for the
\fB'\\l'\fP sequence in substitute replacement patterns, because the
character \fB'l'\fP is not special to any parsing layer
above it.
.LP
<control>-V quoting in \fIex\fP is slightly different from backslash
quoting. In the four commands where
<control>-V quoting applies ( \fBabbreviate\fP, \fBunabbreviate\fP,
\fBmap\fP, and \fBunmap\fP), any character may be
escaped by a <control>-V whether it would have a special meaning or
not. IEEE\ Std\ 1003.1-2001 requires conformance
to historical practice.
.LP
Historical implementations of the editor did not require delimiters
within character classes to be escaped; for example, the
command \fB:s/[/]//\fP on the string \fB"xxx/yyy"\fP would delete
the \fB'/'\fP from the string.
IEEE\ Std\ 1003.1-2001 disallows this historical practice for consistency
and because it places a large burden on
implementations by requiring that knowledge of regular expressions
be built into the editor parser.
.LP
Historically, quoting <newline>s in \fIex\fP commands was handled
inconsistently. In most cases, the <newline>
always terminated the command, regardless of any preceding escape
character, because backslash characters did not escape
<newline>s for most \fIex\fP commands. However, some \fIex\fP commands
(for example, \fBs\fP, \fBmap\fP, and
\fBabbreviation\fP) permitted <newline>s to be escaped (although in
the case of \fBmap\fP and \fBabbreviation\fP,
<control>-V characters escaped them instead of backslashes). This
was true in not only the command line, but also
\fB\&.exrc\fP and \fBsource\fPd files. For example, the command:
.sp
.RS
.nf

\fBmap = foo<control-V><newline>bar
\fP
.fi
.RE
.LP
would succeed, although it was sometimes difficult to get the <control>-V
and the inserted <newline> passed to the
\fIex\fP parser. For consistency and simplicity of specification,
IEEE\ Std\ 1003.1-2001 requires that it be possible to
escape <newline>s in \fIex\fP commands at all times, using backslashes
for most \fIex\fP commands, and using
<control>-V characters for the \fBmap\fP and \fBabbreviation\fP commands.
For example, the command \fBprint\fP
<newline> \fBlist\fP is required to be parsed as the single command
\fBprint\fP <newline> \fBlist\fP. While this
differs from historical practice, IEEE\ Std\ 1003.1-2001 developers
believed it unlikely that any script or user depended
on the historical behavior.
.LP
Historically, an error in a command specified using the \fB-c\fP option
did not cause the rest of the \fB-c\fP commands to be
discarded. IEEE\ Std\ 1003.1-2001 disallows this for consistency with
mapped keys, the \fB@\fP, \fBglobal\fP,
\fBsource\fP, and \fBv\fP commands, the \fIEXINIT\fP environment variable,
and the \fB.exrc\fP files.
.SS Input Editing in ex
.LP
One of the common uses of the historical \fIex\fP editor is over slow
network connections. Editors that run in canonical mode
can require far less traffic to and from, and far less processing
on, the host machine, as well as more easily supporting
block-mode terminals. For these reasons, IEEE\ Std\ 1003.1-2001 requires
that \fIex\fP be implemented using canonical mode
input processing, as was done historically.
.LP
IEEE\ Std\ 1003.1-2001 does not require the historical 4 BSD input
editing characters "word erase" or "literal
next". For this reason, it is unspecified how they are handled by
\fIex\fP, although they must have the required effect.
Implementations that resolve them after the line has been ended using
a <newline> or <control>-M character, and
implementations that rely on the underlying system terminal support
for this processing, are both conforming. Implementations are
strongly urged to use the underlying system functionality, if at all
possible, for compatibility with other system text input
interfaces.
.LP
Historically, when the \fIeof\fP character was used to decrement the
\fBautoindent\fP level, the cursor moved to display the
new end of the \fBautoindent\fP characters, but did not move the cursor
to a new line, nor did it erase the <control>-D
character from the line. IEEE\ Std\ 1003.1-2001 does not specify that
the cursor remain on the same line or that the rest
of the line is erased; however, implementations are strongly encouraged
to provide the best possible user interface; that is, the
cursor should remain on the same line, and any <control>-D character
on the line should be erased.
.LP
IEEE\ Std\ 1003.1-2001 does not require the historical 4 BSD input
editing character "reprint", traditionally
<control>-R, which redisplayed the current input from the user. For
this reason, and because the functionality cannot be
implemented after the line has been terminated by the user, IEEE\ Std\ 1003.1-2001
makes no requirements about this
functionality. Implementations are strongly urged to make this historical
functionality available, if possible.
.LP
Historically, <control>-Q did not perform a literal next function
in \fIex\fP, as it did in \fIvi\fP. IEEE\ Std\ 1003.1-2001 requires
conformance to historical practice to avoid breaking
historical \fIex\fP scripts and \fB.exrc\fP files.
.SS eof
.LP
Whether the \fIeof\fP character immediately modifies the \fBautoindent\fP
characters in the prompt is left unspecified so that
implementations can conform in the presence of systems that do not
support this functionality. Implementations are encouraged to
modify the line and redisplay it immediately, if possible.
.LP
The specification of the handling of the \fIeof\fP character differs
from historical practice only in that \fIeof\fP
characters are not discarded if they follow normal characters in the
text input. Historically, they were always discarded.
.SS Command Descriptions in ex
.LP
Historically, several commands (for example, \fBglobal\fP, \fBv\fP,
\fBvisual\fP, \fBs\fP, \fBwrite\fP, \fBwq\fP,
\fByank\fP, \fB!\fP, \fB<\fP, \fB>\fP, \fB&\fP, and \fB~\fP) were
executable in empty files (that is, the
default address(es) were 0), or permitted explicit addresses of 0
(for example, 0 was a valid address, or 0,0 was a valid range).
Addresses of 0, or command execution in an empty file, make sense
only for commands that add new text to the edit buffer or write
commands (because users may wish to write empty files). IEEE\ Std\ 1003.1-2001
requires this behavior for such commands and
disallows it otherwise, for consistency and simplicity of specification.
.LP
A count to an \fIex\fP command has been historically corrected to
be no greater than the last line in a file; for example, in a
five-line file, the command \fB1,6print\fP would fail, but the command
\fB1print300\fP would succeed.
IEEE\ Std\ 1003.1-2001 requires conformance to historical practice.
.LP
Historically, the use of flags in \fIex\fP commands could be obscure.
General historical practice was as described by
IEEE\ Std\ 1003.1-2001, but there were some special cases. For instance,
the \fBlist\fP, \fBnumber\fP, and \fBprint\fP
commands ignored trailing address offsets; for example, \fB3p\ +++#\fP
would display line 3, and 3 would be the current line
after the execution of the command. The \fBopen\fP and \fBvisual\fP
commands ignored both the trailing offsets and the trailing
flags. Also, flags specified to the \fBopen\fP and \fBvisual\fP commands
interacted badly with the \fBlist\fP edit option, and
setting and then unsetting it during the open/visual session would
cause \fIvi\fP to stop
displaying lines in the specified format. For consistency and simplicity
of specification, IEEE\ Std\ 1003.1-2001 does not
permit any of these exceptions to the general rule.
.LP
IEEE\ Std\ 1003.1-2001 uses the word \fIcopy\fP in several places
when discussing buffers. This is not intended to
imply implementation.
.LP
Historically, \fIex\fP users could not specify numeric buffers because
of the ambiguity this would cause; for example, in the
command \fB3\ delete\ 2\fP, it is unclear whether 2 is a buffer name
or a \fIcount\fP. IEEE\ Std\ 1003.1-2001
requires conformance to historical practice by default, but does not
preclude extensions.
.LP
Historically, the contents of the unnamed buffer were frequently discarded
after commands that did not explicitly affect it; for
example, when using the \fBedit\fP command to switch files. For consistency
and simplicity of specification,
IEEE\ Std\ 1003.1-2001 does not permit this behavior.
.LP
The \fIex\fP utility did not historically have access to the numeric
buffers, and, furthermore, deleting lines in \fIex\fP did
not modify their contents. For example, if, after doing a delete in
\fIvi\fP, the user switched
to \fIex\fP, did another delete, and then switched back to \fIvi\fP,
the contents of the
numeric buffers would not have changed. IEEE\ Std\ 1003.1-2001 requires
conformance to historical practice. Numeric buffers
are described in the \fIex\fP utility in order to confine the description
of buffers to a single location in
IEEE\ Std\ 1003.1-2001.
.LP
The metacharacters that trigger shell expansion in \fIfile\fP arguments
match historical practice, as does the method for doing
shell expansion. Implementations wishing to provide users with the
flexibility to alter the set of metacharacters are encouraged to
provide a \fBshellmeta\fP string edit option.
.LP
Historically, \fIex\fP commands executed from \fIvi\fP refreshed the
screen when it did not
strictly need to do so; for example, \fB:!date\ >\ /dev/null\fP does
not require a screen refresh because the output of
the UNIX \fIdate\fP command requires only a single line of the screen.
IEEE\ Std\ 1003.1-2001 requires that the screen be refreshed if it
has been overwritten, but makes no requirements as to
how an implementation should make that determination. Implementations
may prompt and refresh the screen regardless.
.SS Abbreviate
.LP
Historical practice was that characters that were entered as part
of an abbreviation replacement were subject to \fBmap\fP
expansions, the \fBshowmatch\fP edit option, further abbreviation
expansions, and so on; that is, they were logically pushed onto
the terminal input queue, and were not a simple replacement. IEEE\ Std\ 1003.1-2001
requires conformance to historical
practice. Historical practice was that whenever a non-word character
(that had not been escaped by a <control>-V) was entered
after a word character, \fIvi\fP would check for abbreviations. The
check was based on the type
of the character entered before the word character of the word/non-word
pair that triggered the check. The word character of the
word/non-word pair that triggered the check and all characters entered
before the trigger pair that were of that type were included
in the check, with the exception of <blank>s, which always delimited
the abbreviation.
.LP
This means that, for the abbreviation to work, the \fIlhs\fP must
end with a word character, there can be no transitions from
word to non-word characters (or \fIvice versa\fP) other than between
the last and next-to-last characters in the \fIlhs\fP, and
there can be no <blank>s in the \fIlhs\fP. In addition, because of
the historical quoting rules, it was impossible to enter
a literal <control>-V in the \fIlhs\fP. IEEE\ Std\ 1003.1-2001 requires
conformance to historical practice.
Historical implementations did not inform users when abbreviations
that could never be used were entered; implementations are
strongly encouraged to do so.
.LP
For example, the following abbreviations will work:
.sp
.RS
.nf

\fB:ab (p  REPLACE
:ab p   REPLACE
:ab ((p REPLACE
\fP
.fi
.RE
.LP
The following abbreviations will not work:
.sp
.RS
.nf

\fB:ab (   REPLACE
:ab (pp REPLACE
\fP
.fi
.RE
.LP
Historical practice is that words on the \fIvi\fP colon command line
were subject to
abbreviation expansion, including the arguments to the \fBabbrev\fP
(and more interestingly) the \fBunabbrev\fP command. Because
there are implementations that do not do abbreviation expansion for
the first argument to those commands, this is permitted, but
not required, by IEEE\ Std\ 1003.1-2001. However, the following sequence:
.sp
.RS
.nf

\fB:ab foo bar
:ab foo baz
\fP
.fi
.RE
.LP
resulted in the addition of an abbreviation of \fB"baz"\fP for the
string \fB"bar"\fP in historical \fIex\fP/ \fIvi\fP, and the sequence:
.sp
.RS
.nf

\fB:ab foo1 bar
:ab foo2 bar
:unabbreviate foo2
\fP
.fi
.RE
.LP
deleted the abbreviation \fB"foo1"\fP , not \fB"foo2"\fP . These behaviors
are not permitted by
IEEE\ Std\ 1003.1-2001 because they clearly violate the expectations
of the user.
.LP
It was historical practice that <control>-V, not backslash, characters
be interpreted as escaping subsequent characters in
the \fBabbreviate\fP command. IEEE\ Std\ 1003.1-2001 requires conformance
to historical practice; however, it should be
noted that an abbreviation containing a <blank> will never work.
.SS Append
.LP
Historically, any text following a vertical-line command separator
after an \fBappend\fP, \fBchange\fP, or \fBinsert\fP
command became part of the insert text. For example, in the command:
.sp
.RS
.nf

\fB:g/pattern/append|stuff1
\fP
.fi
.RE
.LP
a line containing the text \fB"stuff1"\fP would be appended to each
line matching pattern. It was also historically valid to
enter:
.sp
.RS
.nf

\fB:append|stuff1
stuff2
\&.
\fP
.fi
.RE
.LP
and the text on the \fIex\fP command line would be appended along
with the text inserted after it. There was an historical bug,
however, that the user had to enter two terminating lines (the \fB'.'\fP
lines) to terminate text input mode in this case.
IEEE\ Std\ 1003.1-2001 requires conformance to historical practice,
but disallows the historical need for multiple
terminating lines.
.SS Change
.LP
See the RATIONALE for the \fBappend\fP command. Historical practice
for cursor positioning after the change command when no
text is input, is as described in IEEE\ Std\ 1003.1-2001. However,
one System V implementation is known to have been
modified such that the cursor is positioned on the first address specified,
and not on the line before the first address.
IEEE\ Std\ 1003.1-2001 disallows this modification for consistency.
.LP
Historically, the \fBchange\fP command did not support buffer arguments,
although some implementations allow the specification
of an optional buffer. This behavior is neither required nor disallowed
by IEEE\ Std\ 1003.1-2001.
.SS Change Directory
.LP
A common extension in \fIex\fP implementations is to use the elements
of a \fBcdpath\fP edit option as prefix directories for
\fIpath\fP arguments to \fBchdir\fP that are relative pathnames and
that do not have \fB'.'\fP or \fB".."\fP as their first
component. Elements in the \fBcdpath\fP edit option are colon-separated.
The initial value of the \fBcdpath\fP edit option is the
value of the shell \fICDPATH\fP environment variable. This feature
was not included in IEEE\ Std\ 1003.1-2001 because it
does not exist in any of the implementations considered historical
practice.
.SS Copy
.LP
Historical implementations of \fIex\fP permitted copies to lines inside
of the specified range; for example, \fB:2,5copy3\fP
was a valid command. IEEE\ Std\ 1003.1-2001 requires conformance to
historical practice.
.SS Delete
.LP
IEEE\ Std\ 1003.1-2001 requires support for the historical parsing
of a \fBdelete\fP command followed by flags, without
any intervening <blank>s. For example:
.TP 7
\fB1dp\fP
Deletes the first line and prints the line that was second.
.TP 7
\fB1delep\fP
As for \fB1dp\fP.
.TP 7
\fB1d\fP
Deletes the first line, saving it in buffer \fIp\fP.
.TP 7
\fB1d\ p1l\fP
(Pee-one-ell.) Deletes the first line, saving it in buffer \fIp\fP,
and listing the line that was second.
.sp
.SS Edit
.LP
Historically, any \fIex\fP command could be entered as a \fB+\fP \fIcommand\fP
argument to the \fBedit\fP command, although
some (for example, \fBinsert\fP and \fBappend\fP) were known to confuse
historical implementations. For consistency and
simplicity of specification, IEEE\ Std\ 1003.1-2001 requires that
any command be supported as an argument to the
\fBedit\fP command.
.LP
Historically, the command argument was executed with the current line
set to the last line of the file, regardless of whether
the \fBedit\fP command was executed from visual mode or not. IEEE\ Std\ 1003.1-2001
requires conformance to historical
practice.
.LP
Historically, the \fB+\fP \fIcommand\fP specified to the \fBedit\fP
and \fBnext\fP commands was delimited by the first
<blank>, and there was no way to quote them. For consistency, IEEE\ Std\ 1003.1-2001
requires that the usual
\fIex\fP backslash quoting be provided.
.LP
Historically, specifying the \fB+\fP \fIcommand\fP argument to the
edit command required a filename to be specified as well;
for example, \fB:edit\ +100\fP would always fail. For consistency
and simplicity of specification,
IEEE\ Std\ 1003.1-2001 does not permit this usage to fail for that
reason.
.LP
Historically, only the cursor position of the last file edited was
remembered by the editor. IEEE\ Std\ 1003.1-2001
requires that this be supported; however, implementations are permitted
to remember and restore the cursor position for any file
previously edited.
.SS File
.LP
Historical versions of the \fIex\fP editor \fBfile\fP command displayed
a current line and number of lines in the edit buffer
of 0 when the file was empty, while the \fIvi\fP <control>-G command
displayed a current
line and number of lines in the edit buffer of 1 in the same situation.
IEEE\ Std\ 1003.1-2001 does not permit this
discrepancy, instead requiring that a message be displayed indicating
that the file is empty.
.SS Global
.LP
The two-pass operation of the \fBglobal\fP and \fBv\fP commands is
not intended to imply implementation, only the required
result of the operation.
.LP
The current line and column are set as specified for the individual
\fIex\fP commands. This requirement is cumulative; that is,
the current line and column must track across all the commands executed
by the \fBglobal\fP or \fBv\fP commands.
.SS Insert
.LP
See the RATIONALE for the \fBappend\fP command.
.LP
Historically, \fBinsert\fP could not be used with an address of zero;
that is, not when the edit buffer was empty.
IEEE\ Std\ 1003.1-2001 requires that this command behave consistently
with the \fBappend\fP command.
.SS Join
.LP
The action of the \fBjoin\fP command in relation to the special characters
is only defined for the POSIX locale because the
correct amount of white space after a period varies; in Japanese none
is required, in French only a single space, and so on.
.SS List
.LP
The historical output of the \fBlist\fP command was potentially ambiguous.
The standard developers believed correcting this to
be more important than adhering to historical practice, and IEEE\ Std\ 1003.1-2001
requires unambiguous output.
.SS Map
.LP
Historically, command mode maps only applied to command names; for
example, if the character \fB'x'\fP was mapped to
\fB'y'\fP , the command \fBfx\fP searched for the \fB'x'\fP character,
not the \fB'y'\fP character.
IEEE\ Std\ 1003.1-2001 requires this behavior. Historically, entering
<control>-V as the first character of a \fIvi\fP command was an error.
Several implementations have extended the semantics of \fIvi\fP such
that <control>-V means that the subsequent command character is not
mapped. This is
permitted, but not required, by IEEE\ Std\ 1003.1-2001. Regardless,
using <control>-V to escape the second or later
character in a sequence of characters that might match a \fBmap\fP
command, or any character in text input mode, is historical
practice, and stops the entered keys from matching a map. IEEE\ Std\ 1003.1-2001
requires conformance to historical
practice.
.LP
Historical implementations permitted digits to be used as a \fBmap\fP
command \fIlhs\fP, but then ignored the map.
IEEE\ Std\ 1003.1-2001 requires that the mapped digits not be ignored.
.LP
The historical implementation of the \fBmap\fP command did not permit
\fBmap\fP commands that were more than a single
character in length if the first character was printable. This behavior
is permitted, but not required, by
IEEE\ Std\ 1003.1-2001.
.LP
Historically, mapped characters were remapped unless the \fBremap\fP
edit option was not set, or the prefix of the mapped
characters matched the mapping characters; for example, in the \fBmap\fP:
.sp
.RS
.nf

\fB:map ab abcd
\fP
.fi
.RE
.LP
the characters \fB"ab"\fP were used as is and were not remapped, but
the characters \fB"cd"\fP were mapped if appropriate.
This can cause infinite loops in the \fIvi\fP mapping mechanisms.
IEEE\ Std\ 1003.1-2001 requires conformance to historical practice,
and that such loops be interruptible.
.LP
Text input maps had the same problems with expanding the \fIlhs\fP
for the \fIex\fP \fBmap!\fP and \fBunmap!\fP command as
did the \fIex\fP \fBabbreviate\fP and \fBunabbreviate\fP commands.
See the RATIONALE for the \fIex\fP \fBabbreviate\fP
command. IEEE\ Std\ 1003.1-2001 requires similar modification of some
historical practice for the \fBmap\fP and
\fBunmap\fP commands, as described for the \fBabbreviate\fP and \fBunabbreviate\fP
commands.
.LP
Historically, \fBmap\fPs that were subsets of other \fBmap\fPs behaved
differently depending on the order in which they were
defined. For example:
.sp
.RS
.nf

\fB:map! ab     short
:map! abc    long
\fP
.fi
.RE
.LP
would always translate the characters \fB"ab"\fP to \fB"short"\fP
, regardless of how fast the characters \fB"abc"\fP
were entered. If the entry order was reversed:
.sp
.RS
.nf

\fB:map! abc    long
:map! ab     short
\fP
.fi
.RE
.LP
the characters \fB"ab"\fP would cause the editor to pause, waiting
for the completing \fB'c'\fP character, and the
characters might never be mapped to \fB"short"\fP . For consistency
and simplicity of specification,
IEEE\ Std\ 1003.1-2001 requires that the shortest match be used at
all times.
.LP
The length of time the editor spends waiting for the characters to
complete the \fIlhs\fP is unspecified because the timing
capabilities of systems are often inexact and variable, and it may
depend on other factors such as the speed of the connection. The
time should be long enough for the user to be able to complete the
sequence, but not long enough for the user to have to wait. Some
implementations of \fIvi\fP have added a \fBkeytime\fP option, which
permits users to set the
number of 0,1 seconds the editor waits for the completing characters.
Because mapped terminal function and cursor keys tend to
start with an <ESC> character, and <ESC> is the key ending \fIvi\fP
text input
mode, \fBmap\fPs starting with <ESC> characters are generally exempted
from this timeout period, or, at least timed out
differently.
.SS Mark
.LP
Historically, users were able to set the "previous context" marks
explicitly. In addition, the \fIex\fP commands \fB"\fP
and \fB'`\fP and the \fIvi\fP commands \fB"\fP, \fB``\fP, \fB`'\fP,
and \fB'`\fP all
referred to the same mark. In addition, the previous context marks
were not set if the command, with which the address setting the
mark was associated, failed. IEEE\ Std\ 1003.1-2001 requires conformance
to historical practice. Historically, if marked
lines were deleted, the mark was also deleted, but would reappear
if the change was undone. IEEE\ Std\ 1003.1-2001 requires
conformance to historical practice.
.LP
The description of the special events that set the \fB`\fP and \fB'\fP
marks matches historical practice. For example,
historically the command \fB/a/,/b/\fP did not set the \fB`\fP and
\fB'\fP marks, but the command \fB/a/,/b/delete\fP did.
.SS Next
.LP
Historically, any \fIex\fP command could be entered as a \fB+\fP \fIcommand\fP
argument to the \fBnext\fP command, although
some (for example, \fBinsert\fP and \fBappend\fP) were known to confuse
historical implementations.
IEEE\ Std\ 1003.1-2001 requires that any command be permitted and
that it behave as specified. The \fBnext\fP command can
accept more than one file, so usage such as:
.sp
.RS
.nf

\fBnext `ls [abc] `
\fP
.fi
.RE
.LP
is valid; it need not be valid for the \fBedit\fP or \fBread\fP commands,
for example, because they expect only one
filename.
.LP
Historically, the \fBnext\fP command behaved differently from the
\fB:rewind\fP command in that it ignored the force flag if
the \fBautowrite\fP flag was set. For consistency, IEEE\ Std\ 1003.1-2001
does not permit this behavior.
.LP
Historically, the \fBnext\fP command positioned the cursor as if the
file had never been edited before, regardless.
IEEE\ Std\ 1003.1-2001 does not permit this behavior, for consistency
with the \fBedit\fP command.
.LP
Implementations wanting to provide a counterpart to the \fBnext\fP
command that edited the previous file have used the command
\fBprev[ious],\fP which takes no \fIfile\fP argument. IEEE\ Std\ 1003.1-2001
does not require this command.
.SS Open
.LP
Historically, the \fBopen\fP command would fail if the \fBopen\fP
edit option was not set. IEEE\ Std\ 1003.1-2001 does
not mention the \fBopen\fP edit option and does not require this behavior.
Some historical implementations do not permit entering
open mode from open or visual mode, only from \fIex\fP mode. For consistency,
IEEE\ Std\ 1003.1-2001 does not permit this
behavior.
.LP
Historically, entering open mode from the command line (that is, \fIvi\fP
\fB+open\fP)
resulted in anomalous behaviors; for example, the \fIex\fP file and
\fIset\fP
commands, and the \fIvi\fP command <control>-G did not work. For consistency,
IEEE\ Std\ 1003.1-2001 does not permit this behavior.
.LP
Historically, the \fBopen\fP command only permitted \fB'/'\fP characters
to be used as the search pattern delimiter. For
consistency, IEEE\ Std\ 1003.1-2001 requires that the search delimiters
used by the \fBs\fP, \fBglobal\fP, and \fBv\fP
commands be accepted as well.
.SS Preserve
.LP
The \fBpreserve\fP command does not historically cause the file to
be considered unmodified for the purposes of future commands
that may exit the editor. IEEE\ Std\ 1003.1-2001 requires conformance
to historical practice.
.LP
Historical documentation stated that mail was not sent to the user
when preserve was executed; however, historical
implementations did send mail in this case. IEEE\ Std\ 1003.1-2001
requires conformance to the historical
implementations.
.SS Print
.LP
The writing of NUL by the \fBprint\fP command is not specified as
a special case because the standard developers did not want
to require \fIex\fP to support NUL characters. Historically, characters
were displayed using the ARPA standard mappings, which are
as follows:
.IP " 1." 4
Printable characters are left alone.
.LP
.IP " 2." 4
Control characters less than \\177 are represented as \fB'^'\fP followed
by the character offset from the \fB'@'\fP
character in the ASCII map; for example, \\007 is represented as \fB'^G'\fP
\&.
.LP
.IP " 3." 4
\\177 is represented as \fB'^'\fP followed by \fB'?'\fP .
.LP
.LP
The display of characters having their eighth bit set was less standard.
Existing implementations use hex (0x00), octal (\\000),
and a meta-bit display. (The latter displayed bytes that had their
eighth bit set as the two characters \fB"M-"\fP followed by
the seven-bit display as described above.) The latter probably has
the best claim to historical practice because it was used for
the \fB-v\fP option of 4 BSD and 4 BSD-derived versions of the \fIcat\fP
utility since
1980.
.LP
No specific display format is required by IEEE\ Std\ 1003.1-2001.
.LP
Explicit dependence on the ASCII character set has been avoided where
possible, hence the use of the phrase an
"implementation-defined multi-character sequence" for the display
of non-printable characters in preference to the historical
usage of, for instance, \fB"^I"\fP for the <tab>. Implementations
are encouraged to conform to historical practice in the
absence of any strong reason to diverge.
.LP
Historically, all \fIex\fP commands beginning with the letter \fB'p'\fP
could be entered using capitalized versions of the
commands; for example, \fBP[rint]\fP, \fBPre[serve]\fP, and \fBPu[t]\fP
were all valid command names.
IEEE\ Std\ 1003.1-2001 permits, but does not require, this historical
practice because capital forms of the commands are
used by some implementations for other purposes.
.SS Put
.LP
Historically, an \fIex\fP \fBput\fP command, executed from open or
visual mode, was the same as the open or visual mode
\fBP\fP command, if the buffer was named and was cut in character
mode, and the same as the \fBp\fP command if the buffer was
named and cut in line mode. If the unnamed buffer was the source of
the text, the entire line from which the text was taken was
usually \fBput\fP, and the buffer was handled as if in line mode,
but it was possible to get extremely anomalous behavior. In
addition, using the \fBQ\fP command to switch into \fIex\fP mode,
and then doing a \fBput\fP often resulted in errors as well,
such as appending text that was unrelated to the (supposed) contents
of the buffer. For consistency and simplicity of
specification, IEEE\ Std\ 1003.1-2001 does not permit these behaviors.
All \fIex\fP \fBput\fP commands are required to
operate in line mode, and the contents of the buffers are not altered
by changing the mode of the editor.
.SS Read
.LP
Historically, an \fIex\fP \fBread\fP command executed from open or
visual mode, executed in an empty file, left an empty line
as the first line of the file. For consistency and simplicity of specification,
IEEE\ Std\ 1003.1-2001 does not permit this
behavior. Historically, a \fBread\fP in open or visual mode from a
program left the cursor at the last line read in, not the
first. For consistency, IEEE\ Std\ 1003.1-2001 does not permit this
behavior.
.LP
Historical implementations of \fIex\fP were unable to undo \fBread\fP
commands that read from the output of a program. For
consistency, IEEE\ Std\ 1003.1-2001 does not permit this behavior.
.LP
Historically, the \fIex\fP and \fIvi\fP message after a successful
\fBread\fP or
\fBwrite\fP command specified "characters", not "bytes". IEEE\ Std\ 1003.1-2001
requires that the number of bytes be
displayed, not the number of characters, because it may be difficult
in multi-byte implementations to determine the number of
characters read. Implementations are encouraged to clarify the message
displayed to the user.
.LP
Historically, reads were not permitted on files other than type regular,
except that FIFO files could be read (probably only
because they did not exist when \fIex\fP and \fIvi\fP were originally
written). Because the
historical \fIex\fP evaluated \fBread!\fP and \fBread\ !\fP equivalently,
there can be no optional way to force the read.
IEEE\ Std\ 1003.1-2001 permits, but does not require, this behavior.
.SS Recover
.LP
Some historical implementations of the editor permitted users to recover
the edit buffer contents from a previous edit session,
and then exit without saving those contents (or explicitly discarding
them). The intent of IEEE\ Std\ 1003.1-2001 in
requiring that the edit buffer be treated as already modified is to
prevent this user error.
.SS Rewind
.LP
Historical implementations supported the \fBrewind\fP command when
the user was editing the first file in the list; that is,
the file that the \fBrewind\fP command would edit. IEEE\ Std\ 1003.1-2001
requires conformance to historical practice.
.SS Substitute
.LP
Historically, \fIex\fP accepted an \fBr\fP option to the \fBs\fP command.
The effect of the \fBr\fP option was to use the
last regular expression used in any command as the pattern, the same
as the \fB~\fP command. The \fBr\fP option is not
required by IEEE\ Std\ 1003.1-2001. Historically, the \fBc\fP and
\fBg\fP options were toggled; for example, the command
\fB:s/abc/def/\fP was the same as \fBs/abc/def/ccccgggg\fP. For simplicity
of specification, IEEE\ Std\ 1003.1-2001 does
not permit this behavior.
.LP
The tilde command is often used to replace the last search RE. For
example, in the sequence:
.sp
.RS
.nf

\fBs/red/blue/
/green
~
\fP
.fi
.RE
.LP
the \fB~\fP command is equivalent to:
.sp
.RS
.nf

\fBs/green/blue/
\fP
.fi
.RE
.LP
Historically, \fIex\fP accepted all of the following forms:
.sp
.RS
.nf

\fBs/abc/def/
s/abc/def
s/abc/
s/abc
\fP
.fi
.RE
.LP
IEEE\ Std\ 1003.1-2001 requires conformance to this historical practice.
.LP
The \fBs\fP command presumes that the \fB'^'\fP character only occupies
a single column in the display. Much of the
\fIex\fP and \fIvi\fP specification presumes that the <space> only
occupies a single
column in the display. There are no known character sets for which
this is not true.
.LP
Historically, the final column position for the substitute commands
was based on previous column movements; a search for a
pattern followed by a substitution would leave the column position
unchanged, while a 0 command followed by a substitution would
change the column position to the first non- <blank>. For consistency
and simplicity of specification,
IEEE\ Std\ 1003.1-2001 requires that the final column position always
be set to the first non- <blank>.
.SS Set
.LP
Historical implementations redisplayed all of the options for each
occurrence of the \fBall\fP keyword.
IEEE\ Std\ 1003.1-2001 permits, but does not require, this behavior.
.SS Tag
.LP
No requirement is made as to where \fIex\fP and \fIvi\fP shall look
for the file referenced
by the tag entry. Historical practice has been to look for the path
found in the \fBtags\fP file, based on the current directory.
A useful extension found in some implementations is to look based
on the directory containing the tags file that held the entry, as
well. No requirement is made as to which reference for the tag in
the tags file is used. This is deliberate, in order to permit
extensions such as multiple entries in a tags file for a tag.
.LP
Because users often specify many different tags files, some of which
need not be relevant or exist at any particular time,
IEEE\ Std\ 1003.1-2001 requires that error messages about problem
tags files be displayed only if the requested tag is not
found, and then, only once for each time that the \fBtag\fP edit option
is changed.
.LP
The requirement that the current edit buffer be unmodified is only
necessary if the file indicated by the tag entry is not the
same as the current file (as defined by the current pathname). Historically,
the file would be reloaded if the filename had
changed, as well as if the filename was different from the current
pathname. For consistency and simplicity of specification,
IEEE\ Std\ 1003.1-2001 does not permit this behavior, requiring that
the name be the only factor in the decision.
.LP
Historically, \fIvi\fP only searched for tags in the current file
from the current cursor to
the end of the file, and therefore, if the \fBwrapscan\fP option was
not set, tags occurring before the current cursor were not
found. IEEE\ Std\ 1003.1-2001 considers this a bug, and implementations
are required to search for the first occurrence in
the file, regardless.
.SS Undo
.LP
The \fBundo\fP description deliberately uses the word "modified".
The \fBundo\fP command is not intended to undo commands
that replace the contents of the edit buffer, such as \fBedit\fP,
\fBnext\fP, \fBtag\fP, or \fBrecover\fP.
.LP
Cursor positioning after the \fBundo\fP command was inconsistent in
the historical \fIvi\fP, sometimes attempting to restore the original
cursor position ( \fBglobal\fP, \fBundo\fP,
and \fBv\fP commands), and sometimes, in the presence of maps, placing
the cursor on the last line added or changed instead of the
first. IEEE\ Std\ 1003.1-2001 requires a simplified behavior for consistency
and simplicity of specification.
.SS Version
.LP
The \fBversion\fP command cannot be exactly specified since there
is no widely-accepted definition of what the version
information should contain. Implementations are encouraged to do something
reasonably intelligent.
.SS Write
.LP
Historically, the \fIex\fP and \fIvi\fP message after a successful
\fBread\fP or
\fBwrite\fP command specified "characters", not "bytes". IEEE\ Std\ 1003.1-2001
requires that the number of bytes be
displayed, not the number of characters because it may be difficult
in multi-byte implementations to determine the number of
characters written. Implementations are encouraged to clarify the
message displayed to the user.
.LP
Implementation-defined tests are permitted so that implementations
can make additional checks; for example, for locks or file
modification times.
.LP
Historically, attempting to append to a nonexistent file caused an
error. It has been left unspecified in
IEEE\ Std\ 1003.1-2001 to permit implementations to let the \fBwrite\fP
succeed, so that the append semantics are similar
to those of the historical \fIcsh\fP.
.LP
Historical \fIvi\fP permitted empty edit buffers to be written. However,
since the way \fIvi\fP got around dealing with "empty" files was to
always have a line in the edit buffer, no
matter what, it wrote them as files of a single, empty line. IEEE\ Std\ 1003.1-2001
does not permit this behavior.
.LP
Historically, \fIex\fP restored standard output and standard error
to their values as of when \fIex\fP was invoked, before
writes to programs were performed. This could disturb the terminal
configuration as well as be a security issue for some terminals.
IEEE\ Std\ 1003.1-2001 does not permit this, requiring that the program
output be captured and displayed as if by the
\fIex\fP \fBprint\fP command.
.SS Adjust Window
.LP
Historically, the line count was set to the value of the \fBscroll\fP
option if the type character was end-of-file. This
feature was broken on most historical implementations long ago, however,
and is not documented anywhere. For this reason,
IEEE\ Std\ 1003.1-2001 is resolutely silent.
.LP
Historically, the \fBz\fP command was <blank>-sensitive and \fBz\ +\fP
and \fBz\ -\fP did different things than
\fBz+\fP and \fBz-\fP because the type could not be distinguished
from a flag. (The commands \fBz\ .\fP and \fBz\ =\fP
were historically invalid.) IEEE\ Std\ 1003.1-2001 requires conformance
to this historical practice.
.LP
Historically, the \fBz\fP command was further <blank>-sensitive in
that the \fIcount\fP could not be
<blank>-delimited; for example, the commands \fBz=\ 5\fP and \fBz-\ 5\fP
were also invalid. Because the
\fIcount\fP is not ambiguous with respect to either the type character
or the flags, this is not permitted by
IEEE\ Std\ 1003.1-2001.
.SS Escape
.LP
Historically, \fIex\fP filter commands only read the standard output
of the commands, letting standard error appear on the
terminal as usual. The \fIvi\fP utility, however, read both standard
output and standard error.
IEEE\ Std\ 1003.1-2001 requires the latter behavior for both \fIex\fP
and \fIvi\fP,
for consistency.
.SS Shift Left and Shift Right
.LP
Historically, it was possible to add shift characters to increase
the effect of the command; for example, \fB<<<\fP
outdented (or \fB>>>\fP indented) the lines 3 levels of indentation
instead of the default 1.
IEEE\ Std\ 1003.1-2001 requires conformance to historical practice.
.SS <control>-D
.LP
Historically, the <control>-D command erased the prompt, providing
the user with an unbroken presentation of lines from
the edit buffer. This is not required by IEEE\ Std\ 1003.1-2001; implementations
are encouraged to provide it if possible.
Historically, the <control>-D command took, and then ignored, a \fIcount\fP.
IEEE\ Std\ 1003.1-2001 does not permit
this behavior.
.SS Write Line Number
.LP
Historically, the \fIex\fP \fB=\fP command, when executed in \fIex\fP
mode in an empty edit buffer, reported 0, and from open
or visual mode, reported 1. For consistency and simplicity of specification,
IEEE\ Std\ 1003.1-2001 does not permit this
behavior.
.SS Execute
.LP
Historically, \fIex\fP did not correctly handle the inclusion of text
input commands (that is, \fBappend\fP, \fBinsert\fP,
and \fBchange\fP) in executed buffers. IEEE\ Std\ 1003.1-2001 does
not permit this exclusion for consistency.
.LP
Historically, the logical contents of the buffer being executed did
not change if the buffer itself were modified by the
commands being executed; that is, buffer execution did not support
self-modifying code. IEEE\ Std\ 1003.1-2001 requires
conformance to historical practice.
.LP
Historically, the \fB@\fP command took a range of lines, and the \fB@\fP
buffer was executed once per line, with the current
line ( \fB'.'\fP ) set to each specified line. IEEE\ Std\ 1003.1-2001
requires conformance to historical practice.
.LP
Some historical implementations did not notice if errors occurred
during buffer execution. This, coupled with the ability to
specify a range of lines for the \fIex\fP \fB@\fP command, makes it
trivial to cause them to drop \fBcore\fP.
IEEE\ Std\ 1003.1-2001 requires that implementations stop buffer execution
if any error occurs, if the specified line
doesn't exist, or if the contents of the edit buffer itself are replaced
(for example, the buffer executes the \fIex\fP
\fB:edit\fP command).
.SS Regular Expressions in ex
.LP
Historical practice is that the characters in the replacement part
of the last \fBs\fP command-that is, those matched by
entering a \fB'~'\fP in the regular expression-were not further expanded
by the regular expression engine. So, if the
characters contained the string \fB"a.,"\fP they would match \fB'a'\fP
followed by \fB".,"\fP and not \fB'a'\fP
followed by any character. IEEE\ Std\ 1003.1-2001 requires conformance
to historical practice.
.SS Edit Options in ex
.LP
The following paragraphs describe the historical behavior of some
edit options that were not, for whatever reason, included in
IEEE\ Std\ 1003.1-2001. Implementations are strongly encouraged to
only use these names if the functionality described here
is fully supported.
.TP 7
\fBextended\fP
The \fBextended\fP edit option has been used in some implementations
of \fIvi\fP to
provide extended regular expressions instead of basic regular expressions
This option was omitted from
IEEE\ Std\ 1003.1-2001 because it is not widespread historical practice.
.TP 7
\fBflash\fP
The \fBflash\fP edit option historically caused the screen to flash
instead of beeping on error. This option was omitted from
IEEE\ Std\ 1003.1-2001 because it is not found in some historical
implementations.
.TP 7
\fBhardtabs\fP
The \fBhardtabs\fP edit option historically defined the number of
columns between hardware tab settings. This option was
omitted from IEEE\ Std\ 1003.1-2001 because it was believed to no
longer be generally useful.
.TP 7
\fBmodeline\fP
The \fBmodeline\fP (sometimes named \fBmodelines\fP) edit option historically
caused \fIex\fP or \fIvi\fP to read the five first and last lines
of the file for editor commands. This option is a
security problem, and vendors are strongly encouraged to delete it
from historical implementations.
.TP 7
\fBopen\fP
The \fBopen\fP edit option historically disallowed the \fIex\fP \fBopen\fP
and \fBvisual\fP commands. This edit option was
omitted because these commands are required by IEEE\ Std\ 1003.1-2001.
.TP 7
\fBoptimize\fP
The \fBoptimize\fP edit option historically expedited text throughput
by setting the terminal to not do automatic
<carriage-return>s when printing more than one logical line of output.
This option was omitted from
IEEE\ Std\ 1003.1-2001 because it was intended for terminals without
addressable cursors, which are rarely, if ever, still
used.
.TP 7
\fBruler\fP
The \fBruler\fP edit option has been used in some implementations
of \fIvi\fP to present a
current row/column ruler for the user. This option was omitted from
IEEE\ Std\ 1003.1-2001 because it is not widespread
historical practice.
.TP 7
\fBsourceany\fP
The \fBsourceany\fP edit option historically caused \fIex\fP or \fIvi\fP
to source
start-up files that were owned by users other than the user running
the editor. This option is a security problem, and vendors are
strongly encouraged to remove it from their implementations.
.TP 7
\fBtimeout\fP
The \fBtimeout\fP edit option historically enabled the (now standard)
feature of only waiting for a short period before
returning keys that could be part of a macro. This feature was omitted
from IEEE\ Std\ 1003.1-2001 because its behavior is
now standard, it is not widely useful, and it was rarely documented.
.TP 7
\fBverbose\fP
The \fBverbose\fP edit option has been used in some implementations
of \fIvi\fP to cause
\fIvi\fP to output error messages for common errors; for example,
attempting to move the cursor
past the beginning or end of the line instead of only alerting the
screen. (The historical \fIvi\fP only alerted the terminal and presented
no message for such errors. The historical editor
option \fBterse\fP did not select when to present error messages,
it only made existing error messages more or less verbose.) This
option was omitted from IEEE\ Std\ 1003.1-2001 because it is not widespread
historical practice; however, implementors are
encouraged to use it if they wish to provide error messages for naive
users.
.TP 7
\fBwraplen\fP
The \fBwraplen\fP edit option has been used in some implementations
of \fIvi\fP to specify
an automatic margin measured from the left margin instead of from
the right margin. This is useful when multiple screen sizes are
being used to edit a single file. This option was omitted from IEEE\ Std\ 1003.1-2001
because it is not widespread
historical practice; however, implementors are encouraged to use it
if they add this functionality.
.sp
.SS autoindent, ai
.LP
Historically, the command \fB0a\fP did not do any autoindentation,
regardless of the current indentation of line 1.
IEEE\ Std\ 1003.1-2001 requires that any indentation present in line
1 be used.
.SS autoprint, ap
.LP
Historically, the \fBautoprint\fP edit option was not completely consistent
or based solely on modifications to the edit
buffer. Exceptions were the \fBread\fP command (when reading from
a file, but not from a filter), the \fBappend\fP,
\fBchange\fP, \fBinsert\fP, \fBglobal\fP, and \fBv\fP commands, all
of which were not affected by \fBautoprint\fP, and the
\fBtag\fP command, which was affected by \fBautoprint\fP. IEEE\ Std\ 1003.1-2001
requires conformance to historical
practice.
.LP
Historically, the \fBautoprint\fP option only applied to the last
of multiple commands entered using vertical-bar delimiters;
for example, \fBdelete\fP <newline> was affected by \fBautoprint\fP,
but \fBdelete|version\fP <newline> was not.
IEEE\ Std\ 1003.1-2001 requires conformance to historical practice.
.SS autowrite, aw
.LP
Appending the \fB'!'\fP character to the \fIex\fP \fBnext\fP command
to avoid performing an automatic write was not
supported in historical implementations. IEEE\ Std\ 1003.1-2001 requires
that the behavior match the other \fIex\fP
commands for consistency.
.SS ignorecase, ic
.LP
Historical implementations of case-insensitive matching (the \fBignorecase\fP
edit option) lead to counterintuitive situations
when uppercase characters were used in range expressions. Historically,
the process was as follows:
.IP " 1." 4
Take a line of text from the edit buffer.
.LP
.IP " 2." 4
Convert uppercase to lowercase in text line.
.LP
.IP " 3." 4
Convert uppercase to lowercase in regular expressions, except in character
class specifications.
.LP
.IP " 4." 4
Match regular expressions against text.
.LP
.LP
This would mean that, with \fBignorecase\fP in effect, the text:
.sp
.RS
.nf

\fBThe cat sat on the mat
\fP
.fi
.RE
.LP
would be matched by
.sp
.RS
.nf

\fB/^the/
\fP
.fi
.RE
.LP
but not by:
.sp
.RS
.nf

\fB/^[A-Z]he/
\fP
.fi
.RE
.LP
For consistency with other commands implementing regular expressions,
IEEE\ Std\ 1003.1-2001 does not permit this
behavior.
.SS paragraphs, para
.LP
The ISO\ POSIX-2:1993 standard made the default \fBparagraphs\fP and
\fBsections\fP edit options implementation-defined,
arguing they were historically oriented to the UNIX system \fItroff\fP
text formatter, and a "portable user" could use the
\fB{\fP, \fB}\fP, \fB[[\fP, \fB]]\fP, \fB(\fP, and \fB)\fP commands
in open or visual mode and have the cursor stop in
unexpected places. IEEE\ Std\ 1003.1-2001 specifies their values in
the POSIX locale because the unusual grouping (they
only work when grouped into two characters at a time) means that they
cannot be used for general-purpose movement, regardless.
.SS readonly
.LP
Implementations are encouraged to provide the best possible information
to the user as to the read-only status of the file, with
the exception that they should not consider the current special privileges
of the process. This provides users with a safety net
because they must force the overwrite of read-only files, even when
running with additional privileges.
.LP
The \fBreadonly\fP edit option specification largely conforms to historical
practice. The only difference is that historical
implementations did not notice that the user had set the \fBreadonly\fP
edit option in cases where the file was already marked
read-only for some reason, and would therefore reinitialize the \fBreadonly\fP
edit option the next time the contents of the edit
buffer were replaced. This behavior is disallowed by IEEE\ Std\ 1003.1-2001.
.SS report
.LP
The requirement that lines copied to a buffer interact differently
than deleted lines is historical practice. For example, if
the \fBreport\fP edit option is set to 3, deleting 3 lines will cause
a report to be written, but 4 lines must be copied before a
report is written.
.LP
The requirement that the \fIex\fP \fBglobal\fP, \fBv\fP, \fBopen\fP,
\fBundo\fP, and \fBvisual\fP commands present reports
based on the total number of lines added or deleted during the command
execution, and that commands executed by the \fBglobal\fP
and \fBv\fP commands not present reports, is historical practice.
IEEE\ Std\ 1003.1-2001 extends historical practice by
requiring that buffer execution be treated similarly. The reasons
for this are two-fold. Historically, only the report by the last
command executed from the buffer would be seen by the user, as each
new report would overwrite the last. In addition, the standard
developers believed that buffer execution had more in common with
\fBglobal\fP and \fBv\fP commands than it did with other
\fIex\fP commands, and should behave similarly, for consistency and
simplicity of specification.
.SS showmatch, sm
.LP
The length of time the cursor spends on the matching character is
unspecified because the timing capabilities of systems are
often inexact and variable. The time should be long enough for the
user to notice, but not long enough for the user to become
annoyed. Some implementations of \fIvi\fP have added a \fBmatchtime\fP
option that permits
users to set the number of 0,1 second intervals the cursor pauses
on the matching character.
.SS showmode
.LP
The \fBshowmode\fP option has been used in some historical implementations
of \fIex\fP and \fIvi\fP to display the current editing mode when
in open or visual mode. The editing modes have
generally included "command" and "input", and sometimes other modes
such as "replace" and "change". The string was usually
displayed on the bottom line of the screen at the far right-hand corner.
In addition, a preceding \fB'*'\fP character often
denoted whether the contents of the edit buffer had been modified.
The latter display has sometimes been part of the
\fBshowmode\fP option, and sometimes based on another option. This
option was not available in the 4 BSD historical implementation
of \fIvi\fP, but was viewed as generally useful, particularly to novice
users, and is required
by IEEE\ Std\ 1003.1-2001.
.LP
The \fBsmd\fP shorthand for the \fBshowmode\fP option was not present
in all historical implementations of the editor.
IEEE\ Std\ 1003.1-2001 requires it, for consistency.
.LP
Not all historical implementations of the editor displayed a mode
string for command mode, differentiating command mode from
text input mode by the absence of a mode string. IEEE\ Std\ 1003.1-2001
permits this behavior for consistency with
historical practice, but implementations are encouraged to provide
a display string for both modes.
.SS slowopen
.LP
Historically the \fBslowopen\fP option was automatically set if the
terminal baud rate was less than 1200 baud, or if the baud
rate was 1200 baud and the \fBredraw\fP option was not set. The \fBslowopen\fP
option had two effects. First, when inserting
characters in the middle of a line, characters after the cursor would
not be pushed ahead, but would appear to be overwritten.
Second, when creating a new line of text, lines after the current
line would not be scrolled down, but would appear to be
overwritten. In both cases, ending text input mode would cause the
screen to be refreshed to match the actual contents of the edit
buffer. Finally, terminals that were sufficiently intelligent caused
the editor to ignore the \fBslowopen\fP option.
IEEE\ Std\ 1003.1-2001 permits most historical behavior, extending
historical practice to require \fBslowopen\fP behaviors
if the edit option is set by the user.
.SS tags
.LP
The default path for tags files is left unspecified as implementations
may have their own \fBtags\fP implementations that do
not correspond to the historical ones. The default \fBtags\fP option
value should probably at least include the file
\fB\&./tags\fP.
.SS term
.LP
Historical implementations of \fIex\fP and \fIvi\fP ignored changes
to the \fBterm\fP edit
option after the initial terminal information was loaded. This is
permitted by IEEE\ Std\ 1003.1-2001; however,
implementations are encouraged to permit the user to modify their
terminal type at any time.
.SS terse
.LP
Historically, the \fBterse\fP edit option optionally provided a shorter,
less descriptive error message, for some error
messages. This is permitted, but not required, by IEEE\ Std\ 1003.1-2001.
Historically, most common visual mode errors (for
example, trying to move the cursor past the end of a line) did not
result in an error message, but simply alerted the terminal.
Implementations wishing to provide messages for novice users are urged
to do so based on the \fBedit\fP option \fBverbose\fP, and
not \fBterse\fP.
.SS window
.LP
In historical implementations, the default for the \fBwindow\fP edit
option was based on the baud rate as follows:
.IP " 1." 4
If the baud rate was less than 1200, the \fBedit\fP option \fBw300\fP
set the window value; for example, the line:
.sp
.RS
.nf

\fBset w300=12
\fP
.fi
.RE
.LP
would set the window option to 12 if the baud rate was less than 1200.
.LP
.IP " 2." 4
If the baud rate was equal to 1200, the \fBedit\fP option \fBw1200\fP
set the window value.
.LP
.IP " 3." 4
If the baud rate was greater than 1200, the \fBedit\fP option \fBw9600\fP
set the window value.
.LP
.LP
The \fBw300\fP, \fBw1200\fP, and \fBw9600\fP options do not appear
in IEEE\ Std\ 1003.1-2001 because of their
dependence on specific baud rates.
.LP
In historical implementations, the size of the window displayed by
various commands was related to, but not necessarily the same
as, the \fBwindow\fP edit option. For example, the size of the window
was set by the \fIex\fP command \fBvisual 10\fP, but it
did not change the value of the \fBwindow\fP edit option. However,
changing the value of the \fBwindow\fP edit option did change
the number of lines that were displayed when the screen was repainted.
IEEE\ Std\ 1003.1-2001 does not permit this behavior
in the interests of consistency and simplicity of specification, and
requires that all commands that change the number of lines
that are displayed do it by setting the value of the \fBwindow\fP
edit option.
.SS wrapmargin, wm
.LP
Historically, the \fBwrapmargin\fP option did not affect maps inserting
characters that also had associated \fIcount\fPs; for
example \fB:map\ K\ 5aABC\ DEF\fP. Unfortunately, there are widely
used maps that depend on this behavior. For
consistency and simplicity of specification, IEEE\ Std\ 1003.1-2001
does not permit this behavior.
.LP
Historically, \fBwrapmargin\fP was calculated using the column display
width of all characters on the screen. For example, an
implementation using \fB"^I"\fP to represent <tab>s when the \fBlist\fP
edit option was set, where \fB'^'\fP and
\fB'I'\fP each took up a single column on the screen, would calculate
the \fBwrapmargin\fP based on a value of 2 for each
<tab>. The \fBnumber\fP edit option similarly changed the effective
length of the line as well.
IEEE\ Std\ 1003.1-2001 requires conformance to historical practice.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fICommand Search and Execution\fP , \fIctags\fP , \fIed\fP , \fIsed\fP
, \fIsh\fP , \fIstty\fP , \fIvi\fP , the System Interfaces volume
of IEEE\ Std\ 1003.1-2001, \fIaccess\fP()
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .