'\" et
.TH EX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.

.SH NAME
ex
\(em text editor
.SH SYNOPSIS
.LP
.nf
ex \fB[\fR\(mirR\fB] [\fR\(mis|\(miv\fB] [\fR\(mic \fIcommand\fB] [\fR\(mit \fItagstring\fB] [\fR\(miw \fIsize\fB] [\fIfile\fR...\fB]\fR
.fi
.SH DESCRIPTION
The
.IR ex
utility is a line-oriented text editor. There are two other modes of
the editor\(emopen and visual\(emin which screen-oriented editing is
available. This is described more fully by the
.IR ex
.BR open
and
.BR visual
commands and in
.IR "\fIvi\fR\^".
.P
If an operand is
.BR '\(mi' ,
the results are unspecified.
.P
This section uses the term
.IR "edit buffer"
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.
.P
Certain terminals do not have all the capabilities necessary to support
the complete
.IR ex
definition, such as the full-screen editing commands (\c
.IR "visual mode"
or
.IR "open mode" ).
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 POSIX.1\(hy2008 or
report an error describing the terminal-related deficiency.
.SH OPTIONS
The
.IR ex
utility shall conform to the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 12.2" ", " "Utility Syntax Guidelines",
except for the unspecified usage of
.BR '\(mi' ,
and that
.BR '\(pl' 
may be recognized as an option delimiter as well as
.BR '\(mi' .
.P
The following options shall be supported:
.IP "\fB\(mic\ \fIcommand\fR" 10
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
.BR \(mic
option. In such implementations, the specified commands shall be
executed in the order specified on the command line.
.IP "\fB\(mir\fP" 10
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
.IR ex
.BR preserve
command.
.RS 10 
.P
A
.IR crash
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
.BR preserve
command) that will be recovered is unspecified.
.P
If no
.IR file
operands are given and the
.BR \(mit
option is not specified, all other options, the
.IR EXINIT
variable, and any
.BR .exrc
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.
.RE
.IP "\fB\(miR\fP" 10
Set
.BR readonly
edit option.
.IP "\fB\(mis\fP" 10
Prepare
.IR ex
for batch use by taking the following actions:
.RS 10 
.IP " *" 4
Suppress writing prompts and informational (but not diagnostic)
messages.
.IP " *" 4
Ignore the value of
.IR TERM
and any implementation default terminal type and assume the terminal is
a type incapable of supporting open or visual modes; see the
.BR visual
command and the description of
.IR "\fIvi\fR\^".
.IP " *" 4
Suppress the use of the
.IR EXINIT
environment variable and the reading of any
.BR .exrc
file; see the EXTENDED DESCRIPTION section.
.IP " *" 4
Suppress autoindentation, ignoring the value of the
.BR autoindent
edit option.
.RE
.IP "\fB\(mit\ \fItagstring\fR" 10
Edit the file containing the specified
.IR tagstring ;
see
.IR "\fIctags\fR\^".
The tags feature represented by
.BR \(mit
.IR tagstring
and the
.BR tag
command is optional. It shall be provided on any system that also
provides a conforming implementation of
.IR ctags ;
otherwise, the use of
.BR \(mit
produces undefined results. On any system, it shall be an error to
specify more than a single
.BR \(mit
option.
.IP "\fB\(miv\fP" 10
Begin in visual mode (see
.IR "\fIvi\fR\^").
.IP "\fB\(miw\ \fIsize\fR" 10
Set the value of the
.IR window
editor option to
.IR size .
.SH OPERANDS
The following operand shall be supported:
.IP "\fIfile\fR" 10
A pathname of a file to be edited.
.SH STDIN
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}.
.P
If the standard input is not a terminal device, it shall be as if the
.BR \(mis
option had been specified.
.P
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"
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}\(mi1
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
.IR ex
implementations.
.P
The
.BR .exrc
files and source files shall be text files consisting of
.IR ex
commands; see the EXTENDED DESCRIPTION section.
.P
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"
The following environment variables shall affect the execution of
.IR ex :
.IP "\fICOLUMNS\fP" 10
Override the system-selected horizontal screen size. See the Base Definitions volume of POSIX.1\(hy2008,
.IR "Chapter 8" ", " "Environment Variables"
for valid values and results when it is unset or null.
.IP "\fIEXINIT\fP" 10
Determine a list of
.IR ex
commands that are executed on editor start-up. See the EXTENDED
DESCRIPTION section for more details of the initialization phase.
.IP "\fIHOME\fP" 10
Determine a pathname of a directory that shall be searched for an
editor start-up file named
.BR .exrc ;
see the EXTENDED DESCRIPTION section.
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 8.2" ", " "Internationalization Variables"
for the precedence of internationalization variables used to determine
the values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_COLLATE\fP" 10
.br
Determine the locale for the behavior of ranges, equivalence classes,
and multi-character collating elements within regular expressions.
.IP "\fILC_CTYPE\fP" 10
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.
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error.
.IP "\fILINES\fP" 10
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 POSIX.1\(hy2008,
.IR "Chapter 8" ", " "Environment Variables"
for valid values and results when it is unset or null.
.IP "\fINLSPATH\fP" 10
Determine the location of message catalogs for the processing of
.IR LC_MESSAGES .
.IP "\fIPATH\fP" 10
Determine the search path for the shell command specified in the
.IR ex
editor commands
.BR ! ,
.BR shell ,
.BR read ,
and
.BR write ,
and the open and visual mode command
.BR ! ;
see the description of command search and execution in
.IR "Section 2.9.1.1" ", " "Command Search and Execution".
.IP "\fISHELL\fP" 10
Determine the preferred command line interpreter for use as the default
value of the
.BR shell
edit option.
.IP "\fITERM\fP" 10
Determine the name of the terminal type. If this variable is unset or
null, an unspecified default terminal type shall be used.
.SH "ASYNCHRONOUS EVENTS"
The following term is used in this and following sections to specify
command and asynchronous event actions:
.IP "\fIcomplete\ write\fP" 10
.br
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
.IR ex
.BR preserve
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.
.P
The following actions shall be taken upon receipt of signals:
.IP SIGINT 10
If the standard input is not a terminal device,
.IR ex
shall not write the file or return to command or text input mode, and
shall exit with a non-zero exit status.
.RS 10 
.P
Otherwise, if executing an open or visual text input mode command,
.IR ex
in receipt of SIGINT shall behave identically to its receipt of the
<ESC>
character.
.P
Otherwise:
.IP " 1." 4
If executing an
.IR ex
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.
.IP " 2." 4
If there is a currently executing command, it shall be aborted and a
message displayed. Unless otherwise specified by the
.IR ex
or
.IR vi
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.
.RS 4 
.P
If the currently executing command was a motion command, its associated
command shall be discarded.
.RE
.IP " 3." 4
If in open or visual command mode, the terminal shall be alerted.
.IP " 4." 4
The editor shall then return to command mode.
.RE
.IP SIGCONT 10
The screen shall be refreshed if in open or visual mode.
.IP SIGHUP 10
If the edit buffer has been modified since the last complete write,
.IR ex
shall attempt to save the edit buffer so that it can be recovered later
using the
.BR \(mir
option or the
.IR ex
.BR recover
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.
.IP SIGTERM 10
Refer to SIGHUP.
.P
The action taken for all other signals is unspecified.
.SH STDOUT
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
The standard error shall be used only for diagnostic messages.
.SH "OUTPUT FILES"
The output from
.IR ex
shall be text files.
.SH "EXTENDED DESCRIPTION"
Only the
.IR ex
mode of the editor is described in this section. See
.IR "\fIvi\fR\^"
for additional editing capabilities available in
.IR ex .
.P
When an error occurs,
.IR ex
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
.BR errorbells
is set, an alert action shall precede the error message.
.P
By default,
.IR ex
shall start in command mode, which shall be indicated by a
.BR :
prompt; see the
.BR prompt
command. Text input mode can be entered by the
.BR append ,
.BR insert ,
or
.BR change
commands; it can be exited (and command mode re-entered) by typing a
<period>
(\c
.BR '.' )
alone at the beginning of a line.
.SS "Initialization in ex and vi"
.P
The following symbols are used in this and following sections to
specify locations in the edit buffer:
.IP "\fIalternate\ and\ current\ pathnames\fP" 6
.br
Two pathnames, named
.IR current
and
.IR alternate ,
are maintained by the editor. Any
.IR ex
commands that take filenames as arguments shall set them as follows:
.RS 6 
.IP " 1." 4
If a
.IR file
argument is specified to the
.IR ex
.BR edit ,
.BR ex ,
or
.BR recover
commands, or if an
.IR ex
.BR tag
command replaces the contents of the edit buffer.
.RS 4 
.IP " a." 4
If the command replaces the contents of the edit buffer, the current
pathname shall be set to the
.IR file
argument or the file indicated by the tag, and the alternate pathname
shall be set to the previous value of the current pathname.
.IP " b." 4
Otherwise, the alternate pathname shall be set to the
.IR file
argument.
.RE
.IP " 2." 4
If a
.IR file
argument is specified to the
.IR ex
.BR next
command:
.RS 4 
.IP " a." 4
If the command replaces the contents of the edit buffer, the current
pathname shall be set to the first
.IR file
argument, and the alternate pathname shall be set to the previous
value of the current pathname.
.RE
.IP " 3." 4
If a
.IR file
argument is specified to the
.IR ex
.BR file
command, the current pathname shall be set to the
.IR file
argument, and the alternate pathname shall be set to the previous
value of the current pathname.
.IP " 4." 4
If a
.IR file
argument is specified to the
.IR ex
.BR read
and
.BR write
commands (that is, when reading or writing a file, and not to the
program named by the
.BR shell
edit option), or a
.IR file
argument is specified to the
.IR ex
.BR xit
command:
.RS 4 
.IP " a." 4
If the current pathname has no value, the current pathname shall be
set to the
.IR file
argument.
.IP " b." 4
Otherwise, the alternate pathname shall be set to the
.IR file
argument.
.RE
.P
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.
.RE
.IP "\fIcurrent\ line\fP" 6
.br
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
.IR "current line value" .
When the edit buffer contains no lines, the current line shall be zero;
see
.IR "Addressing in ex".
.IP "\fIcurrent\ column\fP" 6
.br
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
.IR "current column"
value. This column is an
.IR ideal
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
.IR "Command Descriptions in vi".
.IP "\fIset\ to\ non-<blank>\fP" 6
.br
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-\c
<blank>
of the line. If the line has no non-\c
<blank>
non-\c
<newline>
characters, the current column shall be set to the last display line
column on which is displayed any part of the last non-\c
<newline>
character in the line. If the line is empty, the current column shall
be set to column position 1.
.P
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.
.P
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.
.P
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
.IR EXINIT
is set, the editor shall execute the
.IR ex
commands contained in that variable.
.IP " 2." 4
If the
.IR EXINIT
variable is not set, and all of the following are true:
.RS 4 
.IP " a." 4
The
.IR HOME
environment variable is not null and not empty.
.IP " b." 4
The file
.BR .exrc
in the directory referred to by the
.IR HOME
environment variable:
.RS 4 
.IP " i." 5
Exists
.IP ii. 5
Is owned by the same user ID as the real user ID of the process or the
process has appropriate privileges
.IP iii. 5
Is not writable by anyone other than the owner
.RE
.P
the editor shall execute the
.IR ex
commands contained in that file.
.RE
.IP " 3." 4
If and only if all of the following are true:
.RS 4 
.IP " a." 4
The current directory is not referred to by the
.IR HOME
environment variable.
.IP " b." 4
A command in the
.IR EXINIT
environment variable or a command in the
.BR .exrc
file in the directory referred to by the
.IR HOME
environment variable sets the editor option
.BR exrc .
.IP " c." 4
The
.BR .exrc
file in the current directory:
.RS 4 
.IP " i." 5
Exists
.IP ii. 5
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
.IP iii. 5
Is not writable by anyone other than the owner
.RE
.P
the editor shall attempt to execute the
.IR ex
commands contained in that file.
.RE
.P
Lines in any
.BR .exrc
file that are blank lines shall be ignored. If any
.BR .exrc
file exists, but is not read for ownership or permission reasons, it
shall be an error.
.P
After the
.IR EXINIT
variable and any
.BR .exrc
files are processed, the first file specified by the user shall be
edited, as follows:
.IP " 1." 4
If the user specified the
.BR \(mit
option, the effect shall be as if the
.IR ex
.BR tag
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.
.IP " 2." 4
Otherwise, if the user specified any command line
.IR file
arguments, the effect shall be as if the
.IR ex
.BR edit
command was entered with the first of those arguments as its
.IR file
argument.
.IP " 3." 4
Otherwise, the effect shall be as if the
.IR ex
.BR edit
command was entered with a nonexistent filename as its
.IR file
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.
.P
If the
.BR \(mir
option was specified, the first time a file in the initial argument
list or a file specified by the
.BR \(mit
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.
.P
If the
.BR \(mic
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
.BR \(mir
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-\c
<blank>,
and the
.IR ex
commands specified with the
.BR \(mic
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
.BR \(mit
option or a
.BR tag
command is associated with this action, the
.BR \(mic
option commands shall be executed and then the movement to the tag
shall be performed.
.P
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
.BR \(mit
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
.IR ex
.BR next
command shall edit the first filename from the command line). If the
.BR \(mit
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"
.P
Addressing in
.IR ex
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.
.P
Addresses are constructed as follows:
.IP " 1." 4
The character
.BR '.' 
(period) shall address the current line.
.IP " 2." 4
The character
.BR '$' 
shall address the last line of the edit buffer.
.IP " 3." 4
The positive decimal number
.IR n
shall address the
.IR n th
line of the edit buffer.
.IP " 4." 4
The address
.BR \(dq'x\(dq 
refers to the line marked with the mark name character
.BR 'x' ,
which shall be a lowercase letter from the portable character set,
the backquote character, or the single-quote character. 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
.IR ex
.BR mark
or
.BR k
commands, or the
.IR vi
.BR m
command.
.IP " 5." 4
A regular expression enclosed by
<slash>
characters (\c
.BR '/' )
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
.IR "Regular Expressions in ex",
an address consisting of a null regular expression delimited by
<slash>
characters (\c
.BR \(dq//\(dq )
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
.BR wrapscan
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
.BR \(dq\e/\(dq 
shall represent a literal
<slash>
instead of the regular expression delimiter.
.IP " 6." 4
A regular expression enclosed in
<question-mark>
characters (\c
.BR '?' )
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-mark>
characters (\c
.BR \(dq??\(dq )
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
.BR wrapscan
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
.BR \(dq\e?\(dq 
shall represent a literal
<question-mark>
instead of the RE delimiter.
.IP " 7." 4
A
<plus-sign>
(\c
.BR '\(pl' )
or a minus-sign (\c
.BR '\(mi' )
followed by a decimal number shall address the current line plus or
minus the number. A
.BR '\(pl' 
or
.BR '\(mi' 
not followed by a decimal number shall address the current line plus or
minus 1.
.P
Addresses can be followed by zero or more address offsets, optionally
<blank>-separated.
Address offsets are constructed as follows:
.IP " 1." 4
A
.BR '\(pl' 
or
.BR '\(mi' 
immediately followed by a decimal number shall add (subtract) the
indicated number of lines to (from) the address. A
.BR '\(pl' 
or
.BR '\(mi' 
not followed by a decimal number shall add (subtract) 1 to (from) the
address.
.IP " 2." 4
A decimal number shall add the indicated number of lines to the
address.
.P
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.
.P
Commands take zero, one, or two addresses; see the descriptions of
.IR 1addr
and
.IR 2addr
in
.IR "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.
.P
Addresses shall be separated from each other by a
<comma>
(\c
.BR ',' )
or a
<semicolon>
(\c
.BR ';' ).
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 (\c
.BR '.' )
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.).
.P
A
<percent-sign>
(\c
.BR '%' )
shall be equivalent to entering the two addresses
.BR \(dq1,$\(dq .
.P
Any delimiting
<blank>
characters between addresses, address separators, or address offsets
shall be discarded.
.SS "Command Line Parsing in ex"
.P
The following symbol is used in this and following sections to describe
parsing behavior:
.IP "\fIescape\fP" 10
If a character is referred to as ``\c
<backslash>-escaped''
or ``\c
<control>\(hyV-escaped'',
it shall mean that the character acquired or lost a special
meaning by virtue of being preceded, respectively, by a
<backslash>
or
<control>\(hyV
character. Unless otherwise specified, the escaping character shall be
discarded at that time and shall not be further considered for any
purpose.
.P
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.
.IP " 2." 4
Leading
<blank>
characters shall be skipped.
.IP " 3." 4
If the leading character is a double-quote character, the characters up
to and including the next non-\c
<backslash>-escaped
<newline>
shall be discarded, and any subsequent characters shall be parsed as a
separate command.
.IP " 4." 4
Leading characters that can be interpreted as addresses shall be
evaluated; see
.IR "Addressing in ex".
.IP " 5." 4
Leading
<blank>
characters shall be skipped.
.IP " 6." 4
If the next character is a
<vertical-line>
character or a
<newline>:
.RS 4 
.IP " a." 4
If the next character is a
<newline>:
.RS 4 
.IP " i." 5
If
.IR ex
is in open or visual mode, the current line shall be set to the last
address specified, if any.
.IP ii. 5
Otherwise, if the last command was terminated by a
<vertical-line>
character, no action shall be taken; for example, the command
.BR \(dq||<newline>\(dq 
shall execute two implied commands, not three.
.IP iii. 5
Otherwise, step 6.b. shall apply.
.RE
.IP " b." 4
Otherwise, the implied command shall be the
.BR print
command. The last
.BR # ,
.BR p ,
and
.BR l
flags specified to any
.IR ex
command shall be remembered and shall apply to this implied command.
Executing the
.IR ex
.BR number ,
.BR print ,
or
.BR list
command shall set the remembered flags to
.BR # ,
nothing, and
.BR l ,
respectively, plus any other flags specified for that execution of the
.BR number ,
.BR print ,
or
.BR list
command.
.RS 4 
.P
If
.IR ex
is not currently performing a
.BR global
or
.BR v
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.
.RE
.IP " c." 4
The
<newline>
or
<vertical-line>
character shall be discarded and any subsequent characters shall be
parsed as a separate command.
.RE
.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 4 
.IP " a." 4
Commands that consist of any prefix of the characters in the command
name
.BR delete ,
followed immediately by any of the characters
.BR 'l' ,
.BR 'p' ,
.BR '\(pl' ,
.BR '\(mi' ,
or
.BR '#' 
shall be interpreted as a
.BR delete
command, followed by a
<blank>,
followed by the characters that were not part of the prefix of the
.BR delete
command. The maximum number of characters shall be matched to the
command name
.BR delete ;
for example,
.BR \(dqdel\(dq 
shall not be treated as
.BR \(dqde\(dq 
followed by the flag
.BR l .
.IP " b." 4
Commands that consist of the character
.BR 'k' ,
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
.BR 'k' .
.IP " c." 4
Commands that consist of the character
.BR 's' ,
followed by characters that could be interpreted as valid options to
the
.BR s
command, shall be the equivalent of the
.BR s
command, without any pattern or replacement values, followed by a
<blank>,
followed by the characters after the
.BR 's' .
.RE
.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
center tab(!) box;
lB | lB || lB | lB || lB | lB.
a!append!n!next!t!t
c!change!p!print!u!undo
ch!change!pr!print!un!undo
e!edit!r!read!v!v
m!move!re!read!w!write
ma!mark!s!s
.TE
.RS 4 
.P
Implementation extensions with names causing similar ambiguities shall
not be checked for a match until all possible matches for commands
specified by POSIX.1\(hy2008 have been checked.
.RE
.IP " 9." 4
If the command is a
.BR !
command, or if the command is a
.BR read
command followed by zero or more
<blank>
characters and a
.BR ! ,
or if the command is a
.BR write
command followed by one or more
<blank>
characters and a
.BR ! ,
the rest of the command shall include all characters up to a non-\c
<backslash>-escaped
<newline>.
The
<newline>
shall be discarded and any subsequent characters shall be parsed as a
separate
.IR ex
command.
.IP 10. 4
Otherwise, if the command is an
.BR edit ,
.BR ex ,
or
.BR next
command, or a
.BR visual
command while in open or visual mode, the next part of the command
shall be parsed as follows:
.RS 4 
.IP " a." 4
Any
.BR '!' 
character immediately following the command shall be skipped and be
part of the command.
.IP " b." 4
Any leading
<blank>
characters shall be skipped and be part of the command.
.IP " c." 4
If the next character is a
.BR '\(pl' ,
characters up to the first non-\c
<backslash>-escaped
<newline>
or non-\c
<backslash>-escaped
<blank>
shall be skipped and be part of the command.
.IP " d." 4
The rest of the command shall be determined by the steps specified in
paragraph 12.
.RE
.IP 11. 4
Otherwise, if the command is a
.BR global ,
.BR open ,
.BR s ,
or
.BR v
command, the next part of the command shall be parsed as follows:
.RS 4 
.IP " a." 4
Any leading
<blank>
characters shall be skipped and be part of the command.
.IP " b." 4
If the next character is not an alphanumeric, double-quote,
<newline>,
<backslash>,
or
<vertical-line>
character:
.RS 4 
.IP " i." 5
The next character shall be used as a command delimiter.
.IP ii. 5
If the command is a
.BR global ,
.BR open ,
or
.BR v
command, characters up to the first non-\c
<backslash>-escaped
<newline>,
or first non-\c
<backslash>-escaped
delimiter character, shall be skipped and be part of the command.
.IP iii. 5
If the command is an
.BR s
command, characters up to the first non-\c
<backslash>-escaped
<newline>,
or second non-\c
<backslash>-escaped
delimiter character, shall be skipped and be part of the command.
.RE
.IP " c." 4
If the command is a
.BR global
or
.BR v
command, characters up to the first non-\c
<backslash>-escaped
<newline>
shall be skipped and be part of the command.
.IP " d." 4
Otherwise, the rest of the command shall be determined by the steps
specified in paragraph 12.
.RE
.IP 12. 4
Otherwise:
.RS 4 
.IP " a." 4
If the command was a
.BR map ,
.BR unmap ,
.BR abbreviate ,
or
.BR unabbreviate
command, characters up to the first non-\c
<control>\(hyV-escaped
<newline>,
<vertical-line>,
or double-quote character shall be skipped and be part of the command.
.IP " b." 4
Otherwise, characters up to the first non-\c
<backslash>-escaped
<newline>,
<vertical-line>,
or double-quote character shall be skipped and be part of the command.
.IP " c." 4
If the command was an
.BR append ,
.BR change ,
or
.BR insert
command, and the step 12.b. ended at a
<vertical-line>
character, any subsequent characters, up to the next non-\c
<backslash>-escaped
<newline>
shall be used as input text to the command.
.IP " d." 4
If the command was ended by a double-quote character, all subsequent
characters, up to the next non-\c
<backslash>-escaped
<newline>,
shall be discarded.
.IP " e." 4
The terminating
<newline>
or
<vertical-line>
character shall be discarded and any subsequent characters shall be
parsed as a separate
.IR ex
command.
.RE
.P
Command arguments shall be parsed as described by the Synopsis and
Description of each individual
.IR ex
command. This parsing shall not be
<blank>-sensitive,
except for the
.BR !
argument, which must follow the command name without intervening
<blank>
characters, and where it would otherwise be ambiguous. For example,
.IR count
and
.IR flag
arguments need not be
<blank>-separated
because
.BR \(dqd22p\(dq 
is not ambiguous, but
.IR file
arguments to the
.IR ex
.BR next
command must be separated by one or more
<blank>
characters. Any
<blank>
in command arguments for the
.BR abbreviate ,
.BR unabbreviate ,
.BR map ,
and
.BR unmap
commands can be
<control>\(hyV-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.
.P
Within command arguments for the
.BR abbreviate ,
.BR unabbreviate ,
.BR map ,
and
.BR unmap
commands, any character can be
<control>\(hyV-escaped.
All such escaped characters shall be treated literally and shall have
no special meaning. Within command arguments for all other
.IR ex
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
.BR '!' ,
.BR '%' ,
and
.BR '#' 
expansion characters. See
.IR "Regular Expressions in ex"
and
.IR "Replacement Strings in ex"
for descriptions of command arguments that are regular expressions or
replacement strings.
.P
Non-\c
<backslash>-escaped
.BR '%' 
characters appearing in
.IR file
arguments to any
.IR ex
command shall be replaced by the current pathname; unescaped
.BR '#' 
characters shall be replaced by the alternate pathname. It shall be an
error if
.BR '%' 
or
.BR '#' 
characters appear unescaped in an argument and their corresponding
values are not set.
.P
Non-\c
<backslash>-escaped
.BR '!' 
characters in the arguments to either the
.IR ex
.BR !
command or the open and visual mode
.BR !
command, or in the arguments to the
.IR ex
.BR read
command, where the first non-\c
<blank>
after the command name is a
.BR '!' 
character, or in the arguments to the
.IR ex
.BR write
command where the command name is followed by one or more
<blank>
characters and the first non-\c
<blank>
after the command name is a
.BR '!' 
character, shall be replaced with the arguments to the last of those
three commands as they appeared after all unescaped
.BR '%' ,
.BR '#' ,
and
.BR '!' 
characters were replaced. It shall be an error if
.BR '!' 
characters appear unescaped in one of these commands and there has been
no previous execution of one of these commands.
.P
If an error occurs during the parsing or execution of an
.IR ex
command:
.IP " *" 4
An informational message to this effect shall be written. Execution of
the
.IR ex
command shall stop, and the cursor (for example, the current line and
column) shall not be further modified.
.IP " *" 4
If the
.IR ex
command resulted from a map expansion, all characters from that map
expansion shall be discarded, except as otherwise specified by the
.BR map
command.
.IP " *" 4
Otherwise, if the
.IR ex
command resulted from the processing of an
.IR EXINIT
environment variable, a
.BR .exrc
file, a
.BR :source
command, a
.BR \(mic
option, or a
.BR + \c
.IR command
specified to an
.IR ex
.BR edit ,
.BR ex ,
.BR next ,
or
.BR visual
command, no further commands from the source of the commands shall be
executed.
.IP " *" 4
Otherwise, if the
.IR ex
command resulted from the execution of a buffer or a
.BR global
or
.BR v
command, no further commands caused by the execution of the buffer or
the
.BR global
or
.BR v
command shall be executed.
.IP " *" 4
Otherwise, if the
.IR ex
command was not terminated by a
<newline>,
all characters up to and including the next non-\c
<backslash>-escaped
<newline>
shall be discarded.
.SS "Input Editing in ex"
.P
The following symbol is used in this and the following sections to
specify command actions:
.IP "\fIword\fP" 10
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.
.P
When accepting input characters from the user, in either
.IR ex
command mode or
.IR ex
text input mode,
.IR ex
shall enable canonical mode input processing, as defined in the System Interfaces volume of POSIX.1\(hy2008.
.br
.P
If in
.IR ex
text input mode:
.IP " 1." 4
If the
.BR number
edit option is set,
.IR ex
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
.IR ex
.BR number
command.
.IP " 2." 4
If the
.BR autoindent
edit option is set,
.IR ex
shall prompt for input using
.BR autoindent
characters, as described by the
.BR autoindent
edit option.
.BR autoindent
characters shall follow the line number, if any.
.P
If in
.IR ex
command mode:
.IP " 1." 4
If the
.BR prompt
edit option is set, input shall be prompted for using a single
.BR ':' 
character; otherwise, there shall be no prompt.
.P
The input characters in the following sections shall have the following
effects on the input line.
.SS "Scroll"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
eof
.fi \fR
.P
.RE
.RE
.P
See the description of the
.IR stty
.IR eof
character in
.IR "\fIstty\fR\^".
.P
If in
.IR ex
command mode:
.sp
.RS
If the
.IR eof
character is the first character entered on the line, the line shall be
evaluated as if it contained two characters: a
<control>\(hyD
and a
<newline>.
.P
Otherwise, the
.IR eof
character shall have no special meaning.
.RE
.br
.P
If in
.IR ex
text input mode:
.sp
.RS
If the cursor follows an
.BR autoindent
character, the
.BR autoindent
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
.BR shiftwidth
edit option column boundary, and the user shall be prompted again for
input for the same line.
.P
Otherwise, if the cursor follows a
.BR '0' ,
which follows an
.BR autoindent
character, and the
.BR '0' 
was the previous text input character, the
.BR '0' 
and all
.BR autoindent
characters in the line shall be discarded, and the user shall be
prompted again for input for the same line.
.P
Otherwise, if the cursor follows a
.BR '^' ,
which follows an
.BR autoindent
character, and the
.BR '^' 
was the previous text input character, the
.BR '^' 
and all
.BR autoindent
characters in the line shall be discarded, and the user shall be
prompted again for input for the same line. In addition, the
.BR autoindent
level for the next input line shall be derived from the same line from
which the
.BR autoindent
level for the current input line was derived.
.P
Otherwise, if there are no
.BR autoindent
or text input characters in the line, the
.IR eof
character shall be discarded.
.P
Otherwise, the
.IR eof
character shall have no special meaning.
.RE
.SS "<newline>"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
<newline>
.br
<control>-J
.fi \fR
.P
.RE
.RE
.P
If in
.IR ex
command mode:
.sp
.RS
Cause the command line to be parsed;
<control>\(hyJ
shall be mapped to the
<newline>
for this purpose.
.RE
.br
.P
If in
.IR ex
text input mode:
.sp
.RS
Terminate the current line. If there are no characters other than
.BR autoindent
characters on the line, all characters on the line shall be discarded.
.P
Prompt for text input on a new line after the current line. If the
.BR autoindent
edit option is set, an appropriate number of
.BR autoindent
characters shall be added as a prefix to the line as described by the
.IR ex
.BR autoindent
edit option.
.RE
.SS "<backslash>"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
<backslash>
.fi \fR
.P
.RE
.RE
.P
Allow the entry of a subsequent
<newline>
or
<control>\(hyJ
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>\(hyV"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
<control>-V
.fi \fR
.P
.RE
.RE
.P
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>\(hyV
character shall be discarded before the command line is parsed or the
input text becomes part of the edit buffer.
.P
If the ``literal next'' functionality is performed by the underlying
system, it is implementation-defined whether a character other than
<control>\(hyV
performs this function.
.SS "<control>\(hyW"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
<control>-W
.fi \fR
.P
.RE
.RE
.P
Discard the
<control>\(hyW,
and the word previous to it in the input line, including any
<blank>
characters following the word and preceding the
<control>\(hyW.
If the ``word erase'' functionality is performed by the underlying
system, it is implementation-defined whether a character other than
<control>\(hyW
performs this function.
.SS "Command Descriptions in ex"
.P
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.
.IP "\fI1addr\fR" 10
A single line address, given in any of the forms described in
.IR "Addressing in ex";
the default shall be the current line (\c
.BR '.' ),
unless otherwise specified.
.RS 10 
.P
If the line address is zero, it shall be an error, unless otherwise
specified in the following command descriptions.
.P
If the edit buffer is empty, and the address is specified with a
command other than
.BR = ,
.BR append ,
.BR insert ,
.BR open ,
.BR put ,
.BR read ,
or
.BR visual ,
or the address is not zero, it shall be an error.
.RE
.IP "\fI2addr\fP" 10
Two addresses specifying an inclusive range of lines. If no addresses
are specified, the default for
.IR 2addr
shall be the current line only (\c
.BR \(dq.,.\(dq ),
unless otherwise specified in the following command descriptions. If
one address is specified,
.IR 2addr
shall specify that line only, unless otherwise specified in the
following command descriptions.
.RS 10 
.P
It shall be an error if the first address is greater than the second
address.
.P
If the edit buffer is empty, and the two addresses are specified with a
command other than the
.BR ! ,
.BR write ,
.BR wq ,
or
.BR xit
commands, or either address is not zero, it shall be an error.
.RE
.IP "\fIcount\fP" 10
A positive decimal number. If
.IR count
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
.IR count \(mi1.
.RS 10 
.P
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.
.RE
.IP "\fIflags\fP" 10
One or more of the characters
.BR '\(pl' ,
.BR '\(mi' ,
.BR '#' ,
.BR 'p' ,
or
.BR 'l' 
(ell). The flag characters can be
<blank>-separated,
and in any order or combination. The characters
.BR '#' ,
.BR 'p' ,
and
.BR 'l' 
shall cause lines to be written in the format specified by the
.BR print
command with the specified
.IR flags .
.RS 10 
.P
The lines to be written are as follows:
.IP " 1." 4
All edit buffer lines written during the execution of the
.IR ex
.BR & ,
.BR ~ ,
.BR list ,
.BR number ,
.BR open ,
.BR print ,
.BR s ,
.BR visual ,
and
.BR z
commands shall be written as specified by
.IR flags .
.IP " 2." 4
After the completion of an
.IR ex
command with a flag as an argument, the current line shall be written
as specified by
.IR flags ,
unless the current line was the last line written by the command.
.P
The characters
.BR '\(pl' 
and
.BR '\(mi' 
cause the value of the current line after the execution of the
.IR ex
command to be adjusted by the offset address as described in
.IR "Addressing in ex".
This adjustment shall occur before the current line is written as
described in 2. above.
.P
The default for
.IR flags
shall be none.
.RE
.IP "\fIbuffer\fP" 10
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.
.RS 10 
.P
In
.IR ex
commands, buffer names are specified as the name by itself. In open or
visual mode commands the name is preceded by a double-quote (\c
.BR '\&"' )
character.
.P
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.
.P
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
.IR vi
.BR c
or
.BR d
commands, the motion character associated with the
.BR c
or
.BR d
commands specifies that the buffer text shall be in line mode, or the
commands
.BR % ,
.BR ` ,
.BR / ,
.BR ? ,
.BR ( ,
.BR ) ,
.BR N ,
.BR n ,
.BR { ,
or
.BR }
are used to define a region of text for the
.BR c
or
.BR d
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.
.P
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
.IR ex
commands shall be in line mode. The
.IR ex
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.
.RE
.IP "\fIfile\fP" 10
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
.BR '~' ,
.BR '{' ,
.BR '[' ,
.BR '*' ,
.BR '?' ,
.BR '$' ,
.BR '\&"' ,
backquote, single-quote, and
<backslash>,
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.
.RS 10 
.P
The process of shell expansions in the editor shall be done as
follows. The
.IR ex
utility shall pass two arguments to the program named by the shell edit
option; the first shall be
.BR \(mic ,
and the second shall be the string
.BR \(dqecho\(dq 
and the command text as a single argument. The standard output and
standard error of that command shall replace the command text.
.RE
.IP "\fB!\fP" 10
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
.IR ex
.BR read ,
.BR write ,
and
.BR !
commands, the
.BR '!' 
character shall only act as a modifier if there are no
<blank>
characters between it and the command name.
.IP "\fIremembered\ search\ direction\fP" 10
.br
The
.IR vi
commands
.BR N
and
.BR n
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
.IR ex
.BR global ,
.BR v ,
.BR s ,
and
.BR tag
commands, and the
.IR vi
.BR /
and
.BR ?
commands.
.SS "Abbreviate"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
ab\fB[\fIbreviate\fB][\fIlhs rhs\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If
.IR lhs
and
.IR rhs
are not specified, write the current list of abbreviations and do
nothing more.
.P
Implementations may restrict the set of characters accepted in
.IR lhs
or
.IR rhs ,
except that printable characters and
<blank>
characters shall not be restricted. Additional restrictions shall be
implementation-defined.
.P
In both
.IR lhs
and
.IR rhs ,
any character may be escaped with a
<control>\(hyV,
in which case the character shall not be used to delimit
.IR lhs
from
.IR rhs ,
and the escaping
<control>\(hyV
shall be discarded.
.P
In open and visual text input mode, if a non-word or
<ESC>
character that is not escaped by a
<control>\(hyV
character is entered after a word character, a check shall be made for
a set of characters matching
.IR lhs ,
in the text input entered during this command. If it is found, the
effect shall be as if
.IR rhs
was entered instead of
.IR lhs .
.P
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.
.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.
.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>
characters nor word characters, plus the triggering word character.
.P
It is unspecified whether the
.IR lhs
argument entered for the
.IR ex
.BR abbreviate
and
.BR unabbreviate
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.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Append"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI1addr\fB] \fRa\fB[\fRppend\fB][\fR!\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Enter
.IR ex
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.
.P
This command shall be affected by the
.BR number
and
.BR autoindent
edit options; following the command name with
.BR '!' 
shall cause the
.BR autoindent
edit option setting to be toggled for the duration of this command
only.
.P
.IR "Current line" :
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.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Arguments"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
ar\fB[\fIgs\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Write the current argument list, with the current argument-list entry,
if any, between
.BR '[' 
and
.BR ']' 
characters.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Change"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRc\fB[\fRhange\fB][\fR!\fB][\fIcount\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Enter
.IR ex
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.
.P
This command shall be affected by the
.BR number
and
.BR autoindent
edit options; following the command name with
.BR '!' 
shall cause the
.BR autoindent
edit option setting to be toggled for the duration of this command
only.
.P
.IR "Current line" :
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.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Change Directory"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
chd\fB[\fRir\fB][\fR!\fB][\fIdirectory\fB]\fR
cd\fB[\fR!\fB][\fIdirectory\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Change the current working directory to
.IR directory .
.P
If no
.IR directory
argument is specified, and the
.IR HOME
environment variable is set to a non-null and non-empty value,
.IR directory
shall default to the value named in the
.IR HOME
environment variable. If the
.IR HOME
environment variable is empty or is undefined, the default value of
.IR directory
is implementation-defined.
.P
If no
.BR '!' 
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
.BR '/' ,
it shall be an error.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Copy"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRco\fB[\fRpy\fB] \fI1addr \fB[\fIflags\fB]
[\fI2addr\fB] \fRt \fI1addr \fB[\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
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.
.P
.IR "Current line" :
Set to the last line copied.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Delete"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRd\fB[\fRelete\fB][\fIbuffer\fB][\fIcount\fB][\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Delete the specified lines into a buffer (defaulting to the unnamed
buffer), which shall become a line-mode buffer.
.P
Flags can immediately follow the command name; see
.IR "Command Line Parsing in ex".
.P
.IR "Current line" :
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.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Edit"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
e\fB[\fRdit\fB][\fR!\fB][\fR+\fIcommand\fB][\fIfile\fB]\fR
ex\fB[\fR!\fB][\fR+\fIcommand\fB][\fIfile\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If no
.BR '!' 
is appended to the command name, and the edit buffer has been modified
since the last complete write, it shall be an error.
.P
If
.IR file
is specified, replace the current contents of the edit buffer with the
current contents of
.IR file ,
and set the current pathname to
.IR file .
If
.IR file
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.
.P
The
.BR + \c
.IR command
option shall be
<blank>-delimited;
<blank>
characters within the
.BR + \c
.IR command
can be escaped by preceding them with a
<backslash>
character. The
.BR + \c
.IR command
shall be interpreted as an
.IR ex
command immediately after the contents of the edit buffer have been
replaced and the current line and column have been set.
.P
If the edit buffer is empty:
.P
.IR "Current line" :
Set to 0.
.P
.IR "Current column" :
Set to 1.
.P
Otherwise, if executed while in
.IR ex
command mode or if the
.BR + \c
.IR command
argument is specified:
.P
.IR "Current line" :
Set to the last line of the edit buffer.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.P
Otherwise, if
.IR file
is omitted or results in the current pathname:
.P
.IR "Current line" :
Set to the first line of the edit buffer.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.P
Otherwise, if
.IR file
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:
.P
.IR "Current line" :
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.
.P
.IR "Current column" :
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-\c
<blank>.
.br
.P
Otherwise:
.P
.IR "Current line" :
Set to the first line of the edit buffer.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "File"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
f\fB[\fRile\fB][\fIfile\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If a
.IR file
argument is specified, the alternate pathname shall be set to the
current pathname, and the current pathname shall be set to
.IR file .
.P
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
.BR readonly
edit option is set, this fact shall be included in this message. The
message may contain other unspecified information.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Global"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRg\fB[\fRlobal\fB] \fR/\fIpattern\fR/ \fB[\fIcommands\fB]
[\fI2addr\fB] \fRv /\fIpattern\fR/ \fB[\fIcommands\fB]\fR
.fi \fR
.P
.RE
.RE
.P
The optional
.BR '!' 
character after the
.BR global
command shall be the same as executing the
.BR v
command.
.P
If
.IR pattern
is empty (for example,
.BR \(dq//\(dq )
or not specified, the last regular expression used in the editor
command shall be used as the
.IR pattern .
The
.IR pattern
can be delimited by
<slash>
characters (shown in the Synopsis), as well as any non-alphanumeric
or non-\c
<blank>
other than
<backslash>,
<vertical-line>,
<newline>,
or double-quote.
.P
If no lines are specified, the lines shall default to the entire file.
.P
The
.BR global
and
.BR v
commands are logically two-pass operations. First, mark the lines
within the specified lines for which the line excluding the terminating
<newline>
matches (\c
.BR global )
or does not match (\c
.BR v
or
.BR global! )
the specified pattern. Second, execute the
.IR ex
commands given by
.IR commands ,
with the current line (\c
.BR '.' )
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
.IR ex
.BR :edit
command) an error message shall be written and no more commands
resulting from the execution of this command shall be processed.
.P
Multiple
.IR ex
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>.
.P
If no commands are specified:
.IP " 1." 4
If in
.IR ex
command mode, it shall be as if the
.BR print
command were specified.
.IP " 2." 4
Otherwise, no command shall be executed.
.P
For the
.BR append ,
.BR change ,
and
.BR insert
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
.BR open
and
.BR visual
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
.IR vi
.BR Q
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.
.P
The
.BR global ,
.BR v ,
and
.BR undo
commands cannot be used in
.IR commands .
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.
.P
If the remembered search direction is not set, the
.BR global
and
.BR v
commands shall set it to forward.
.P
The
.BR autoprint
and
.BR autoindent
edit options shall be inhibited for the duration of the
.BR g
or
.BR v
command.
.P
.IR "Current line" :
If no commands executed, set to the last marked line. Otherwise, as
specified for the executed
.IR ex
commands.
.P
.IR "Current column" :
If no commands are executed, set to non-\c
<blank>;
otherwise, as specified for the individual
.IR ex
commands.
.SS "Insert"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI1addr\fB] \fRi\fB[\fRnsert\fB][\fR!\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Enter
.IR ex
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.
.P
This command shall be affected by the
.BR number
and
.BR autoindent
edit options; following the command name with
.BR '!' 
shall cause the
.BR autoindent
edit option setting to be toggled for the duration of this command
only.
.P
.IR "Current line" :
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.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Join"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRj\fB[\fRoin\fB][\fR!\fB][\fIcount\fB][\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If
.IR count
is specified:
.sp
.RS
If no address was specified, the
.BR join
command shall behave as if
.IR 2addr
were the current line and the current line plus
.IR count
(.\|,\|. +
.IR count ).
.P
If one address was specified, the
.BR join
command shall behave as if
.IR 2addr
were the specified address and the specified address plus
.IR count
(\c
.IR addr ,\c
.IR addr
+
.IR count ).
.P
If two addresses were specified, the
.BR join
command shall behave as if an additional address, equal to the last
address plus
.IR count
\(mi1 (\c
.IR addr1 ,\c
.IR addr2 ,\c
.IR addr2
+
.IR count
\(mi1), was specified.
.P
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.
.RE
.P
If no
.IR count
is specified:
.sp
.RS
If no address was specified, the
.BR join
command shall behave as if
.IR 2addr
were the current line and the next line (.\|,\|. +1).
.P
If one address was specified, the
.BR join
command shall behave as if
.IR 2addr
were the specified address and the next line (\c
.IR addr ,\c
.IR addr
+1).
.RE
.P
Join the text from the specified lines together into a single line,
which shall replace the specified lines.
.P
If a
.BR '!' 
character is appended to the command name, the
.BR join
shall be without modification of any line, independent of the current
locale.
.P
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>
characters from the line to be joined.
.IP " 2." 4
If the line to be joined is now empty, delete it, and skip steps 3
through 5.
.IP " 3." 4
If the current line ends in a
<blank>,
or the first character of the line to be joined is a
.BR ')' 
character, join the lines without further modification.
.IP " 4." 4
If the last character of the current line is a
.BR '.' ,
join the lines with two
<space>
characters between them.
.IP " 5." 4
Otherwise, join the lines with a single
<space>
between them.
.P
.IR "Current line" :
Set to the first line specified.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "List"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRl\fB[\fRist\fB][\fIcount\fB][\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
This command shall be equivalent to the
.IR ex
command:
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB] \fRl\fB[\fIflags\fB]\fR
.fi \fR
.P
.RE
.P
See
.IR "Print".
.SS "Map"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
map\fB[\fR!\fB][\fIlhs rhs\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If
.IR lhs
and
.IR rhs
are not specified:
.IP " 1." 4
If
.BR '!' 
is specified, write the current list of text input mode maps.
.IP " 2." 4
Otherwise, write the current list of command mode maps.
.IP " 3." 4
Do nothing more.
.P
Implementations may restrict the set of characters accepted in
.IR lhs
or
.IR rhs ,
except that printable characters and
<blank>
characters shall not be restricted. Additional restrictions shall be
implementation-defined. In both
.IR lhs
and
.IR rhs ,
any character can be escaped with a
<control>\(hyV,
in which case the character shall not be used to delimit
.IR lhs
from
.IR rhs ,
and the escaping
<control>\(hyV
shall be discarded.
.P
If the character
.BR '!' 
is appended to the
.BR map
command name, the mapping shall be effective during open or visual text
input mode rather than
.BR open
or
.BR visual
command mode. This allows
.IR lhs
to have two different
.BR map
definitions at the same time: one for command mode and one for text
input mode.
.br
.P
For command mode mappings:
.sp
.RS
When the
.IR lhs
is entered as any part of a
.IR vi
command in open or visual mode (but not as part of the arguments to the
command), the action shall be as if the corresponding
.IR rhs
had been entered.
.P
If any character in the command, other than the first, is escaped using
a
<control>\(hyV
character, that character shall not be part of a match to an
.IR lhs .
.P
It is unspecified whether implementations shall support
.BR map
commands where the
.IR lhs
is more than a single character in length, where the first character of
the
.IR lhs
is printable.
.RE
.P
.sp
.RS
If
.IR lhs
contains more than one character and the first character is
.BR '#' ,
followed by a sequence of digits corresponding to a numbered function
key, then when this function key is typed it shall be mapped to
.IR rhs .
Characters other than digits following a
.BR '#' 
character also represent the function key named by the characters in
the
.IR lhs
following the
.BR '#' 
and may be mapped to
.IR rhs .
It is unspecified how function keys are named or what function keys are
supported.
.RE
.P
For text input mode mappings:
.sp
.RS
When the
.IR lhs
is entered as any part of text entered in open or visual text input
modes, the action shall be as if the corresponding
.IR rhs
had been entered.
.P
If any character in the input text is escaped using a
<control>\(hyV
character, that character shall not be part of a match to an
.IR lhs .
.P
It is unspecified whether the
.IR lhs
text entered for subsequent
.BR map
or
.BR unmap
commands is replaced with the
.IR rhs
text for the purposes of the screen display; regardless of whether or
not the display appears as if the corresponding
.IR rhs
text was entered, the effect of the command shall be as if the
.IR lhs
text was entered.
.RE
.P
If only part of the
.IR lhs
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
.IR lhs .
.P
The
.IR rhs
characters shall themselves be subject to remapping, unless otherwise
specified by the
.BR remap
edit option, except that if the characters in
.IR lhs
occur as prefix characters in
.IR rhs ,
those characters shall not be remapped.
.P
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.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Mark"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI1addr\fB] \fRma\fB[\fRrk\fB] \fIcharacter
\fB[\fI1addr\fB] \fRk \fIcharacter\fR
.fi \fR
.P
.RE
.RE
.P
Implementations shall support
.IR character
values of a single lowercase letter of the POSIX locale and the
backquote and single-quote characters; support of other characters is
implementation-defined.
.P
If executing the
.IR vi
.BR m
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.
.P
Otherwise, set the specified mark to the specified line and 1-based
numbered first non-\c
<blank>
non-\c
<newline>
in the line, if any; otherwise, the last non-\c
<newline>
in the line, if any; otherwise, column position 1.
.P
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
.BR undo
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.
.P
The marks
.BR `
and
.BR '
shall be set as described previously, immediately before the following
events occur in the editor:
.IP " 1." 4
The use of
.BR '$' 
as an
.IR ex
address
.IP " 2." 4
The use of a positive decimal number as an
.IR ex
address
.IP " 3." 4
The use of a search command as an
.IR ex
address
.IP " 4." 4
The use of a mark reference as an
.IR ex
address
.IP " 5." 4
The use of the following open and visual mode commands:
<control>\(hy],
.BR % ,
.BR ( ,
.BR ) ,
.BR [ ,
.BR ] ,
.BR { ,
.BR }
.IP " 6." 4
The use of the following open and visual mode commands:
.BR ' ,
.BR G ,
.BR H ,
.BR L ,
.BR M ,
.BR z
if the current line will change as a result of the command
.IP " 7." 4
The use of the open and visual mode commands:
.BR / ,
.BR ? ,
.BR N ,
.BR ` ,
.BR n
if the current line or column will change as a result of the command
.IP " 8." 4
The use of the
.IR ex
mode commands:
.BR z ,
.BR undo ,
.BR global ,
.BR v
.P
For rules 1., 2., 3., and 4., the
.BR `
and
.BR '
marks shall not be set if the
.IR ex
command is parsed as specified by rule 6.a. in
.IR "Command Line Parsing in ex".
.P
For rules 5., 6., and 7., the
.BR `
and
.BR '
marks shall not be set if the commands are used as motion commands in
open and visual mode.
.P
For rules 1., 2., 3., 4., 5., 6., 7., and 8., the
.BR `
and
.BR '
marks shall not be set if the command fails.
.P
The
.BR `
and
.BR '
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
.BR ex
mode and the edit buffer is not empty, before any commands or movements
(including commands or movements specified by the
.BR \(mic
or
.BR \(mit
options or the
.BR + \c
.IR command
argument) are executed on the edit buffer. If in open or visual mode,
the marks shall be set as if executing the
.IR vi
.BR m
command; otherwise, as if executing the
.IR ex
.BR mark
command.
.P
When changing from
.BR ex
mode to open or visual mode, if the
.BR `
and
.BR '
marks are not already set, the
.BR `
and
.BR '
marks shall be set as described previously.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Move"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRm\fB[\fRove\fB] \fI1addr\fR \fB[\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
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.
.P
.IR "Current line" :
Set to the last of the moved lines.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Next"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
n\fB[\fRext\fB][\fR!\fB][\fR+\fIcommand\fB][\fIfile \fR...\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If no
.BR '!' 
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
.BR autowrite
option.
.br
.P
If one or more files is specified:
.IP " 1." 4
Set the argument list to the specified filenames.
.IP " 2." 4
Set the current argument list reference to be the first entry in the
argument list.
.IP " 3." 4
Set the current pathname to the first filename specified.
.P
Otherwise:
.IP " 1." 4
It shall be an error if there are no more filenames in the argument
list after the filename currently referenced.
.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.
.P
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.
.P
This command shall be affected by the
.BR autowrite
and
.BR writeany
edit options.
.P
The
.BR + \c
.IR command
option shall be
<blank>-delimited;
<blank>
characters can be escaped by preceding them with a
<backslash>
character. The
.BR + \c
.IR command
shall be interpreted as an
.IR ex
command immediately after the contents of the edit buffer have been
replaced and the current line and column have been set.
.P
.IR "Current line" :
Set as described for the
.BR edit
command.
.P
.IR "Current column" :
Set as described for the
.BR edit
command.
.SS "Number"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRnu\fB[\fRmber\fB][\fIcount\fB][\fIflags\fB]
[\fI2addr\fB] \fR#\fB[\fIcount\fB][\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
These commands shall be equivalent to the
.IR ex
command:
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB] \fR#\fB[\fIflags\fB]\fR
.fi \fR
.P
.RE
.P
See
.IR "Print".
.SS "Open"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI1addr\fB] \fRo\fB[\fRpen\fB]\fR /\fIpattern\fR/ \fB[\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
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.
.P
Enter open mode.
.P
The trailing delimiter can be omitted from
.IR pattern
at the end of the command line. If
.IR pattern
is empty (for example,
.BR \(dq//\(dq )
or not specified, the last regular expression used in the editor shall
be used as the pattern. The pattern can be delimited by
<slash>
characters (shown in the Synopsis), as well as any alphanumeric, or non-\c
<blank>
other than
<backslash>,
<vertical-line>,
<newline>,
or
double-quote.
.P
.IR "Current line" :
Set to the specified line.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Preserve"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
pre\fB[\fRserve\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Save the edit buffer in a form that can later be recovered by using the
.BR \(mir
option or by using the
.IR ex
.BR recover
command. After the file has been preserved, a mail message shall be
sent to the user. This message shall be readable by invoking the
.IR mailx
utility. The message shall contain the name of the file, the time of
preservation, and an
.IR ex
command that could be used to recover the file. Additional information
may be included in the mail message.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Print"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB][\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
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.
.P
Non-printable characters, except for the
<tab>,
shall be written as implementation-defined multi-character sequences.
.P
If the
.BR #
flag is specified or the
.BR number
edit option is set, each line shall be preceded by its line number in
the following format:
.sp
.RS 4
.nf
\fB
"%6d  ", <\fIline number\fR>
.fi \fR
.P
.RE
.P
If the
.BR l
flag is specified or the
.BR list
edit option is set:
.IP " 1." 4
The characters listed in the Base Definitions volume of POSIX.1\(hy2008,
.IR "Table 5-1" ", " "Escape Sequences and Associated Actions"
shall be written as the corresponding escape sequence.
.IP " 2." 4
Non-printable characters not in the Base Definitions volume of POSIX.1\(hy2008,
.IR "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).
.IP " 3." 4
The end of each line shall be marked with a
.BR '$' ,
and literal
.BR '$' 
characters within the line shall be written with a preceding
<backslash>.
.P
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.
.P
If a line is folded, and the
.BR l
flag is not specified and the
.BR list
edit option is not set, it is unspecified whether a multi-column
character at the folding position is separated; it shall not be
discarded.
.P
.IR "Current line" :
Set to the last written line.
.P
.IR "Current column" :
Unchanged if the current line is unchanged; otherwise, set to non-\c
<blank>.
.SS "Put"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI1addr\fB] \fRpu\fB[\fRt\fB][\fIbuffer\fB]\fR
.fi \fR
.P
.RE
.RE
.P
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.
.P
.IR "Current line" :
Set to the last line entered into the edit buffer.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Quit"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
q\fB[\fRuit\fB][\fR!\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If no
.BR '!' 
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.
.IP " 2." 4
If there are filenames in the argument list after the filename
currently referenced, and the last command was not a
.BR quit ,
.BR wq ,
.BR xit ,
or
.BR ZZ
(see
.IR "Exit")
command, it shall be an error.
.P
Otherwise, terminate the editing session.
.SS "Read"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI1addr\fB] \fRr\fB[\fRead\fB][\fR!\fB][\fIfile\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If
.BR '!' 
is not the first non-\c
<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
.IR file
is named, the current pathname shall be the default. If there is no
current pathname, then
.IR file
shall become the current pathname. If there is no current pathname or
.IR file
operand, it shall be an error. Specifying a
.IR file
that is not of type regular shall have unspecified results.
.P
Otherwise, if
.IR file
is preceded by
.BR '!' ,
the rest of the line after the
.BR '!' 
shall have
.BR '%' ,
.BR '#' ,
and
.BR '!' 
characters expanded as described in
.IR "Command Line Parsing in ex".
.P
The
.IR ex
utility shall then pass two arguments to the program named by the
shell edit option; the first shall be
.BR \(mic
and the second shall be the expanded arguments to the
.BR read
command as a single argument. The standard input of the program shall
be set to the standard input of the
.IR ex
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.
.P
Each line in the copied file or program output (as delimited by
<newline>
characters 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>
characters.
.P
The special meaning of the
.BR '!' 
following the
.BR read
command can be overridden by escaping it with a
<backslash>
character.
.P
.IR "Current line" :
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.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Recover"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
rec\fB[\fRover\fB][\fR!\fB] \fIfile\fR
.fi \fR
.P
.RE
.RE
.P
If no
.BR '!' 
is appended to the command name, and the edit buffer has been modified
since the last complete write, it shall be an error.
.P
If no
.IR file
operand is specified, then the current pathname shall be used. If
there is no current pathname or
.IR file
operand, it shall be an error.
.P
If no recovery information has previously been saved about
.IR file ,
the
.BR recover
command shall behave identically to the
.BR edit
command, and an informational message to this effect shall be written.
.P
Otherwise, set the current pathname to
.IR file ,
and replace the current contents of the edit buffer with the recovered
contents of
.IR file .
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.
.P
.IR "Current file" :
Set as described for the
.BR edit
command.
.P
.IR "Current column" :
Set as described for the
.BR edit
command.
.SS "Rewind"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
rew\fB[\fRind\fB][\fR!\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If no
.BR '!' 
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
.BR autowrite
option.
.P
If the argument list is empty, it shall be an error.
.P
The current argument list reference and the current pathname shall be
set to the first filename in the argument list.
.P
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.
.P
This command shall be affected by the
.BR autowrite
and
.BR writeany
edit options.
.P
.IR "Current line" :
Set as described for the
.BR edit
command.
.P
.IR "Current column" :
Set as described for the
.BR edit
command.
.SS "Set"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
se\fB[\fRt\fB][\fIoption\fB[\fR=\fB[\fIvalue\fB]]\fR ...\fB][\fRno\fIoption\fR ...\fB][\fIoption\fR? ...\fB][\fRall\fB]\fR
.fi \fR
.P
.RE
.RE
.P
When no arguments are specified, write the value of the
.BR term
edit option and those options whose values have been changed from the
default settings; when the argument
.IR all
is specified, write all of the option values.
.P
Giving an option name followed by the character
.BR '?' 
shall cause the current value of that option to be written. The
.BR '?' 
can be separated from the option name by zero or more
<blank>
characters. The
.BR '?' 
shall be necessary only for Boolean valued options. Boolean options can
be given values by the form
.BR set
.IR option
to turn them on or
.BR set
.BR no \c
.IR option
to turn them off; string and numeric options can be assigned by the
form
.BR set
.IR option =\c
.IR value .
Any
<blank>
characters 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>
characters.
.P
See
.IR "Edit Options in ex"
for details about specific options.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Shell"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
sh\fB[\fRell\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Invoke the program named in the
.BR shell
edit option with the single argument
.BR \(mii
(interactive mode). Editing shall be resumed when the program exits.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Source"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
so\fB[\fRurce\fB] \fIfile\fR
.fi \fR
.P
.RE
.RE
.P
Read and execute
.IR ex
commands from
.IR file .
Lines in the file that are blank lines shall be ignored.
.P
.IR "Current line" :
As specified for the individual
.IR ex
commands.
.P
.IR "Current column" :
As specified for the individual
.IR ex
commands.
.SS "Substitute"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRs\fB[\fRubstitute\fB][\fR/\fIpattern\fR/\fIrepl\fR/\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR
.br
\fB[\fI2addr\fB] \fR&\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR
.br
\fB[\fI2addr\fB] \fR~\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR
.fi \fR
.P
.RE
.RE
.P
Replace the first instance of the pattern
.IR pattern
by the string
.IR repl
on each specified line. (See
.IR "Regular Expressions in ex"
and
.IR "Replacement Strings in ex".)
Any non-alphabetic, non-\c
<blank>
delimiter other than
<backslash>,
.BR '|' ,
<newline>,
or double-quote
can be used instead of
.BR '/' .
<backslash>
characters can be used to escape delimiters,
<backslash>
characters, and other special characters.
.P
The trailing delimiter can be omitted from
.IR pattern
or from
.IR repl
at the end of the command line. If both
.IR pattern
and
.IR repl
are not specified or are empty (for example,
.BR \(dq//\(dq ),
the last
.BR s
command shall be repeated. If only
.IR pattern
is not specified or is empty, the last regular expression used in the
editor shall be used as the pattern. If only
.IR repl
is not specified or is empty, the pattern shall be replaced by nothing.
If the entire replacement pattern is
.BR '%' ,
the last replacement pattern to an
.BR s
command shall be used.
.P
Entering a
<carriage-return>
in
.IR repl
(which requires an escaping
<backslash>
in
.IR ex
mode and an escaping
<control>\(hyV
in open or
.IR vi
mode) shall split the line at that point, creating a new line in the
edit buffer. The
<carriage-return>
shall be discarded.
.P
If
.IR options
includes the letter
.BR 'g' 
(\c
.BR global ),
all non-overlapping instances of the pattern in the line shall be
replaced.
.P
If
.IR options
includes the letter
.BR 'c' 
(\c
.BR confirm ),
then before each substitution the line shall be written; the written
line shall reflect all previous substitutions. On the following line,
<space>
characters shall be written beneath the characters from the line that
are before the
.IR pattern
to be replaced, and
.BR '^' 
characters written beneath the characters included in the
.IR pattern
to be replaced. The
.IR ex
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
.IR ex
command line.
.P
If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications
confirmed by the user shall be preserved in the edit buffer after the
interrupt.
.P
If the remembered search direction is not set, the
.BR s
command shall set it to forward.
.P
In the second Synopsis, the
.BR &
command shall repeat the previous substitution, as if the
.BR &
command were replaced by:
.sp
.RS 4
.nf
\fB
s/\fIpattern\fR/\fIrepl\fR/
.fi \fR
.P
.RE
.P
where
.IR pattern
and
.IR repl
are as specified in the previous
.BR s ,
.BR & ,
or
.BR ~
command.
.P
In the third Synopsis, the
.BR ~
command shall repeat the previous substitution, as if the
.BR '~' 
were replaced by:
.sp
.RS 4
.nf
\fB
s/\fIpattern\fR/\fIrepl\fR/
.fi \fR
.P
.RE
.P
where
.IR pattern
shall be the last regular expression specified to the editor, and
.IR repl
shall be from the previous substitution (including
.BR &
and
.BR ~ )
command.
.P
These commands shall be affected by the
.IR LC_MESSAGES
environment variable.
.P
.IR "Current line" :
Set to the last line in which a substitution occurred, or, unchanged if
no substitution occurred.
.P
.IR "Current column":
Set to non-\c
<blank>.
.SS "Suspend"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
su\fB[\fRspend\fB][\fR!\fB]\fR
st\fB[\fRop\fB][\fR!\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Allow control to return to the invoking process;
.IR ex
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
.IR set
.BR \(mim ).
.P
These commands shall be affected by the
.BR autowrite
and
.BR writeany
edit options.
.P
The current
.BR susp
character (see
.IR "\fIstty\fR\^")
shall be equivalent to the
.BR suspend
command.
.SS "Tag"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
ta\fB[\fRg\fB][\fR!\fB] \fItagstring\fR
.fi \fR
.P
.RE
.RE
.P
The results are unspecified if the format of a tags file is not as
specified by the
.IR ctags
utility (see
.IR "\fIctags\fR\^")
description.
.P
The
.BR tag
command shall search for
.IR tagstring
in the tag files referred to by the
.BR tag
edit option, in the order they are specified, until a reference to
.IR tagstring
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
.BR tag
edit option, it shall be an error, and an error message shall be
written at the first occurrence of such an error.
.P
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
.BR s
command.
.P
If the
.IR tagstring
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
.BR '!' 
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
.BR autowrite
option.
.P
This command shall be affected by the
.BR autowrite ,
.BR tag ,
.BR taglength ,
and
.BR writeany
edit options.
.P
.IR "Current line" :
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
.BR edit
command.
.P
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
.BR edit
command.
.P
.IR "Current column" :
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-\c
<blank>.
Otherwise, set as specified for the
.BR edit
command.
.SS "Unabbreviate"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
una\fB[\fRbbrev\fB] \fIlhs\fR
.fi \fR
.P
.RE
.RE
.P
If
.IR lhs
is not an entry in the current list of abbreviations (see
.IR "Abbreviate"),
it shall be an error. Otherwise, delete
.IR lhs
from the list of abbreviations.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Undo"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
u\fB[\fRndo\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Reverse the changes made by the last command that modified the contents
of the edit buffer, including
.BR undo .
For this purpose, the
.BR global ,
.BR v ,
.BR open ,
and
.BR visual
commands, and commands resulting from buffer executions and mapped
character expansions, are considered single commands.
.P
If no action that can be undone preceded the
.BR undo
command, it shall be an error.
.P
If the
.BR undo
command restores lines that were marked, the mark shall also be
restored unless it was reset subsequent to the deletion of the lines.
.P
.IR "Current line" :
.IP " 1." 4
If lines are added or changed in the file, set to the first line added
or changed.
.IP " 2." 4
Set to the line before the first line deleted, if it exists.
.IP " 3." 4
Set to 1 if the edit buffer is not empty.
.IP " 4." 4
Set to zero.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Unmap"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
unm\fB[\fRap\fB][\fR!\fB] \fIlhs\fR
.fi \fR
.P
.RE
.RE
.P
If
.BR '!' 
is appended to the command name, and if
.IR lhs
is not an entry in the list of text input mode map definitions, it
shall be an error. Otherwise, delete
.IR lhs
from the list of text input mode map definitions.
.P
If no
.BR '!' 
is appended to the command name, and if
.IR lhs
is not an entry in the list of command mode map definitions, it shall
be an error. Otherwise, delete
.IR lhs
from the list of command mode map definitions.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Version"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
ve\fB[\fRrsion\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Write a message containing version information for the editor. The
format of the message is unspecified.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Visual"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI1addr\fB] \fRvi\fB[\fRsual\fB][\fItype\fB][\fIcount\fB][\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If
.IR ex
is currently in open or visual mode, the Synopsis and behavior of the
visual command shall be the same as the
.BR edit
command, as specified by
.IR "Edit".
.P
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.
.P
If
.IR count
is specified, the value of the
.BR window
edit option shall be set to
.IR count
(as described in
.IR "window").
If the
.BR '^' 
type character was also specified, the
.BR window
edit option shall be set before being used by the type character.
.P
Enter visual mode. If
.IR type
is not specified, it shall be as if a
.IR type
of
.BR '\(pl' 
was specified. The
.IR type
shall cause the following effects:
.IP "\fR+\fP" 6
Place the beginning of the specified line at the top of the display.
.IP "\fR-\fP" 6
Place the end of the specified line at the bottom of the display.
.IP "\fR.\fP" 6
Place the beginning of the specified line in the middle of the display.
.IP "\fR^\fP" 6
If the specified line is less than or equal to the value of the
.BR window
edit option, set the line to 1; otherwise, decrement the line by the
value of the
.BR window
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
.BR window
edit option number of lines.
.P
.IR "Current line" :
Set to the specified line.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Write"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRw\fB[\fRrite\fB][\fR!\fB][\fR>>\fB][\fIfile\fB]
[\fI2addr\fB] \fRw\fB[\fRrite\fB][\fR!\fB][\fIfile\fB]
[\fI2addr\fB] \fRwq\fB[\fR!\fB][\fR>>\fB][\fIfile\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If no lines are specified, the lines shall default to the entire file.
.P
The command
.BR wq
shall be equivalent to a
.BR write
command followed by a
.BR quit
command;
.BR wq!
shall be equivalent to
.BR write!
followed by
.BR quit .
In both cases, if the
.BR write
command fails, the
.BR quit
shall not be attempted.
.P
If the command name is not followed by one or more
<blank>
characters, or
.IR file
is not preceded by a
.BR '!' 
character, the
.BR write
shall be to a file.
.IP " 1." 4
If the
.BR >>
argument is specified, and the file already exists, the lines shall be
appended to the file instead of replacing its contents. If the
.BR >>
argument is specified, and the file does not already exist, it is
unspecified whether the write shall proceed as if the
.BR >>
argument had not been specified or if the write shall fail.
.IP " 2." 4
If the
.BR readonly
edit option is set (see
.IR "readonly"),
the
.BR write
shall fail.
.IP " 3." 4
If
.IR file
is specified, and is not the current pathname, and the file exists,
the
.BR write
shall fail.
.IP " 4." 4
If
.IR file
is not specified, the current pathname shall be used. If there is no
current pathname, the
.BR write
command shall fail.
.IP " 5." 4
If the current pathname is used, and the current pathname has been
changed by the
.BR file
or
.BR read
commands, and the file exists, the
.BR write
shall fail. If the
.BR write
is successful, subsequent
.BR write s
shall not fail for this reason (unless the current pathname is changed
again).
.IP " 6." 4
If the whole edit buffer is not being written, and the file to be
written exists, the
.BR write
shall fail.
.P
For rules 1., 2., 3., and 5., the
.BR write
can be forced by appending the character
.BR '!' 
to the command name.
.P
For rules 2., 3., and 5., the
.BR write
can be forced by setting the
.BR writeany
edit option.
.P
Additional, implementation-defined tests may cause the
.BR write
to fail.
.P
If the edit buffer is empty, a file without any contents shall be written.
.P
An informational message shall be written noting the number of lines
and bytes written.
.P
Otherwise, if the command is followed by one or more
<blank>
characters, and the file is preceded by
.BR '!' ,
the rest of the line after the
.BR '!' 
shall have
.BR '%' ,
.BR '#' ,
and
.BR '!' 
characters expanded as described in
.IR "Command Line Parsing in ex".
.P
The
.IR ex
utility shall then pass two arguments to the program named by the
.BR shell
edit option; the first shall be
.BR \(mic
and the second shall be the expanded arguments to the
.BR write
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
.BR print
command. If the last character in that output is not a
<newline>,
a
<newline>
shall be written at the end of the output.
.P
The special meaning of the
.BR '!' 
following the
.BR write
command can be overridden by escaping it with a
<backslash>
character.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Write and Exit"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRx\fB[\fRit\fB][\fR!\fB][\fIfile\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If the edit buffer has not been modified since the last complete
.BR write ,
.BR xit
shall be equivalent to the
.BR quit
command, or if a
.BR '!' 
is appended to the command name, to
.BR quit! .
.P
Otherwise,
.BR xit
shall be equivalent to the
.BR wq
command, or if a
.BR '!' 
is appended to the command name, to
.BR wq! .
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Yank"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB] \fRya\fB[\fRnk\fB][\fIbuffer\fB][\fIcount\fB]\fR
.fi \fR
.P
.RE
.RE
.P
Copy the specified lines to the specified buffer (by default, the
unnamed buffer), which shall become a line-mode buffer.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Adjust Window"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI1addr\fB] \fRz\fB[\fR!\fB][\fItype \fR...\fB][\fIcount\fB][\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If no line is specified, the current line shall be the default; if
.IR type
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.
.P
If there are
<blank>
characters between the
.IR type
argument and the preceding
.BR z
command name or optional
.BR '!' 
character, it shall be an error.
.P
If
.IR count
is specified, the value of the
.BR window
edit option shall be set to
.IR count
(as described in
.IR "window").
If
.IR count
is omitted, it shall default to 2 times the value of the
.BR scroll
edit option, or if
.BR !
was specified, the number of lines in the display minus 1.
.P
If
.IR type
is omitted, then
.IR count
lines starting with the specified line shall be written. Otherwise,
.IR count
lines starting with the line specified by the
.IR type
argument shall be written.
.P
The
.IR type
argument shall change the lines to be written. The possible values of
.IR type
are as follows:
.IP "\fR\(mi\fP" 6
The specified line shall be decremented by the following value:
.RS 6 
.sp
.RS 4
.nf
\fB
(((number of ``\(mi'' characters) x \fIcount\fR) \(mi1)
.fi \fR
.P
.RE
.P
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
.IR count
lines or the last line in the edit buffer has been written.
.RE
.IP "\fR+\fP" 6
The specified line shall be incremented by the following value:
.RS 6 
.sp
.RS 4
.nf
\fB
(((number of ``+'' characters) \(mi1) x \fIcount\fR) +1
.fi \fR
.P
.RE
.P
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
.IR count
lines or the last line in the edit buffer has been written.
.RE
.IP "\fR=\fR,\fR.\fR" 6
If more than a single
.BR '.' 
or
.BR '=' 
is specified, it shall be an error. The following steps shall be
taken:
.RS 6 
.IP " 1." 4
If
.IR count
is zero, nothing shall be written.
.IP " 2." 4
Write as many of the
.IR N
lines before the current line in the edit buffer as exist. If
.IR count
or
.BR '!' 
was specified,
.IR N
shall be:
.RS 4 
.sp
.RS 4
.nf
\fB
(\fIcount\fR \(mi1) /2
.fi \fR
.P
.RE
.P
Otherwise,
.IR N
shall be:
.sp
.RS 4
.nf
\fB
(\fIcount\fP \(mi3) /2
.fi \fR
.P
.RE
.P
If
.IR N
is a number less than 3, no lines shall be written.
.RE
.IP " 3." 4
If
.BR '=' 
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
.BR '\(mi' 
characters.
.IP " 4." 4
Write the current line.
.IP " 5." 4
Repeat step 3.
.IP " 6." 4
Write as many of the
.IR N
lines after the current line in the edit buffer as exist.
.IR N
shall be defined as in step 2. If
.IR N
is a number less than 3, no lines shall be written. If
.IR count
is less than 3, no lines shall be written.
.RE
.IP "\fR^\fP" 6
The specified line shall be decremented by the following value:
.RS 6 
.sp
.RS 4
.nf
\fB
(((number of ``^'' characters) +1) x \fIcount\fR) \(mi1
.fi \fR
.P
.RE
.P
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
.IR count
lines or the last line in the edit buffer has been written.
.RE
.P
.IR "Current line" :
Set to the last line written, unless the type is
.BR = ,
in which case, set to the specified line.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Escape"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
! \fIcommand
\fB[\fIaddr\fB]\fR! \fIcommand\fR
.fi \fR
.P
.RE
.RE
.P
The contents of the line after the
.BR '!' 
shall have
.BR '%' ,
.BR '#' ,
and
.BR '!' 
characters expanded as described in
.IR "Command Line Parsing in ex".
If the expansion causes the text of the line to change, it shall be
redisplayed, preceded by a single
.BR '!' 
character.
.P
The
.IR ex
utility shall execute the program named by the
.BR shell
edit option. It shall pass two arguments to the program; the first
shall be
.BR \(mic ,
and the second shall be the expanded arguments to the
.BR !
command as a single argument.
.P
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
.IR ex
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
.BR warn
edit option is set.
.P
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>
characters 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>
characters. The specified lines shall be copied into the unnamed buffer
before they are replaced, and the unnamed buffer shall become a line-mode
buffer.
.P
If in
.IR ex
mode, a single
.BR '!' 
character shall be written when the program completes.
.P
This command shall be affected by the
.BR shell
and
.BR warn
edit options. If no lines are specified, this command shall be affected
by the
.BR autowrite
and
.BR writeany
edit options. If lines are specified, this command shall be affected by
the
.BR autoprint
edit option.
.br
.P
.IR "Current line" :
.IP " 1." 4
If no lines are specified, unchanged.
.IP " 2." 4
Otherwise, set to the last line read in, if any lines are read in.
.IP " 3." 4
Otherwise, set to the line before the first line of the lines
specified, if that line exists.
.IP " 4." 4
Otherwise, set to the first line of the edit buffer if the edit buffer
is not empty.
.IP " 5." 4
Otherwise, set to zero.
.P
.IR "Current column" :
If no lines are specified, unchanged. Otherwise, set to non-\c
<blank>.
.SS "Shift Left"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB]\fR <\fB[\fR< ...\fB][\fIcount\fB][\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
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
.BR shiftwidth
edit option. Only leading
<blank>
characters shall be deleted or changed into other
<blank>
characters in shifting; other characters shall not be affected.
.P
Lines to be shifted shall be copied into the unnamed buffer, which
shall become a line-mode buffer.
.P
This command shall be affected by the
.BR autoprint
edit option.
.P
.IR "Current line" :
Set to the last line in the lines specified.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Shift Right"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB]\fR >\fB[\fR> ...\fB][\fIcount\fB][\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
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
.BR shiftwidth
edit option. The shift shall be accomplished by adding
<blank>
characters as a prefix to the line or changing leading
<blank>
characters into other
<blank>
characters. Empty lines shall not be changed.
.P
Lines to be shifted shall be copied into the unnamed buffer, which
shall become a line-mode buffer.
.P
This command shall be affected by the
.BR autoprint
edit option.
.P
.IR "Current line" :
Set to the last line in the lines specified.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "<control>\(hyD"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
<control>-D
.fi \fR
.P
.RE
.RE
.P
Write the next
.IR n
lines, where
.IR n
is the minimum of the values of the
.BR scroll
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.
.P
.IR "Current line" :
Set to the last line written.
.P
.IR "Current column" :
Set to non-\c
<blank>.
.SS "Write Line Number"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI1addr\fB] \fR= \fB[\fIflags\fB]\fR
.fi \fR
.P
.RE
.RE
.P
If
.IR line
is not specified, it shall default to the last line in the edit buffer.
Write the line number of the specified line.
.P
.IR "Current line" :
Unchanged.
.P
.IR "Current column" :
Unchanged.
.SS "Execute"
.IP "\fISynopsis\fR:" 10
.sp -1v
.RS 10 
.sp
.RS 4
.nf
\fB
\fB[\fI2addr\fB]\fR @ \fIbuffer\fR
\fB[\fI2addr\fB]\fR * \fIbuffer\fR
.fi \fR
.P
.RE
.RE
.P
If no buffer is specified or is specified as
.BR '@' 
or
.BR '*' ,
the last buffer executed shall be used. If no previous buffer has been
executed, it shall be an error.
.P
For each line specified by the addresses, set the current line (\c
.BR '.' )
to the specified line, and execute the contents of the named
.IR buffer
(as they were at the time the
.BR @
command was executed) as
.IR ex
commands. For each line of a line-mode buffer, and all but the last
line of a character-mode buffer, the
.IR ex
command parser shall behave as if the line was terminated by a
<newline>.
.P
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
.IR ex
.BR :edit
command) an error message shall be written, and no more commands
resulting from the execution of this command shall be processed.
.P
.IR "Current line" :
As specified for the individual
.IR ex
commands.
.P
.IR "Current column" :
As specified for the individual
.IR ex
commands.
.SS "Regular Expressions in ex"
.P
The
.IR ex
utility shall support regular expressions that are a superset of the
basic regular expressions described in the Base Definitions volume of POSIX.1\(hy2008,
.IR "Section 9.3" ", " "Basic Regular Expressions".
A null regular expression (\c
.BR \(dq//\(dq )
shall be equivalent to the last regular expression encountered.
.P
Regular expressions can be used in addresses to specify lines and, in
some commands (for example, the
.BR substitute
command), to specify portions of a line to be substituted.
.P
The following constructs can be used to enhance the basic regular
expressions:
.IP "\fR\e<\fR" 6
Match the beginning of a
.IR word .
(See the definition of
.IR word
at the beginning of
.IR "Command Descriptions in ex".)
.IP "\fR\e>\fR" 6
Match the end of a
.IR word .
.IP "\fR~\fR" 6
Match the replacement part of the last
.BR substitute
command. The
<tilde>
(\c
.BR '~' )
character can be escaped in a regular expression to become a normal
character with no special meaning. The
<backslash>
shall be discarded.
.P
When the editor option
.BR magic
is not set, the only characters with special meanings shall be
.BR '^' 
at the beginning of a pattern,
.BR '$' 
at the end of a pattern, and
<backslash>.
The characters
.BR '.' ,
.BR '*' ,
.BR '[' ,
and
.BR '~' 
shall be treated as ordinary characters unless preceded by a
<backslash>;
when preceded by a
<backslash>
they shall regain their special meaning, or in the case of
<backslash>,
be handled as a single
<backslash>.
<backslash>
characters used to escape other characters shall be discarded.
.SS "Replacement Strings in ex"
.P
The character
.BR '&' 
(\c
.BR '\e&' 
if the editor option
.BR magic
is not set) in the replacement string shall stand for the text matched
by the pattern to be replaced. The character
.BR '~' 
(\c
.BR '\e~' 
if
.BR magic
is not set) shall be replaced by the replacement part of the previous
.BR substitute
command. The sequence
.BR '\en' ,
where
.IR n
is an integer, shall be replaced by the text matched by the
corresponding back-reference expression. If the corresponding
back-reference expression does not match, then the characters
.BR '\en' 
shall be replaced by the empty string.
.P
The strings
.BR '\el' ,
.BR '\eu' ,
.BR '\eL' ,
and
.BR '\eU' 
can be used to modify the case of elements in the replacement string
(using the
.BR '\e&' 
or
.BR \(dq\e\(dq digit)
notation. The string
.BR '\el' 
(\c
.BR '\eu' )
shall cause the character that follows to be converted to lowercase
(uppercase). The string
.BR '\eL' 
(\c
.BR '\eU' )
shall cause all characters subsequent to it to be converted to
lowercase (uppercase) as they are inserted by the substitution until
the string
.BR '\ee' 
or
.BR '\eE' ,
or the end of the replacement string, is encountered.
.P
Otherwise, any character following a
<backslash>
shall be treated as that literal character, and the escaping
<backslash>
shall be discarded.
.P
An example of case conversion with the
.BR s
command is as follows:
.sp
.RS 4
.nf
\fB
\fB:\fRp
\fBThe cat sat on the mat.
\fB:\fRs/\e<.at\e>/\eu&/gp
\fBThe Cat Sat on the Mat.
\fB:\fRs/S\e(.*\e)M/S\eU\e1\eeM/p
\fBThe Cat SAT ON THE Mat.\fR
.fi \fR
.P
.RE
.SS "Edit Options in ex"
.P
The
.IR ex
utility has a number of options that modify its behavior. These options
have default settings, which can be changed using the
.BR set
command.
.P
Options are Boolean unless otherwise specified.
.SS "autoindent, ai"
.P
[Default \fIunset\fR]
.P
If
.BR autoindent
is set, each line in input mode shall be indented (using first as many
<tab>
characters as possible, as determined by the editor option
.BR tabstop ,
and then using
<space>
characters) 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
.IR "\fIvi\fR\^"),
align to the first column.
.IP " 2." 4
Otherwise, if in open or visual mode, indentation for each line shall
be set as follows:
.RS 4 
.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>\(hyD
character in
.IR "Input Mode Commands in vi".
.IP " b." 4
Otherwise, it shall be set to the indentation of the previous current
line, if any; otherwise, to the first column.
.RE
.IP " 3." 4
For the
.IR ex
.BR a ,
.BR i ,
and
.BR c
commands, indentation for each line shall be set as follows:
.RS 4 
.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
.IR eof
character in
.IR "Scroll".
.IP " b." 4
Otherwise, if the command is the
.IR ex
.BR a
command, it shall be set to the line appended after, if any; otherwise
to the first column.
.IP " c." 4
Otherwise, if the command is the
.IR ex
.BR i
command, it shall be set to the line inserted before, if any; otherwise
to the first column.
.IP " d." 4
Otherwise, if the command is the
.IR ex
.BR c
command, it shall be set to the indentation of the line replaced.
.RE
.SS "autoprint, ap"
.P
[Default \fIset\fR]
.P
If
.BR autoprint
is set, the current line shall be written after each
.IR ex
command that modifies the contents of the current edit buffer, and
after each
.BR tag
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.
.IP " 2." 4
The command was executed as part of a
.BR global
or
.BR v
command or
.BR @
buffer execution.
.IP " 3." 4
The command was the form of the
.BR read
command that reads a file into the edit buffer.
.IP " 4." 4
The command was the
.BR append ,
.BR change ,
or
.BR insert
command.
.IP " 5." 4
The command was not terminated by a
<newline>.
.IP " 6." 4
The current line shall be written by a flag specified to the command;
for example,
.BR "delete #"
shall write the current line as specified for the flag modifier to the
.BR delete
command, and not as specified by the
.BR autoprint
edit option.
.SS "autowrite, aw"
.P
[Default \fIunset\fR]
.P
If
.BR autowrite
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
.IR ex
.BR write
command had been specified without arguments, before each command
affected by the
.BR autowrite
edit option is executed. Appending the character
.BR '!' 
to the command name of any of the
.IR ex
commands except
.BR '!' 
shall prevent the write. If the write fails, it shall be an error and
the command shall not be executed.
.SS "beautify, bf"
.P
[Default \fIunset\fR]
.P
If
.BR beautify
is set, all non-printable characters, other than
<tab>,
<newline>,
and
<form-feed>
characters, shall be discarded from text read in from files.
.SS "directory, dir"
.P
[Default \fIimplementation-defined\fR]
.P
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"
.P
[Default \fIunset\fR]
.P
Causes the presence of
.BR g
and
.BR c
suffixes on substitute commands to be remembered, and toggled by
repeating the suffixes.
.SS "errorbells, eb"
.P
[Default \fIunset\fR]
.P
If the editor is in
.IR ex
mode, and the terminal does not support a standout mode (such as
inverse video), and
.BR errorbells
is set, error messages shall be preceded by alerting the terminal.
.SS "exrc"
.P
[Default \fIunset\fR]
.P
If
.BR exrc
is set,
.IR ex
shall access any
.BR .exrc
file in the current directory, as described in
.IR "Initialization in ex and vi".
If
.BR exrc
is not set,
.IR ex
shall ignore any
.BR .exrc
file in the current directory during initialization, unless the current
directory is that named by the
.IR HOME
environment variable.
.SS "ignorecase, ic"
.P
[Default \fIunset\fR]
.P
If
.BR ignorecase
is set, characters that have uppercase and lowercase representations
shall have those representations considered as equivalent for purposes
of regular expression comparison.
.P
The
.BR ignorecase
edit option shall affect all remembered regular expressions; for
example, unsetting the
.BR ignorecase
edit option shall cause a subsequent
.IR vi
.BR n
command to search for the last basic regular expression in a
case-sensitive fashion.
.SS "list"
.P
[Default \fIunset\fR]
.P
If
.BR list
is set, edit buffer lines written while in
.IR ex
command mode shall be written as specified for the
.BR print
command with the
.BR l
flag specified. In open or visual mode, each edit buffer line shall be
displayed as specified for the
.IR ex
.BR print
command with the
.BR l
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
.BR '$' 
marking the end of the line.
.SS "magic"
.P
[Default \fIset\fR]
.P
If
.BR magic
is set, modify the interpretation of characters in regular expressions
and substitution replacement strings (see
.IR "Regular Expressions in ex"
and
.IR "Replacement Strings in ex").
.SS "mesg"
.P
[Default \fIset\fR]
.P
If
.BR mesg
is set, the permission for others to use the
.BR write
or
.BR talk
commands to write to the terminal shall be turned on while in open or
visual mode. The shell-level command
.IR mesg
.BR n
shall take precedence over any setting of the
.IR ex
.BR mesg
option; that is, if
.BR "mesg y"
was issued before the editor started (or in a shell escape), such as:
.sp
.RS 4
.nf
\fB
:!mesg y
.fi \fR
.P
.RE
.P
the
.BR mesg
option in
.IR ex
shall suppress incoming messages, but the
.BR mesg
option shall not enable incoming messages if
.BR "mesg n"
was issued.
.SS "number, nu"
.P
[Default \fIunset\fR]
.P
If
.BR number
is set, edit buffer lines written while in
.IR ex
command mode shall be written with line numbers, in the format
specified by the
.BR print
command with the
.BR #
flag specified. In
.IR ex
text input mode, each line shall be preceded by the line number it will
have in the file.
.P
In open or visual mode, each edit buffer line shall be displayed with a
preceding line number, in the format specified by the
.IR ex
.BR print
command with the
.BR #
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
.BR print
command.
.SS "paragraphs, para"
.P
[Default in the POSIX locale \fRIPLPPPQPP LIpplpipbp\fR]
.P
The
.BR paragraphs
edit option shall define additional paragraph boundaries for the open
and visual mode commands. The
.BR paragraphs
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"
.P
[Default \fIset\fR]
.P
If
.BR prompt
is set,
.IR ex
command mode input shall be prompted for with a
<colon>
(\c
.BR ':' );
when unset, no prompt shall be written.
.SS "readonly"
.P
[Default \fIsee text\fR]
.P
If the
.BR readonly
edit option is set, read-only mode shall be enabled (see
.IR "Write").
The
.BR readonly
edit option shall be initialized to set if either of the following
conditions are true:
.IP " *" 4
The command-line option
\(miR
was specified.
.IP " *" 4
Performing actions equivalent to the
\fIaccess\fR()
function called with the following arguments indicates that the file
lacks write permission:
.RS 4 
.IP " 1." 4
The current pathname is used as the
.IR path
argument.
.IP " 2." 4
The constant
.BR W_OK
is used as the
.IR amode
argument.
.RE
.P
The
.BR readonly
edit option may be initialized to set for other,
implementation-defined reasons. The
.BR readonly
edit option shall not be initialized to unset based on any special
privileges of the user or process. The
.BR readonly
edit option shall be reinitialized each time that the contents of the
edit buffer are replaced (for example, by an
.BR edit
or
.BR next
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"
.P
[Default \fIunset\fR]
.P
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"
.P
[Default \fIset\fR]
.P
If
.BR remap
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"
.P
[Default 5]
.P
The value of this
.BR report
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 " *" 4
An
.IR ex
or
.IR vi
editor command, other than
.BR open ,
.BR undo ,
or
.BR visual ,
that modifies at least the value of the
.BR report
edit option number of lines, and which is not part of an
.IR ex
.BR global
or
.BR v
command, or
.IR ex
or
.IR vi
buffer execution, shall cause an informational message to be written.
.IP " *" 4
An
.IR ex
.BR yank
or
.IR vi
.BR y
or
.BR Y
command, that copies at least the value of the
.BR report
edit option plus 1 number of lines, and which is not part of an
.IR ex
.BR global
or
.BR v
command, or
.IR ex
or
.IR vi
buffer execution, shall cause an informational message to be written.
.IP " *" 4
An
.IR ex
.BR global ,
.BR v ,
.BR open ,
.BR undo ,
or
.BR visual
command or
.IR ex
or
.IR vi
buffer execution, that adds or deletes a total of at least the value of
the
.BR report
edit option number of lines, and which is not part of an
.IR ex
.BR global
or
.BR v
command, or
.IR ex
or
.IR vi
buffer execution, shall cause an informational message to be written.
(For example, if 3 lines were added and 8 lines deleted during an
.IR ex
.BR visual
command, 5 would be the number compared against the
.BR report
edit option after the command completed.)
.SS "scroll, scr"
.P
[Default (number of lines in the display \(mi1)/2]
.P
The value of the
.BR scroll
edit option shall determine the number of lines scrolled by the
.IR ex
<control>\(hyD
and
.BR z
commands. For the
.IR vi
<control>\(hyD
and
<control>\(hyU
commands, it shall be the initial number of lines to scroll when no
previous
<control>\(hyD
or
<control>\(hyU
command has been executed.
.SS "sections"
.P
[Default in the POSIX locale \fRNHSHH HUnhsh\fR]
.P
The
.BR sections
edit option shall define additional section boundaries for the open and
visual mode commands. The
.BR sections
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"
.P
[Default from the environment variable
.IR SHELL ]
.P
The value of this option shall be a string. The default shall be taken
from the
.IR SHELL
environment variable. If the
.IR SHELL
environment variable is null or empty, the
.IR sh
(see
.IR "\fIsh\fR\^")
utility shall be the default.
.SS "shiftwidth, sw"
.P
[Default 8]
.P
The value of this option shall give the width in columns of an
indentation level used during autoindentation and by the shift commands
(\c
.BR <
and
.BR > ).
.SS "showmatch, sm"
.P
[Default \fIunset\fR]
.P
The functionality described for the
.BR showmatch
edit option need not be supported on block-mode terminals or terminals
with insufficient capabilities.
.P
If
.BR showmatch
is set, in open or visual mode, when a
.BR ')' 
or
.BR '}' 
is typed, if the matching
.BR '(' 
or
.BR '{' 
is currently visible on the display, the matching
.BR '(' 
or
.BR '{' 
shall be flagged moving the cursor to its location for an unspecified
amount of time.
.SS "showmode"
.P
[Default \fIunset\fP]
.P
If
.BR showmode
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"
.P
[Default \fIunset\fR]
.P
If
.BR slowopen
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
.IR "Input Mode Commands in vi").
.SS "tabstop, ts"
.P
[Default 8]
.P
The value of this edit option shall specify the column boundary used by
a
<tab>
in the display (see
.IR "autoprint" ", " "ap"
and
.IR "Input Mode Commands in vi").
.SS "taglength, tl"
.P
[Default zero]
.P
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"
.P
[Default \fIsee text\fP]
.P
The value of this edit option shall be a string of
<blank>-delimited
pathnames of files used by the
.BR tag
command. The default value is unspecified.
.SS "term"
.P
[Default from the environment variable
.IR TERM ]
.P
The value of this edit option shall be a string. The default shall be
taken from the
.IR TERM
variable in the environment. If the
.IR TERM
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.
.P
The results are unspecified if the user changes the value of the term
edit option after editor initialization.
.SS "terse"
.P
[Default \fIunset\fR]
.P
If
.BR terse
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"
.P
[Default \fIset\fR]
.P
If
.BR warn
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
.BR !
commands (see
.IR "Escape").
.SS "window"
.P
[Default \fIsee text\fR]
.P
A value used in open and visual mode, by the
<control>\(hyB
and
<control>\(hyF
commands, and, in visual mode, to specify the number of lines displayed
when the screen is repainted.
.P
If the
.BR \(miw
command-line option is not specified, the default value shall be set to
the value of the
.IR LINES
environment variable. If the
.IR LINES
environment variable is empty or null, the default shall be the number
of lines in the display minus 1.
.P
Setting the
.BR window
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
.BR \(miw
option or the
.IR LINES
environment variable) shall cause the
.BR window
edit option to be set to the number of lines in the display minus 1.
.P
The baud rate of the terminal line may change the default in an
implementation-defined manner.
.SS "wrapmargin, wm"
.P
[Default 0]
.P
If the value of this edit option is zero, it shall have no effect.
.P
If not in the POSIX locale, the effect of this edit option is
implementation-defined.
.P
Otherwise, it shall specify a number of columns from the ending margin
of the terminal.
.P
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
.BR wrapmargin
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>
characters 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.
.IP " 2." 4
Otherwise, if there are one or more
<blank>
characters on the current line immediately preceding the last group of
inserted non-\c
<blank>
characters which was entered during the execution of the current text
input command, the
<blank>
characters shall be replaced as if the user had entered a single
<newline>
instead.
.P
If the
.BR autoindent
edit option is set, and the events described in 1. or 2. are performed,
any
<blank>
characters at or after the cursor in the current line shall be discarded.
.P
The ending margin shall be determined by the system or overridden by
the user, as described for
.IR COLUMNS
in the ENVIRONMENT VARIABLES section and the Base Definitions volume of POSIX.1\(hy2008,
.IR "Chapter 8" ", " "Environment Variables".
.SS "wrapscan, ws"
.P
[Default \fIset\fR]
.P
If
.BR wrapscan
is set, searches (the
.IR ex
.BR /
or
.BR ?
addresses, or open and visual mode
.BR / ,
.BR ? ,
.BR N ,
and
.BR n
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"
.P
[Default \fIunset\fR]
.P
If
.BR writeany
is set, some of the checks performed when executing the
.IR ex
.BR write
commands shall be inhibited, as described in editor option
.BR autowrite .
.SH "EXIT STATUS"
The following exit values shall be returned:
.IP "\00" 6
Successful completion.
.IP >0 6
An error occurred.
.SH "CONSEQUENCES OF ERRORS"
When any error is encountered and the standard input is not a terminal
device file,
.IR ex
shall not write the file or return to command or text input mode, and
shall terminate with a non-zero exit status.
.P
Otherwise, when an unrecoverable error is encountered, it shall be
equivalent to a SIGHUP asynchronous event.
.P
Otherwise, when an error is encountered, the editor shall behave as
specified in
.IR "Command Line Parsing in ex".
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
If a SIGSEGV signal is received while
.IR ex
is saving a file, the file might not be successfully saved.
.P
The
.BR next
command can accept more than one file, so usage such as:
.sp
.RS 4
.nf
\fB
next `ls [abc]*`
.fi \fR
.P
.RE
.P
is valid; it would not be valid for the
.BR edit
or
.BR read
commands, for example, because they expect only one file and
unspecified results occur.
.SH EXAMPLES
None.
.SH RATIONALE
The
.IR ex /\c
.IR vi
specification is based on the historical practice found in the 4 BSD and
System V implementations of
.IR ex
and
.IR vi .
.P
A
.IR "restricted editor"
(both the historical
.IR red
utility and modifications to
.IR ex )
were considered and rejected for inclusion. Neither option provided the
level of security that users might expect.
.P
It is recognized that
.IR ex
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
.IR ex
implementation should provide the full set of capabilities on all
terminals capable of supporting them.
.SS "Options"
.P
The
.BR \(mic
replacement for
.BR + \c
.IR command
was inspired by the
.BR \(mie
option of
.IR sed .
Historically, all such commands (see
.BR edit
and
.BR next
as well) were executed from the last line of the edit buffer. This
meant, for example, that
.BR \(dq+/pattern\(dq 
would fail unless the
.BR wrapscan
option was set. POSIX.1\(hy2008 requires conformance to historical practice. The
.BR \(pl \c
.IR command
option is no longer specified by POSIX.1\(hy2008 but may be present in
some implementations. Historically, some implementations restricted the
.IR ex
commands that could be listed as part of the command line arguments.
For consistency, POSIX.1\(hy2008 does not permit these restrictions.
.P
In historical implementations of the editor, the
.BR \(miR
option (and the
.BR readonly
edit option) only prevented overwriting of files; appending to files
was still permitted, mapping loosely into the
.IR csh
.BR noclobber
variable. Some implementations, however, have not followed this
semantic, and
.BR readonly
does not permit appending either. POSIX.1\(hy2008 follows the latter practice,
believing that it is a more obvious and intuitive meaning of
.BR readonly .
.P
The
.BR \(mis
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''.
.P
The
.BR \(mit
option was required because the
.IR ctags
utility appears in POSIX.1\(hy2008 and the option is available in all historical
implementations of
.IR ex .
.P
Historically, the
.IR ex
and
.IR vi
utilities accepted a
.BR \(mix
option, which did encryption based on the algorithm found in the
historical
.IR crypt
utility. The
.BR \(mix
option for encryption, and the associated
.IR crypt
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"
.P
An end-of-file condition is not equivalent to an end-of-file character.
A common end-of-file character,
<control>\(hyD,
is historically an
.IR ex
command.
.P
There was no maximum line length in historical implementations of
.IR ex .
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
.IR ex
and to aid test suite writers in their development of realistic tests
that exercise this limit.
.SS "Input Files"
.P
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
.IR ex
and
.IR vi
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
.IR ex
and
.IR vi
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
.IR ex
or
.IR vi
implementation be required to handle files other than text files.
.P
The paragraph in the INPUT FILES section, ``By default, .\|.\|.'', is
intended to close a long-standing security problem in
.IR ex
and
.IR vi ;
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
.BR \(dqex:\(dq 
or
.BR \(dqvi:\(dq 
(and, apparently,
.BR \(dqei:\(dq 
or
.BR \(dqvx:\(dq )
to be a line containing editor commands, and
.IR ex
interprets all the text up to the next
.BR ':' 
or
<newline>
as a command. Consider the consequences, for example, of an
unsuspecting user using
.IR ex
or
.IR vi
as the editor when replying to a mail message in which a line such as:
.sp
.RS 4
.nf
\fB
ex:! rm \(mirf :
.fi \fR
.P
.RE
.P
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
.IR ex
and
.IR vi .
.SS "Asynchronous Events"
.P
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.
.P
Historically, SIGQUIT was ignored by
.IR ex ,
but was the equivalent of the
.BR Q
command in visual mode; that is, it exited visual mode and entered
.IR ex
mode. POSIX.1\(hy2008 permits, but does not require, this behavior. Historically,
SIGINT was often used by
.IR vi
users to terminate text input mode (\c
<control>\(hyC
is often easier to enter than
<ESC>).
Some implementations of
.IR vi
alerted the terminal on this event, and some did not. POSIX.1\(hy2008 requires
that SIGINT behave identically to
<ESC>,
and that the terminal not be alerted.
.P
Historically, suspending the
.IR ex
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. POSIX.1\(hy2008 is silent on this issue; implementations are
encouraged to follow historical practice, where possible.
.P
Historically, the
.IR vi
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
.IR exec s
an application that then
.IR exec s
.IR vi
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
.IR curses
package did not handle SIGTSTP safely, and the receipt of SIGTSTP at
the wrong time would cause them to crash. POSIX.1\(hy2008 is silent on this issue;
implementations are encouraged to treat suspension as an asynchronous
event if possible.
.P
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. POSIX.1\(hy2008 permits this behavior, noting that the
.BR undo
command is required to be able to undo these partially completed
commands.
.P
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"
.P
For
.IR ex /\c
.IR vi ,
diagnostic messages are those messages reported as a result of a failed
attempt to invoke
.IR ex
or
.IR vi ,
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"
.P
If an
.IR ex
command (other than
.BR cd ,
.BR chdir ,
or
.BR source )
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
.IR ex
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
.BR next
command) and the alternate pathname will be set to the previous
current pathname, if there was one.
.IP " 2." 4
In the case of the file read/write forms of the
.BR read
and
.BR write
commands, if there is no current pathname, the current pathname will
be set to the filename argument.
.IP " 3." 4
Otherwise, the alternate pathname will be set to the filename
argument.
.P
For example,
.BR ":edit foo"
and
.BR ":recover foo" ,
when successful, set the current pathname, and, if there was a
previous current pathname, the alternate pathname. The commands
.BR :write ,
.BR !command ,
and
.BR :edit
set neither the current or alternate pathnames. If the
.BR ":edit foo"
command were to fail for some reason, the alternate pathname would be
set. The
.BR read
and
.BR write
commands set the alternate pathname to their
.IR file
argument, unless the current pathname is not set, in which case they
set the current pathname to their
.IR file
arguments. The alternate pathname was not historically set by the
.BR :source
command. POSIX.1\(hy2008 requires conformance to historical practice.
Implementations adding commands that take filenames as arguments are
encouraged to set the alternate pathname as described here.
.P
Historically,
.IR ex
and
.IR vi
read the
.BR .exrc
file in the
.IR $HOME
directory twice, if the editor was executed in the
.IR $HOME
directory. POSIX.1\(hy2008 prohibits this behavior.
.P
Historically, the 4 BSD
.IR ex
and
.IR vi
read the
.IR $HOME
and local
.BR .exrc
files if they were owned by the real ID of the user, or the
.BR sourceany
option was set, regardless of other considerations. This was a security
problem because it is possible to put normal UNIX system commands
inside a
.BR .exrc
file. POSIX.1\(hy2008 does not specify the
.BR sourceany
option, and historical implementations are encouraged to delete it.
.P
The
.BR .exrc
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
.BR .exrc
files in their home directories.
.P
System V Release 3.2 and later
.IR vi
implementations added the option
.BR [no]exrc .
The behavior is that local
.BR .exrc
files are read-only if the
.BR exrc
option is set. The default for the
.BR exrc
option was off, so by default, local
.BR .exrc
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 POSIX.1\(hy2008 can do. The
implementation-defined exception is intended to permit groups to have
local
.BR .exrc
files that are shared by users, by creating pseudo-users to own the
shared files.
.P
POSIX.1\(hy2008 does not mention system-wide
.IR ex
and
.IR vi
start-up files. While they exist in several implementations of
.IR ex
and
.IR vi ,
they are not present in any implementations considered historical
practice by POSIX.1\(hy2008. 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
.IR EXINIT
variable,
.BR $HOME/.exrc ,
or local
.BR .exrc
files are evaluated.
.P
Historically, any
.IR ex
command could be entered in the
.IR EXINIT
variable or the
.BR .exrc
file, although ones requiring that the edit buffer already contain
lines of text generally caused historical implementations of the editor
to drop
.BR core .
POSIX.1\(hy2008 requires that any
.IR ex
command be permitted in the
.IR EXINIT
variable and
.BR .exrc
files, for simplicity of specification and consistency, although many
of them will obviously fail under many circumstances.
.P
The initialization of the contents of the edit buffer uses the phrase
``the effect shall be'' with regard to various
.IR ex
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
.BR .exrc
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
.IR ex
commands.
.P
Historically, the
.BR \(mit
option behaved as if the tag search were a
.BR + \c
.IR command ;
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
.BR wrapscan
edit option was not set. POSIX.1\(hy2008 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.
.P
Historically, the empty edit buffer presented for editing when a file
was not specified by the user was unnamed. This is permitted by POSIX.1\(hy2008;
however, implementations are encouraged to provide users a temporary
filename for this buffer because it permits them the use of
.IR ex
commands that use the current pathname during temporary edit
sessions.
.P
Historically, the file specified using the
.BR \(mit
option was not part of the current argument list. This practice is
permitted by POSIX.1\(hy2008; however, implementations are encouraged to include
its name in the current argument list for consistency.
.P
Historically, the
.BR \(mic
command was generally not executed until a file that already exists was
edited. POSIX.1\(hy2008 requires conformance to this historical practice.
Commands that could cause the
.BR \(mic
command to be executed include the
.IR ex
commands
.BR edit ,
.BR next ,
.BR recover ,
.BR rewind ,
and
.BR tag ,
and the
.IR vi
commands
<control>\(hy^
and
<control>\(hy].
Historically, reading a file into an edit buffer did not cause the
.BR \(mic
command to be executed (even though it might set the current pathname)
with the exception that it did cause the
.BR \(mic
command to be executed if: the editor was in
.IR ex
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, POSIX.1\(hy2008 does not permit this behavior.
.P
Historically, the
.BR \(mir
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 4
.nf
\fB
vi \(mir *.c
.fi \fR
.P
.RE
.P
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
.BR \(mir
if
.BR \(mit
was specified or did not support command line
.IR file
arguments with the
.BR \(mit
option. For consistency and simplicity of specification, POSIX.1\(hy2008
disallows these special cases, and requires that recovery be attempted
the first time each file is edited.
.P
Historically,
.IR vi
initialized the
.BR `
and
.BR '
marks, but
.IR ex
did not. This meant that if the first command in
.IR ex
mode was
.BR visual
or if an
.IR ex
command was executed first (for example,
.IR vi
+10
.IR file ),
.IR vi
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, POSIX.1\(hy2008 requires that they
always be initialized if in open or visual mode, or if in
.IR ex
mode and the edit buffer is not empty. Not initializing it in
.IR ex
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"
.P
Historically,
.IR ex
and
.IR vi
accepted the additional addressing forms
.BR '\e/' 
and
.BR '\e?' .
They were equivalent to
.BR \(dq//\(dq 
and
.BR \(dq??\(dq ,
respectively. They are not required by POSIX.1\(hy2008, mostly because nobody can
remember whether they ever did anything different historically.
.P
Historically,
.IR ex
and
.IR vi
permitted an address of zero for several commands, and permitted the
.BR %
address in empty files for others. For consistency, POSIX.1\(hy2008 requires
support for the former in the few commands where it makes sense, and
disallows it otherwise. In addition, because POSIX.1\(hy2008 requires that
.BR %
be logically equivalent to
.BR \(dq1,$\(dq ,
it is also supported where it makes sense and disallowed otherwise.
.P
Historically, the
.BR %
address could not be followed by further addresses. For consistency and
simplicity of specification, POSIX.1\(hy2008 requires that additional addresses
be supported.
.P
All of the following are valid
.IR addresses :
.IP "\fR+++\fP" 10
Three lines after the current line.
.IP "\fR/\fIre\fR/\(mi\fR" 10
One line before the next occurrence of
.IR re .
.IP "\fR\(mi2\fR" 10
Two lines before the current line.
.IP "\fR3\0\(mi\|\(mi\|\(mi\|\(mi\02\fR" 10
Line one (note intermediate negative address).
.IP "\fR1\02\03\fR" 10
Line six.
.P
Any number of addresses can be provided to commands taking addresses;
for example,
.BR \(dq1,2,3,4,5p\(dq 
prints lines 4 and 5, because two is the greatest valid number of
addresses accepted by the
.BR print
command. This, in combination with the
<semicolon>
delimiter, permits users to create commands based on ordered patterns
in the file. For example, the command
.BR "3;/foo/;+2print"
will display the first line after line 3 that contains the pattern
.IR foo ,
plus the next two lines. Note that the address
.BR "3;"
must be evaluated before being discarded because the search origin for
the
.BR /foo/
command depends on this.
.P
Historically, values could be added to addresses by including them
after one or more
<blank>
characters; for example,
.BR "3\0\(mi\05p"
wrote the seventh line of the file, and
.BR "/foo/\05"
was the same as
.BR "/foo/+5" .
However, only absolute values could be added; for example,
.BR "5\0/foo/"
was an error. POSIX.1\(hy2008 requires conformance to historical practice.
Address offsets are separately specified from addresses because they
could historically be provided to visual mode search commands.
.P
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, POSIX.1\(hy2008 requires it for leading
<semicolon>
addresses as well.
.P
Historically,
.IR ex
and
.IR vi
accepted the
.BR '^' 
character as both an address and as a flag offset for commands. In both
cases it was identical to the
.BR '\(mi' 
character. POSIX.1\(hy2008 does not require or prohibit this behavior.
.P
Historically, the enhancements to basic regular expressions could be
used in addressing; for example,
.BR '~' ,
.BR '\e<' ,
and
.BR '\e>' .
POSIX.1\(hy2008 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"
.P
Historical
.IR ex
command parsing was even more complex than that described here. POSIX.1\(hy2008
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
POSIX.1\(hy2008; however, users are not expected to notice any of these changes.
Most of the complexity in
.IR ex
parsing is to handle three special termination cases:
.IP " 1." 4
The
.BR ! ,
.BR global ,
.BR v ,
and the filter versions of the
.BR read
and
.BR write
commands are delimited by
<newline>
characters (they can contain
<vertical-line>
characters that are usually shell pipes).
.IP " 2." 4
The
.BR ex ,
.BR edit ,
.BR next ,
and
.BR visual
in open and visual mode commands all take
.IR ex
commands, optionally containing
<vertical-line>
characters, as their first arguments.
.IP " 3." 4
The
.BR s
command takes a regular expression as its first argument, and uses the
delimiting characters to delimit the command.
.P
Historically,
<vertical-line>
characters in the
.BR + \c
.IR command
argument of the
.BR ex ,
.BR edit ,
.BR next ,
.BR vi ,
and
.BR visual
commands, and in the
.IR pattern
and
.IR replacement
parts of the
.BR s
command, did not delimit the command, and in the filter cases for
.BR read
and
.BR write ,
and the
.BR ! ,
.BR global ,
and
.BR v
commands, they did not delimit the command at all. For example, the
following commands are all valid:
.sp
.RS 4
.nf
\fB
\fB:\fRedit +25 | s/abc/ABC/ file.c
\fB:\fRs/ | /PIPE/
\fB:\fRread !spell % | columnate
\fB:\fRglobal/pattern/p | l
\fB:\fRs/a/b/ | s/c/d | set
.fi \fR
.P
.RE
.P
Historically, empty or
<blank>
filled lines in
.BR .exrc
files and
.BR source d
files (as well as
.IR EXINIT
variables and
.IR ex
command scripts) were treated as default commands; that is,
.BR print
commands. POSIX.1\(hy2008 specifically requires that they be ignored when
encountered in
.BR .exrc
and
.BR source d
files to eliminate a common source of new user error.
.P
Historically,
.IR ex
commands with multiple adjacent (or
<blank>-separated)
vertical lines were handled oddly when executed from
.IR ex
mode. For example, the command
.BR "|||"
<carriage-return>,
when the cursor was on line 1, displayed lines 2, 3, and 5 of the file.
In addition, the command
.BR |
would only display the line after the next line, instead of the next
two lines. The former worked more logically when executed from
.IR vi
mode, and displayed lines 2, 3, and 4. POSIX.1\(hy2008 requires the
.IR vi
behavior; that is, a single default command and line number increment
for each command separator, and trailing
<newline>
characters after
<vertical-line>
separators are discarded.
.P
Historically,
.IR ex
permitted a single extra
<colon>
as a leading command character; for example,
.BR ":g/pattern/:p"
was a valid command. POSIX.1\(hy2008 generalizes this to require that any number
of leading
<colon>
characters be stripped.
.P
Historically, any prefix of the
.BR delete
command could be followed without intervening
<blank>
characters by a flag character because in the command
.BR "d\0p" ,
.IR p
is interpreted as the buffer
.IR p .
POSIX.1\(hy2008 requires conformance to historical practice.
.P
Historically, the
.BR k
command could be followed by the mark name without intervening
<blank>
characters. POSIX.1\(hy2008 requires conformance to historical practice.
.P
Historically, the
.BR s
command could be immediately followed by flag and option characters;
for example,
.BR "s/e/E/|s|sgc3p"
was a valid command. However, flag characters could not stand alone;
for example, the commands
.BR sp
and
.BR s\0l
would fail, while the command
.BR sgp
and
.BR "s\0gl"
would succeed. (Obviously, the
.BR '#' 
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
.BR s/e/E/pg
would fail, while the command
.BR s/e/E/gp
would succeed. POSIX.1\(hy2008 requires conformance to historical practice.
.P
Historically, the first command name that had a prefix matching the
input from the user was the executed command; for example,
.BR ve ,
.BR ver ,
and
.BR vers
all executed the
.BR version
command. Commands were in a specific order, however, so that
.BR a
matched
.BR append ,
not
.BR abbreviate .
POSIX.1\(hy2008 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.
.P
Historical implementations of
.IR ex
and
.IR vi
did not correctly handle multiple
.IR ex
commands, separated by
<vertical-line>
characters, that entered or exited visual mode or the editor. Because
implementations of
.IR vi
exist that do not exhibit this failure mode, POSIX.1\(hy2008 does not permit it.
.P
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
.BR '!' 
character, except as specified for the exceptions, the
.BR delete ,
.BR k ,
and
.BR s
commands.
.P
Historically, the repeated execution of the
.IR ex
default
.BR print
commands (\c
<control>\(hyD,
.IR eof ,
<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. POSIX.1\(hy2008 does not require this behavior because it
may be impossible in some situations; however, implementations are
strongly encouraged to provide this semantic if possible.
.P
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 4
.nf
\fB
:edit +25 file.c | s/abc/ABC/ | 1
.fi \fR
.P
.RE
.P
was a valid command, and the substitution was attempted in the newly
edited file. POSIX.1\(hy2008 requires conformance to historical practice. The
following commands are examples that exercise the
.IR ex
parser:
.sp
.RS 4
.nf
\fB
echo 'foo | bar' > file1; echo 'foo/bar' > file2;
vi
:edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\e//SLASH/ | wq
.fi \fR
.P
.RE
.P
Historically, there was no protection in editor implementations to
avoid
.IR ex
.BR global ,
.BR v ,
.BR @ ,
or
.BR *
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, POSIX.1\(hy2008 requires that changing the edit buffer during a
.BR global
or
.BR v
command, or during a
.BR @
or
.BR *
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.
.P
The
.IR ex
command quoting required by POSIX.1\(hy2008 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,
.BR ":edit\0foo\e\e\e\0bar"
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
.BR edit ,
.BR ex ,
.BR next ,
or
.BR visual
command at all. POSIX.1\(hy2008 extends historical practice, requiring that
quoting behavior be made consistent across all
.IR ex
commands, except for the
.BR map ,
.BR unmap ,
.BR abbreviate ,
and
.BR unabbreviate
commands, which historically used
<control>\(hyV
instead of
<backslash>
characters for quoting. For those four commands, POSIX.1\(hy2008 requires
conformance to historical practice.
.P
Backslash quoting in
.IR ex
is non-intuitive.
<backslash>-escapes
are ignored unless they escape a special character; for example, when
performing
.IR file
argument expansion, the string
.BR \(dq\e\e%\(dq 
is equivalent to
.BR '\e%' ,
not \fR"\e<\fIcurrent\ pathname\fR>"\fR.
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
.BR '\el' 
sequence in substitute replacement patterns, because the character
.BR 'l' 
is not special to any parsing layer above it.
.P
<control>\(hyV
quoting in
.IR ex
is slightly different from backslash quoting. In the four commands
where
<control>\(hyV
quoting applies (\c
.BR abbreviate ,
.BR unabbreviate ,
.BR map ,
and
.BR unmap ),
any character may be escaped by a
<control>\(hyV
whether it would have a special meaning or not. POSIX.1\(hy2008 requires
conformance to historical practice.
.P
Historical implementations of the editor did not require delimiters
within character classes to be escaped; for example, the command
.BR ":s/[/]//"
on the string
.BR \(dqxxx/yyy\(dq 
would delete the
.BR '/' 
from the string. POSIX.1\(hy2008 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.
.P
Historically, quoting
<newline>
characters in
.IR ex
commands was handled inconsistently. In most cases, the
<newline>
character always terminated the command, regardless of any preceding
escape character, because
<backslash>
characters did not escape
<newline>
characters for most
.IR ex
commands. However, some
.IR ex
commands (for example,
.BR s ,
.BR map ,
and
.BR abbreviation )
permitted
<newline>
characters to be escaped (although in the case of
.BR map
and
.BR abbreviation ,
<control>\(hyV
characters escaped them instead of
<backslash>
characters). This was true in not only the command line, but also
.BR .exrc
and
.BR source d
files. For example, the command:
.sp
.RS 4
.nf
\fB
map = foo<control-V><newline>bar
.fi \fR
.P
.RE
.P
would succeed, although it was sometimes difficult to get the
<control>\(hyV
and the inserted
<newline>
passed to the
.IR ex
parser. For consistency and simplicity of specification, POSIX.1\(hy2008 requires
that it be possible to escape
<newline>
characters in
.IR ex
commands at all times, using
<backslash>
characters for most
.IR ex
commands, and using
<control>\(hyV
characters for the
.BR map
and
.BR abbreviation
commands. For example, the command
.BR print \c
<newline>\c
.BR list
is required to be parsed as the single command
.BR print \c
<newline>\c
.BR list .
While this differs from historical practice, POSIX.1\(hy2008 developers believed
it unlikely that any script or user depended on the historical
behavior.
.P
Historically, an error in a command specified using the
.BR \(mic
option did not cause the rest of the
.BR \(mic
commands to be discarded. POSIX.1\(hy2008 disallows this for consistency with
mapped keys, the
.BR @ ,
.BR global ,
.BR source ,
and
.BR v
commands, the
.IR EXINIT
environment variable, and the
.BR .exrc
files.
.SS "Input Editing in ex"
.P
One of the common uses of the historical
.IR ex
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, POSIX.1\(hy2008 requires that
.IR ex
be implemented using canonical mode input processing, as was done
historically.
.P
POSIX.1\(hy2008 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
.IR ex ,
although they must have the required effect. Implementations that
resolve them after the line has been ended using a
<newline>
or
<control>\(hyM
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.
.P
Historically, when the
.IR eof
character was used to decrement the
.BR autoindent
level, the cursor moved to display the new end of the
.BR autoindent
characters, but did not move the cursor to a new line, nor did it erase
the
<control>\(hyD
character from the line. POSIX.1\(hy2008 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>\(hyD
character on the line should be erased.
.P
POSIX.1\(hy2008 does not require the historical 4 BSD input editing character
``reprint'', traditionally
<control>\(hyR,
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, POSIX.1\(hy2008 makes no requirements about this
functionality. Implementations are strongly urged to make this
historical functionality available, if possible.
.P
Historically,
<control>\(hyQ
did not perform a literal next function in
.IR ex ,
as it did in
.IR vi .
POSIX.1\(hy2008 requires conformance to historical practice to avoid breaking
historical
.IR ex
scripts and
.BR .exrc
files.
.SS "eof"
.P
Whether the
.IR eof
character immediately modifies the
.BR autoindent
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.
.P
The specification of the handling of the
.IR eof
character differs from historical practice only in that
.IR eof
characters are not discarded if they follow normal characters in the
text input. Historically, they were always discarded.
.SS "Command Descriptions in ex"
.P
Historically, several commands (for example,
.BR global ,
.BR v ,
.BR visual ,
.BR s ,
.BR write ,
.BR wq ,
.BR yank ,
.BR ! ,
.BR < ,
.BR > ,
.BR & ,
and
.BR ~ )
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). POSIX.1\(hy2008 requires this behavior for such commands and
disallows it otherwise, for consistency and simplicity of
specification.
.P
A count to an
.IR ex
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
.BR "1,6print"
would fail, but the command
.BR "1print300"
would succeed. POSIX.1\(hy2008 requires conformance to historical practice.
.P
Historically, the use of flags in
.IR ex
commands could be obscure. General historical practice was as described
by POSIX.1\(hy2008, but there were some special cases. For instance, the
.BR list ,
.BR number ,
and
.BR print
commands ignored trailing address offsets; for example,
.BR "3p\0+++#"
would display line 3, and 3 would be the current line after the
execution of the command. The
.BR open
and
.BR visual
commands ignored both the trailing offsets and the trailing flags.
Also, flags specified to the
.BR open
and
.BR visual
commands interacted badly with the
.BR list
edit option, and setting and then unsetting it during the open/visual
session would cause
.IR vi
to stop displaying lines in the specified format. For consistency and
simplicity of specification, POSIX.1\(hy2008 does not permit any of these
exceptions to the general rule.
.P
POSIX.1\(hy2008 uses the word
.IR copy
in several places when discussing buffers. This is not intended to
imply implementation.
.P
Historically,
.IR ex
users could not specify numeric buffers because of the ambiguity this
would cause; for example, in the command
.BR "3\0delete\02" ,
it is unclear whether 2 is a buffer name or a
.IR count .
POSIX.1\(hy2008 requires conformance to historical practice by default, but does
not preclude extensions.
.P
Historically, the contents of the unnamed buffer were frequently
discarded after commands that did not explicitly affect it; for
example, when using the
.BR edit
command to switch files. For consistency and simplicity of
specification, POSIX.1\(hy2008 does not permit this behavior.
.P
The
.IR ex
utility did not historically have access to the numeric buffers, and,
furthermore, deleting lines in
.IR ex
did not modify their contents. For example, if, after doing a delete in
.IR vi ,
the user switched to
.IR ex ,
did another delete, and then switched back to
.IR vi ,
the contents of the numeric buffers would not have changed. POSIX.1\(hy2008
requires conformance to historical practice. Numeric buffers are
described in the
.IR ex
utility in order to confine the description of buffers to a single
location in POSIX.1\(hy2008.
.P
The metacharacters that trigger shell expansion in
.IR file
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
.BR shellmeta
string edit option.
.P
Historically,
.IR ex
commands executed from
.IR vi
refreshed the screen when it did not strictly need to do so; for
example,
.BR ":!date\0>\0/dev/null"
does not require a screen refresh because the output of the UNIX
.IR date
command requires only a single line of the screen. POSIX.1\(hy2008 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"
.P
Historical practice was that characters that were entered as part of an
abbreviation replacement were subject to
.BR map
expansions, the
.BR showmatch
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. POSIX.1\(hy2008 requires conformance to historical practice.
Historical practice was that whenever a non-word character (that had
not been escaped by a
<control>\(hyV)
was entered after a word character,
.IR vi
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>
characters, which always delimited the abbreviation.
.P
This means that, for the abbreviation to work, the
.IR lhs
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
.IR lhs ,
and there can be no
<blank>
characters in the
.IR lhs .
In addition, because of the historical quoting rules, it was impossible
to enter a literal
<control>\(hyV
in the
.IR lhs .
POSIX.1\(hy2008 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.
.br
.P
For example, the following abbreviations will work:
.sp
.RS 4
.nf
\fB
:ab (p  REPLACE
:ab p   REPLACE
:ab ((p REPLACE
.fi \fR
.P
.RE
.P
The following abbreviations will not work:
.sp
.RS 4
.nf
\fB
:ab (   REPLACE
:ab (pp REPLACE
.fi \fR
.P
.RE
.P
Historical practice is that words on the
.IR vi
colon command line were subject to abbreviation expansion, including
the arguments to the
.BR abbrev
(and more interestingly) the
.BR unabbrev
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 POSIX.1\(hy2008. However, the following sequence:
.sp
.RS 4
.nf
\fB
:ab foo bar
:ab foo baz
.fi \fR
.P
.RE
.P
resulted in the addition of an abbreviation of
.BR \(dqbaz\(dq 
for the string
.BR \(dqbar\(dq 
in historical
.IR ex /\c
.IR vi ,
and the sequence:
.sp
.RS 4
.nf
\fB
:ab foo1 bar
:ab foo2 bar
:unabbreviate foo2
.fi \fR
.P
.RE
.P
deleted the abbreviation
.BR \(dqfoo1\(dq ,
not
.BR \(dqfoo2\(dq .
These behaviors are not permitted by POSIX.1\(hy2008 because they clearly violate
the expectations of the user.
.P
It was historical practice that
<control>\(hyV,
not
<backslash>,
characters be interpreted as escaping subsequent characters in the
.BR abbreviate
command. POSIX.1\(hy2008 requires conformance to historical practice; however, it
should be noted that an abbreviation containing a
<blank>
will never work.
.SS "Append"
.P
Historically, any text following a
<vertical-line>
command separator after an
.BR append ,
.BR change ,
or
.BR insert
command became part of the insert text. For example, in the command:
.sp
.RS 4
.nf
\fB
:g/pattern/append|stuff1
.fi \fR
.P
.RE
.P
a line containing the text
.BR \(dqstuff1\(dq 
would be appended to each line matching pattern. It was also
historically valid to enter:
.sp
.RS 4
.nf
\fB
:append|stuff1
stuff2
\&.
.fi \fR
.P
.RE
.P
and the text on the
.IR ex
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
.BR '.' 
lines) to terminate text input mode in this case. POSIX.1\(hy2008 requires
conformance to historical practice, but disallows the historical need
for multiple terminating lines.
.SS "Change"
.P
See the RATIONALE for the
.BR append
command. Historical practice for cursor positioning after the change
command when no text is input, is as described in POSIX.1\(hy2008. 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. POSIX.1\(hy2008 disallows this modification for
consistency.
.P
Historically, the
.BR change
command did not support buffer arguments, although some implementations
allow the specification of an optional buffer. This behavior is neither
required nor disallowed by POSIX.1\(hy2008.
.SS "Change Directory"
.P
A common extension in
.IR ex
implementations is to use the elements of a
.BR cdpath
edit option as prefix directories for
.IR path
arguments to
.BR chdir
that are relative pathnames and that do not have
.BR '.' 
or
.BR \(dq..\(dq 
as their first component. Elements in the
.BR cdpath
edit option are
<colon>-separated.
The initial value of the
.BR cdpath
edit option is the value of the shell
.IR CDPATH
environment variable. This feature was not included in POSIX.1\(hy2008 because it
does not exist in any of the implementations considered historical
practice.
.SS "Copy"
.P
Historical implementations of
.IR ex
permitted copies to lines inside of the specified range; for example,
.BR ":2,5copy3"
was a valid command. POSIX.1\(hy2008 requires conformance to historical
practice.
.SS "Delete"
.P
POSIX.1\(hy2008 requires support for the historical parsing of a
.BR delete
command followed by flags, without any intervening
<blank>
characters. For example:
.IP "\fB1dp\fP" 8
Deletes the first line and prints the line that was second.
.IP "\fB1delep\fP" 8
As for
.BR 1dp .
.IP "\fB1d\fP" 8
Deletes the first line, saving it in buffer
.IR p .
.IP "\fB1d\0p1l\fP" 8
(Pee-one-ell.) Deletes the first line, saving it in buffer
.IR p ,
and listing the line that was second.
.SS "Edit"
.P
Historically, any
.IR ex
command could be entered as a
.BR + \c
.IR command
argument to the
.BR edit
command, although some (for example,
.BR insert
and
.BR append )
were known to confuse historical implementations. For consistency and
simplicity of specification, POSIX.1\(hy2008 requires that any command be
supported as an argument to the
.BR edit
command.
.P
Historically, the command argument was executed with the current line
set to the last line of the file, regardless of whether the
.BR edit
command was executed from visual mode or not. POSIX.1\(hy2008 requires
conformance to historical practice.
.P
Historically, the
.BR + \c
.IR command
specified to the
.BR edit
and
.BR next
commands was delimited by the first
<blank>,
and there was no way to quote them. For consistency, POSIX.1\(hy2008 requires
that the usual
.IR ex
backslash quoting be provided.
.P
Historically, specifying the
.BR + \c
.IR command
argument to the edit command required a filename to be specified as
well; for example,
.BR ":edit\0+100"
would always fail. For consistency and simplicity of specification,
POSIX.1\(hy2008 does not permit this usage to fail for that reason.
.P
Historically, only the cursor position of the last file edited was
remembered by the editor. POSIX.1\(hy2008 requires that this be supported;
however, implementations are permitted to remember and restore the
cursor position for any file previously edited.
.SS "File"
.P
Historical versions of the
.IR ex
editor
.BR file
command displayed a current line and number of lines in the edit buffer
of 0 when the file was empty, while the
.IR vi
<control>\(hyG
command displayed a current line and number of lines in the edit buffer
of 1 in the same situation. POSIX.1\(hy2008 does not permit this discrepancy,
instead requiring that a message be displayed indicating that the file
is empty.
.SS "Global"
.P
The two-pass operation of the
.BR global
and
.BR v
commands is not intended to imply implementation, only the required
result of the operation.
.P
The current line and column are set as specified for the individual
.IR ex
commands. This requirement is cumulative; that is, the current line and
column must track across all the commands executed by the
.BR global
or
.BR v
commands.
.SS "Insert"
.P
See the RATIONALE for the
.BR append
command.
.P
Historically,
.BR insert
could not be used with an address of zero; that is, not when the edit
buffer was empty. POSIX.1\(hy2008 requires that this command behave consistently
with the
.BR append
command.
.SS "Join"
.P
The action of the
.BR join
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"
.P
The historical output of the
.BR list
command was potentially ambiguous. The standard developers believed
correcting this to be more important than adhering to historical
practice, and POSIX.1\(hy2008 requires unambiguous output.
.SS "Map"
.P
Historically, command mode maps only applied to command names; for
example, if the character
.BR 'x' 
was mapped to
.BR 'y' ,
the command
.BR fx
searched for the
.BR 'x' 
character, not the
.BR 'y' 
character. POSIX.1\(hy2008 requires this behavior. Historically, entering
<control>\(hyV
as the first character of a
.IR vi
command was an error. Several implementations have extended the
semantics of
.IR vi
such that
<control>\(hyV
means that the subsequent command character is not mapped. This is
permitted, but not required, by POSIX.1\(hy2008. Regardless, using
<control>\(hyV
to escape the second or later character in a sequence of characters
that might match a
.BR map
command, or any character in text input mode, is historical practice,
and stops the entered keys from matching a map. POSIX.1\(hy2008 requires
conformance to historical practice.
.P
Historical implementations permitted digits to be used as a
.BR map
command
.IR lhs ,
but then ignored the map. POSIX.1\(hy2008 requires that the mapped digits not be
ignored.
.P
The historical implementation of the
.BR map
command did not permit
.BR map
commands that were more than a single character in length if the first
character was printable. This behavior is permitted, but not required,
by POSIX.1\(hy2008.
.P
Historically, mapped characters were remapped unless the
.BR remap
edit option was not set, or the prefix of the mapped characters matched
the mapping characters; for example, in the
.BR map :
.sp
.RS 4
.nf
\fB
:map ab abcd
.fi \fR
.P
.RE
.P
the characters
.BR \(dqab\(dq 
were used as is and were not remapped, but the characters
.BR \(dqcd\(dq 
were mapped if appropriate. This can cause infinite loops in the
.IR vi
mapping mechanisms. POSIX.1\(hy2008 requires conformance to historical practice,
and that such loops be interruptible.
.P
Text input maps had the same problems with expanding the
.IR lhs
for the
.IR ex
.BR map!
and
.BR unmap!
command as did the
.IR ex
.BR abbreviate
and
.BR unabbreviate
commands. See the RATIONALE for the
.IR ex
.BR abbreviate
command. POSIX.1\(hy2008 requires similar modification of some historical
practice for the
.BR map
and
.BR unmap
commands, as described for the
.BR abbreviate
and
.BR unabbreviate
commands.
.P
Historically,
.BR map s
that were subsets of other
.BR map s
behaved differently depending on the order in which they were defined.
For example:
.sp
.RS 4
.nf
\fB
:map! ab     short
:map! abc    long
.fi \fR
.P
.RE
.P
would always translate the characters
.BR \(dqab\(dq 
to
.BR \(dqshort\(dq ,
regardless of how fast the characters
.BR \(dqabc\(dq 
were entered. If the entry order was reversed:
.sp
.RS 4
.nf
\fB
:map! abc    long
:map! ab     short
.fi \fR
.P
.RE
.P
the characters
.BR \(dqab\(dq 
would cause the editor to pause, waiting for the completing
.BR 'c' 
character, and the characters might never be mapped to
.BR \(dqshort\(dq .
For consistency and simplicity of specification, POSIX.1\(hy2008 requires that
the shortest match be used at all times.
.P
The length of time the editor spends waiting for the characters to
complete the
.IR lhs
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
.IR vi
have added a
.BR keytime
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
.IR vi
text input mode,
.BR map s
starting with
<ESC>
characters are generally exempted from this timeout period, or, at
least timed out differently.
.SS "Mark"
.P
Historically, users were able to set the ``previous context'' marks
explicitly. In addition, the
.IR ex
commands
.BR ''
and
.BR '`
and the
.IR vi
commands
.BR '' ,
.BR `` ,
.BR `' ,
and
.BR '`
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. POSIX.1\(hy2008 requires conformance to historical
practice. Historically, if marked lines were deleted, the mark was also
deleted, but would reappear if the change was undone. POSIX.1\(hy2008 requires
conformance to historical practice.
.P
The description of the special events that set the
.BR `
and
.BR '
marks matches historical practice. For example, historically the
command
.BR "/a/,/b/"
did not set the
.BR `
and
.BR '
marks, but the command
.BR "/a/,/b/delete"
did.
.SS "Next"
.P
Historically, any
.IR ex
command could be entered as a
.BR + \c
.IR command
argument to the
.BR next
command, although some (for example,
.BR insert
and
.BR append )
were known to confuse historical implementations. POSIX.1\(hy2008 requires that
any command be permitted and that it behave as specified. The
.BR next
command can accept more than one file, so usage such as:
.sp
.RS 4
.nf
\fB
next `ls [abc] `
.fi \fR
.P
.RE
.P
is valid; it need not be valid for the
.BR edit
or
.BR read
commands, for example, because they expect only one filename.
.P
Historically, the
.BR next
command behaved differently from the
.BR :rewind
command in that it ignored the force flag if the
.BR autowrite
flag was set. For consistency, POSIX.1\(hy2008 does not permit this behavior.
.P
Historically, the
.BR next
command positioned the cursor as if the file had never been edited
before, regardless. POSIX.1\(hy2008 does not permit this behavior, for
consistency with the
.BR edit
command.
.P
Implementations wanting to provide a counterpart to the
.BR next
command that edited the previous file have used the command
.BR prev[ious],
which takes no
.IR file
argument. POSIX.1\(hy2008 does not require this command.
.SS "Open"
.P
Historically, the
.BR open
command would fail if the
.BR open
edit option was not set. POSIX.1\(hy2008 does not mention the
.BR open
edit option and does not require this behavior. Some historical
implementations do not permit entering open mode from open or visual
mode, only from
.IR ex
mode. For consistency, POSIX.1\(hy2008 does not permit this behavior.
.P
Historically, entering open mode from the command line (that is,
.IR vi
.BR +open )
resulted in anomalous behaviors; for example, the
.IR ex
file and
.IR set
commands, and the
.IR vi
command
<control>\(hyG
did not work. For consistency, POSIX.1\(hy2008 does not permit this behavior.
.P
Historically, the
.BR open
command only permitted
.BR '/' 
characters to be used as the search pattern delimiter. For consistency,
POSIX.1\(hy2008 requires that the search delimiters used by the
.BR s ,
.BR global ,
and
.BR v
commands be accepted as well.
.SS "Preserve"
.P
The
.BR preserve
command does not historically cause the file to be considered
unmodified for the purposes of future commands that may exit the
editor. POSIX.1\(hy2008 requires conformance to historical practice.
.P
Historical documentation stated that mail was not sent to the user when
preserve was executed; however, historical implementations did send
mail in this case. POSIX.1\(hy2008 requires conformance to the historical
implementations.
.SS "Print"
.P
The writing of NUL by the
.BR print
command is not specified as a special case because the standard
developers did not want to require
.IR ex
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.
.IP " 2." 4
Control characters less than \e177 are represented as
.BR '^' 
followed by the character offset from the
.BR '@' 
character in the ASCII map; for example, \e007 is represented as
.BR '^G' .
.IP " 3." 4
\e177 is represented as
.BR '^' 
followed by
.BR '?' .
.P
The display of characters having their eighth bit set was less
standard. Existing implementations use hex (0x00), octal (\e000), and a
meta-bit display. (The latter displayed bytes that had their eighth bit
set as the two characters
.BR \(dqM\(mi\(dq 
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
.BR \(miv
option of 4 BSD and 4 BSD-derived versions of the
.IR cat
utility since 1980.
.P
No specific display format is required by POSIX.1\(hy2008.
.P
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,
.BR \(dq^I\(dq 
for the
<tab>.
Implementations are encouraged to conform to historical practice in the
absence of any strong reason to diverge.
.P
Historically, all
.IR ex
commands beginning with the letter
.BR 'p' 
could be entered using capitalized versions of the commands; for
example,
.BR P[rint] ,
.BR Pre[serve] ,
and
.BR Pu[t]
were all valid command names. POSIX.1\(hy2008 permits, but does not require, this
historical practice because capital forms of the commands are used by
some implementations for other purposes.
.SS "Put"
.P
Historically, an
.IR ex
.BR put
command, executed from open or visual mode, was the same as the open or
visual mode
.BR P
command, if the buffer was named and was cut in character mode, and the
same as the
.BR p
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
.BR put ,
and the buffer was handled as if in line mode, but it was possible to
get extremely anomalous behavior. In addition, using the
.BR Q
command to switch into
.IR ex
mode, and then doing a
.BR put
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, POSIX.1\(hy2008 does not permit these behaviors. All
.IR ex
.BR put
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"
.P
Historically, an
.IR ex
.BR read
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, POSIX.1\(hy2008 does not permit this behavior.
Historically, a
.BR read
in open or visual mode from a program left the cursor at the last line
read in, not the first. For consistency, POSIX.1\(hy2008 does not permit this
behavior.
.P
Historical implementations of
.IR ex
were unable to undo
.BR read
commands that read from the output of a program. For consistency, POSIX.1\(hy2008
does not permit this behavior.
.P
Historically, the
.IR ex
and
.IR vi
message after a successful
.BR read
or
.BR write
command specified ``characters'', not ``bytes''. POSIX.1\(hy2008 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.
.P
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
.IR ex
and
.IR vi
were originally written). Because the historical
.IR ex
evaluated
.BR read!
and
.BR read\0!
equivalently, there can be no optional way to force the read. POSIX.1\(hy2008
permits, but does not require, this behavior.
.SS "Recover"
.P
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 POSIX.1\(hy2008 in requiring that the edit buffer be treated as already
modified is to prevent this user error.
.SS "Rewind"
.P
Historical implementations supported the
.BR rewind
command when the user was editing the first file in the list; that is,
the file that the
.BR rewind
command would edit. POSIX.1\(hy2008 requires conformance to historical practice.
.SS "Substitute"
.P
Historically,
.IR ex
accepted an
.BR r
option to the
.BR s
command. The effect of the
.BR r
option was to use the last regular expression used in any command as
the pattern, the same as the
.BR ~
command. The
.BR r
option is not required by POSIX.1\(hy2008. Historically, the
.BR c
and
.BR g
options were toggled; for example, the command
.BR ":s/abc/def/"
was the same as
.BR "s/abc/def/ccccgggg" .
For simplicity of specification, POSIX.1\(hy2008 does not permit this behavior.
.P
The tilde command is often used to replace the last search RE. For
example, in the sequence:
.sp
.RS 4
.nf
\fB
s/red/blue/
/green
~
.fi \fR
.P
.RE
.P
the
.BR ~
command is equivalent to:
.sp
.RS 4
.nf
\fB
s/green/blue/
.fi \fR
.P
.RE
.P
Historically,
.IR ex
accepted all of the following forms:
.sp
.RS 4
.nf
\fB
s/abc/def/
s/abc/def
s/abc/
s/abc
.fi \fR
.P
.RE
.P
POSIX.1\(hy2008 requires conformance to this historical practice.
.P
The
.BR s
command presumes that the
.BR '^' 
character only occupies a single column in the display. Much of the
.IR ex
and
.IR vi
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.
.P
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-\c
<blank>.
For consistency and simplicity of specification, POSIX.1\(hy2008 requires that
the final column position always be set to the first non-\c
<blank>.
.SS "Set"
.P
Historical implementations redisplayed all of the options for each
occurrence of the
.BR all
keyword. POSIX.1\(hy2008 permits, but does not require, this behavior.
.SS "Tag"
.P
No requirement is made as to where
.IR ex
and
.IR vi
shall look for the file referenced by the tag entry. Historical
practice has been to look for the path found in the
.BR tags
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.
.P
Because users often specify many different tags files, some of which
need not be relevant or exist at any particular time, POSIX.1\(hy2008 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
.BR tag
edit option is changed.
.P
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, POSIX.1\(hy2008 does not permit this behavior,
requiring that the name be the only factor in the decision.
.P
Historically,
.IR vi
only searched for tags in the current file from the current cursor to
the end of the file, and therefore, if the
.BR wrapscan
option was not set, tags occurring before the current cursor were not
found. POSIX.1\(hy2008 considers this a bug, and implementations are required to
search for the first occurrence in the file, regardless.
.SS "Undo"
.P
The
.BR undo
description deliberately uses the word ``modified''. The
.BR undo
command is not intended to undo commands that replace the contents of
the edit buffer, such as
.BR edit ,
.BR next ,
.BR tag ,
or
.BR recover .
.P
Cursor positioning after the
.BR undo
command was inconsistent in the historical
.IR vi ,
sometimes attempting to restore the original cursor position (\c
.BR global ,
.BR undo ,
and
.BR v
commands), and sometimes, in the presence of maps, placing the cursor
on the last line added or changed instead of the first. POSIX.1\(hy2008 requires
a simplified behavior for consistency and simplicity of specification.
.SS "Version"
.P
The
.BR version
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"
.P
Historically, the
.IR ex
and
.IR vi
message after a successful
.BR read
or
.BR write
command specified ``characters'', not ``bytes''. POSIX.1\(hy2008 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.
.P
Implementation-defined tests are permitted so that implementations
can make additional checks; for example, for locks or file modification
times.
.P
Historically, attempting to append to a nonexistent file caused an
error. It has been left unspecified in POSIX.1\(hy2008 to permit implementations
to let the
.BR write
succeed, so that the append semantics are similar to those of the
historical
.IR csh .
.P
Historical
.IR vi
permitted empty edit buffers to be written. However, since the way
.IR vi
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. POSIX.1\(hy2008 does not permit this behavior.
.P
Historically,
.IR ex
restored standard output and standard error to their values as of when
.IR ex
was invoked, before writes to programs were performed. This could
disturb the terminal configuration as well as be a security issue for
some terminals. POSIX.1\(hy2008 does not permit this, requiring that the program
output be captured and displayed as if by the
.IR ex
.BR print
command.
.SS "Adjust Window"
.P
Historically, the line count was set to the value of the
.BR scroll
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, POSIX.1\(hy2008 is resolutely silent.
.P
Historically, the
.BR z
command was
<blank>-sensitive
and
.BR z\0+
and
.BR z\0\(mi
did different things than
.BR z+
and
.BR z\(mi
because the type could not be distinguished from a flag. (The commands
.BR z\0.
and
.BR z\0=
were historically invalid.) POSIX.1\(hy2008 requires conformance to this
historical practice.
.P
Historically, the
.BR z
command was further
<blank>-sensitive
in that the
.IR count
could not be
<blank>-delimited;
for example, the commands
.BR z=\05
and
.BR z\(mi\05
were also invalid. Because the
.IR count
is not ambiguous with respect to either the type character or the
flags, this is not permitted by POSIX.1\(hy2008.
.SS "Escape"
.P
Historically,
.IR ex
filter commands only read the standard output of the commands, letting
standard error appear on the terminal as usual. The
.IR vi
utility, however, read both standard output and standard error. POSIX.1\(hy2008
requires the latter behavior for both
.IR ex
and
.IR vi ,
for consistency.
.SS "Shift Left and Shift Right"
.P
Historically, it was possible to add shift characters to increase the
effect of the command; for example,
.BR <<<
outdented (or
.BR >>>
indented) the lines 3 levels of indentation instead of the default 1.
POSIX.1\(hy2008 requires conformance to historical practice.
.SS "<control>\(hyD"
.P
Historically, the
<control>\(hyD
command erased the prompt, providing the user with an unbroken
presentation of lines from the edit buffer. This is not required by
POSIX.1\(hy2008; implementations are encouraged to provide it if possible.
Historically, the
<control>\(hyD
command took, and then ignored, a
.IR count .
POSIX.1\(hy2008 does not permit this behavior.
.SS "Write Line Number"
.P
Historically, the
.IR ex
.BR =
command, when executed in
.IR ex
mode in an empty edit buffer, reported 0, and from open or visual mode,
reported 1. For consistency and simplicity of specification, POSIX.1\(hy2008 does
not permit this behavior.
.SS "Execute"
.P
Historically,
.IR ex
did not correctly handle the inclusion of text input commands (that is,
.BR append ,
.BR insert ,
and
.BR change )
in executed buffers. POSIX.1\(hy2008 does not permit this exclusion for
consistency.
.P
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. POSIX.1\(hy2008 requires conformance to historical practice.
.P
Historically, the
.BR @
command took a range of lines, and the
.BR @
buffer was executed once per line, with the current line (\c
.BR '.' )
set to each specified line. POSIX.1\(hy2008 requires conformance to historical
practice.
.P
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
.IR ex
.BR @
command, makes it trivial to cause them to drop
.BR core .
POSIX.1\(hy2008 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
.IR ex
.BR :edit
command).
.SS "Regular Expressions in ex"
.P
Historical practice is that the characters in the replacement part of
the last
.BR s
command\(emthat is, those matched by entering a
.BR '~' 
in the regular expression\(emwere not further expanded by the regular
expression engine. So, if the characters contained the string
.BR \(dqa.,\(dq 
they would match
.BR 'a' 
followed by
.BR \(dq.,\(dq 
and not
.BR 'a' 
followed by any character. POSIX.1\(hy2008 requires conformance to historical
practice.
.SS "Edit Options in ex"
.P
The following paragraphs describe the historical behavior of some edit
options that were not, for whatever reason, included in POSIX.1\(hy2008.
Implementations are strongly encouraged to only use these names if the
functionality described here is fully supported.
.IP "\fBextended\fP" 10
The
.BR extended
edit option has been used in some implementations of
.IR vi
to provide extended regular expressions instead of basic regular
expressions This option was omitted from POSIX.1\(hy2008 because it is not
widespread historical practice.
.IP "\fBflash\fP" 10
The
.BR flash
edit option historically caused the screen to flash instead of beeping
on error. This option was omitted from POSIX.1\(hy2008 because it is not found in
some historical implementations.
.IP "\fBhardtabs\fP" 10
The
.BR hardtabs
edit option historically defined the number of columns between hardware
tab settings. This option was omitted from POSIX.1\(hy2008 because it was
believed to no longer be generally useful.
.IP "\fBmodeline\fP" 10
The
.BR modeline
(sometimes named
.BR modelines )
edit option historically caused
.IR ex
or
.IR vi
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.
.IP "\fBopen\fP" 10
The
.BR open
edit option historically disallowed the
.IR ex
.BR open
and
.BR visual
commands. This edit option was omitted because these commands are
required by POSIX.1\(hy2008.
.IP "\fBoptimize\fP" 10
The
.BR optimize
edit option historically expedited text throughput by setting the
terminal to not do automatic
<carriage-return>
characters when printing more than one logical line of output. This
option was omitted from POSIX.1\(hy2008 because it was intended for terminals
without addressable cursors, which are rarely, if ever, still used.
.IP "\fBruler\fP" 10
The
.BR ruler
edit option has been used in some implementations of
.IR vi
to present a current row/column ruler for the user. This option was
omitted from POSIX.1\(hy2008 because it is not widespread historical practice.
.IP "\fBsourceany\fP" 10
The
.BR sourceany
edit option historically caused
.IR ex
or
.IR vi
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.
.IP "\fBtimeout\fP" 10
The
.BR timeout
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 POSIX.1\(hy2008 because its behavior is
now standard, it is not widely useful, and it was rarely documented.
.IP "\fBverbose\fP" 10
The
.BR verbose
edit option has been used in some implementations of
.IR vi
to cause
.IR vi
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
.IR vi
only alerted the terminal and presented no message for such errors. The
historical editor option
.BR terse
did not select when to present error messages, it only made existing
error messages more or less verbose.) This option was omitted from
POSIX.1\(hy2008 because it is not widespread historical practice; however,
implementors are encouraged to use it if they wish to provide error
messages for naive users.
.IP "\fBwraplen\fP" 10
The
.BR wraplen
edit option has been used in some implementations of
.IR vi
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 POSIX.1\(hy2008
because it is not widespread historical practice; however, implementors
are encouraged to use it if they add this functionality.
.SS "autoindent, ai"
.P
Historically, the command
.BR 0a
did not do any autoindentation, regardless of the current indentation
of line 1. POSIX.1\(hy2008 requires that any indentation present in line 1 be
used.
.SS "autoprint, ap"
.P
Historically, the
.BR autoprint
edit option was not completely consistent or based solely on
modifications to the edit buffer. Exceptions were the
.BR read
command (when reading from a file, but not from a filter), the
.BR append ,
.BR change ,
.BR insert ,
.BR global ,
and
.BR v
commands, all of which were not affected by
.BR autoprint ,
and the
.BR tag
command, which was affected by
.BR autoprint .
POSIX.1\(hy2008 requires conformance to historical practice.
.P
Historically, the
.BR autoprint
option only applied to the last of multiple commands entered using
<vertical-line>
delimiters; for example,
.BR delete
<newline>
was affected by
.BR autoprint ,
but
.BR delete|version
<newline>
was not. POSIX.1\(hy2008 requires conformance to historical practice.
.SS "autowrite, aw"
.P
Appending the
.BR '!' 
character to the
.IR ex
.BR next
command to avoid performing an automatic write was not supported in
historical implementations. POSIX.1\(hy2008 requires that the behavior match the
other
.IR ex
commands for consistency.
.SS "ignorecase, ic"
.P
Historical implementations of case-insensitive matching (the
.BR ignorecase
edit option) lead to counter-intuitive 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.
.IP " 2." 4
Convert uppercase to lowercase in text line.
.IP " 3." 4
Convert uppercase to lowercase in regular expressions, except in
character class specifications.
.IP " 4." 4
Match regular expressions against text.
.P
This would mean that, with
.BR ignorecase
in effect, the text:
.sp
.RS 4
.nf
\fB
The cat sat on the mat
.fi \fR
.P
.RE
.P
would be matched by
.sp
.RS 4
.nf
\fB
/^the/
.fi \fR
.P
.RE
.P
but not by:
.sp
.RS 4
.nf
\fB
/^[A\(miZ]he/
.fi \fR
.P
.RE
.P
For consistency with other commands implementing regular expressions,
POSIX.1\(hy2008 does not permit this behavior.
.SS "paragraphs, para"
.P
The ISO\ POSIX\(hy2:\|1993 standard made the default
.BR paragraphs
and
.BR sections
edit options implementation-defined, arguing they were historically
oriented to the UNIX system
.IR troff
text formatter, and a ``portable user'' could use the
.BR { ,
.BR } ,
.BR [[ ,
.BR ]] ,
.BR ( ,
and
.BR )
commands in open or visual mode and have the cursor stop in unexpected
places. POSIX.1\(hy2008 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"
.P
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.
.P
The
.BR readonly
edit option specification largely conforms to historical practice. The
only difference is that historical implementations did not notice that
the user had set the
.BR readonly
edit option in cases where the file was already marked read-only for
some reason, and would therefore reinitialize the
.BR readonly
edit option the next time the contents of the edit buffer were
replaced. This behavior is disallowed by POSIX.1\(hy2008.
.SS "report"
.P
The requirement that lines copied to a buffer interact differently than
deleted lines is historical practice. For example, if the
.BR report
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.
.P
The requirement that the
.IR ex
.BR global ,
.BR v ,
.BR open ,
.BR undo ,
and
.BR visual
commands present reports based on the total number of lines added or
deleted during the command execution, and that commands executed by the
.BR global
and
.BR v
commands not present reports, is historical practice. POSIX.1\(hy2008 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
.BR global
and
.BR v
commands than it did with other
.IR ex
commands, and should behave similarly, for consistency and simplicity
of specification.
.SS "showmatch, sm"
.P
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
.IR vi
have added a
.BR matchtime
option that permits users to set the number of 0,1 second intervals the
cursor pauses on the matching character.
.SS "showmode"
.P
The
.BR showmode
option has been used in some historical implementations of
.IR ex
and
.IR vi
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
.BR '*' 
character often denoted whether the contents of the edit buffer had
been modified. The latter display has sometimes been part of the
.BR showmode
option, and sometimes based on another option. This option was not
available in the 4 BSD historical implementation of
.IR vi ,
but was viewed as generally useful, particularly to novice users, and
is required by POSIX.1\(hy2008.
.P
The
.BR smd
shorthand for the
.BR showmode
option was not present in all historical implementations of the editor.
POSIX.1\(hy2008 requires it, for consistency.
.P
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. POSIX.1\(hy2008 permits this behavior for
consistency with historical practice, but implementations are
encouraged to provide a display string for both modes.
.SS "slowopen"
.P
Historically, the
.BR slowopen
option was automatically set if the terminal baud rate was less than
1\|200 baud, or if the baud rate was 1\|200 baud and the
.BR redraw
option was not set. The
.BR slowopen
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
.BR slowopen
option. POSIX.1\(hy2008 permits most historical behavior, extending historical
practice to require
.BR slowopen
behaviors if the edit option is set by the user.
.SS "tags"
.P
The default path for tags files is left unspecified as implementations
may have their own
.BR tags
implementations that do not correspond to the historical ones. The
default
.BR tags
option value should probably at least include the file
.BR ./tags .
.SS "term"
.P
Historical implementations of
.IR ex
and
.IR vi
ignored changes to the
.BR term
edit option after the initial terminal information was loaded. This is
permitted by POSIX.1\(hy2008; however, implementations are encouraged to permit
the user to modify their terminal type at any time.
.SS "terse"
.P
Historically, the
.BR terse
edit option optionally provided a shorter, less descriptive error
message, for some error messages. This is permitted, but not required,
by POSIX.1\(hy2008. 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
.BR edit
option
.BR verbose ,
and not
.BR terse .
.SS "window"
.P
In historical implementations, the default for the
.BR window
edit option was based on the baud rate as follows:
.IP " 1." 4
If the baud rate was less than 1\|200, the
.BR edit
option
.BR w300
set the window value; for example, the line:
.RS 4 
.sp
.RS 4
.nf
\fB
set w300=12
.fi \fR
.P
.RE
.P
would set the window option to 12 if the baud rate was less than
1\|200.
.RE
.IP " 2." 4
If the baud rate was equal to 1\|200, the
.BR edit
option
.BR w1200
set the window value.
.IP " 3." 4
If the baud rate was greater than 1\|200, the
.BR edit
option
.BR w9600
set the window value.
.P
The
.BR w300 ,
.BR w1200 ,
and
.BR w9600
options do not appear in POSIX.1\(hy2008 because of their dependence on specific
baud rates.
.P
In historical implementations, the size of the window displayed by
various commands was related to, but not necessarily the same as, the
.BR window
edit option. For example, the size of the window was set by the
.IR ex
command
.BR "visual 10" ,
but it did not change the value of the
.BR window
edit option. However, changing the value of the
.BR window
edit option did change the number of lines that were displayed when the
screen was repainted. POSIX.1\(hy2008 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
.BR window
edit option.
.SS "wrapmargin, wm"
.P
Historically, the
.BR wrapmargin
option did not affect maps inserting characters that also had
associated
.IR count s;
for example
.BR ":map\0K\05aABC\0DEF" .
Unfortunately, there are widely used maps that depend on this behavior.
For consistency and simplicity of specification, POSIX.1\(hy2008 does not permit
this behavior.
.P
Historically,
.BR wrapmargin
was calculated using the column display width of all characters on the
screen. For example, an implementation using
.BR \(dq^I\(dq 
to represent
<tab>
characters when the
.BR list
edit option was set, where
.BR '^' 
and
.BR 'I' 
each took up a single column on the screen, would calculate the
.BR wrapmargin
based on a value of 2 for each
<tab>.
The
.BR number
edit option similarly changed the effective length of the line as well.
POSIX.1\(hy2008 requires conformance to historical practice.
.P
Earlier versions of this standard allowed for implementations
with bytes other than eight bits, but this has been modified in this
version.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "Section 2.9.1.1" ", " "Command Search and Execution",
.IR "\fIctags\fR\^",
.IR "\fIed\fR\^",
.IR "\fIsed\fR\^",
.IR "\fIsh\fR\^",
.IR "\fIstty\fR\^",
.IR "\fIvi\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2008,
.IR "Table 5-1" ", " "Escape Sequences and Associated Actions",
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 9.3" ", " "Basic Regular Expressions",
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
.P
The System Interfaces volume of POSIX.1\(hy2008,
.IR "\fIaccess\fR\^(\|)"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .