ex.html

IEEE 1003.1-2003, Single Unix Specification v3

return to command or text input mode, and shall terminate with a non-zero exit status.</dd>

<dt>SIGTERM</dt>

<dd>Refer to SIGHUP.</dd>
</dl>

<p>The action taken for all other signals is unspecified.</p>
</blockquote>

<h4><a name="tag_04_45_10"></a>STDOUT</h4>

<blockquote>
<p>The standard output shall be used only for writing prompts to the user, for informational messages, and for writing lines from
the file.</p>
</blockquote>

<h4><a name="tag_04_45_11"></a>STDERR</h4>

<blockquote>
<p>The standard error shall be used only for diagnostic messages.</p>
</blockquote>

<h4><a name="tag_04_45_12"></a>OUTPUT FILES</h4>

<blockquote>
<p>The output from <i>ex</i> shall be text files.</p>
</blockquote>

<h4><a name="tag_04_45_13"></a>EXTENDED DESCRIPTION</h4>

<blockquote>
<p>Only the <i>ex</i> mode of the editor is described in this section. See <a href="vi.html"><i>vi</i></a> for additional editing
capabilities available in <i>ex</i>.</p>

<p>When an error occurs, <i>ex</i> 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 <b>errorbells</b>
is set, an alert action shall precede the error message.</p>

<p>By default, <i>ex</i> shall start in command mode, which shall be indicated by a <b>:</b> prompt; see the <b>prompt</b> command.
Text input mode can be entered by the <b>append</b>, <b>insert</b>, or <b>change</b> commands; it can be exited (and command mode
re-entered) by typing a period ( <tt>'.'</tt> ) alone at the beginning of a line.</p>

<h5><a name="tag_04_45_13_01"></a>Initialization in ex and vi</h5>

<p>The following symbols are used in this and following sections to specify locations in the edit buffer:</p>

<dl compact>
<dt><i>alternate&nbsp;and&nbsp;current&nbsp;pathnames</i></dt>

<dd><br>
Two pathnames, named <i>current</i> and <i>alternate</i>, are maintained by the editor. Any <i>ex</i> commands that take filenames
as arguments shall set them as follows: 

<ol>
<li>
<p>If a <i>file</i> argument is specified to the <i>ex</i> <b>edit</b>, <b>ex</b>, or <b>recover</b> commands, or if an <i>ex</i>
<b>tag</b> command replaces the contents of the edit buffer.</p>

<ol type="a">
<li>
<p>If the command replaces the contents of the edit buffer, the current pathname shall be set to the <i>file</i> argument or the
file indicated by the tag, and the alternate pathname shall be set to the previous value of the current pathname.</p>
</li>

<li>
<p>Otherwise, the alternate pathname shall be set to the <i>file</i> argument.</p>
</li>
</ol>
</li>

<li>
<p>If a <i>file</i> argument is specified to the <i>ex</i> <b>next</b> command:</p>

<ol type="a">
<li>
<p>If the command replaces the contents of the edit buffer, the current pathname shall be set to the first <i>file</i> argument,
and the alternate pathname shall be set to the previous value of the current pathname.</p>
</li>
</ol>
</li>

<li>
<p>If a <i>file</i> argument is specified to the <i>ex</i> <b>file</b> command, the current pathname shall be set to the
<i>file</i> argument, and the alternate pathname shall be set to the previous value of the current pathname.</p>
</li>

<li>
<p>If a <i>file</i> argument is specified to the <i>ex</i> <b>read</b> and <b>write</b> commands (that is, when reading or writing
a file, and not to the program named by the <b>shell</b> edit option), or a <i>file</i> argument is specified to the <i>ex</i>
<b>xit</b> command:</p>

<ol type="a">
<li>
<p>If the current pathname has no value, the current pathname shall be set to the <i>file</i> argument.</p>
</li>

<li>
<p>Otherwise, the alternate pathname shall be set to the <i>file</i> argument.</p>
</li>
</ol>
</li>
</ol>

<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.</p>
</dd>

<dt><i>current&nbsp;line</i></dt>

<dd><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 <i>current line value</i>. When the edit buffer contains no lines, the current line shall be zero; see <a
href="#tag_04_45_13_02">Addressing in ex</a> .</dd>

<dt><i>current&nbsp;column</i></dt>

<dd><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 <i>current column</i> value. This column is an
<i>ideal</i> 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 <a href="vi.html#tag_04_167_13_02"><i>Command
Descriptions in vi</i></a> .</dd>

<dt><i>set&nbsp;to&nbsp;non-&lt;blank&gt;</i></dt>

<dd><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- &lt;blank&gt; of the line. If the line has no non- &lt;blank&gt; non- &lt;newline&gt;s, the
current column shall be set to the last display line column on which is displayed any part of the last non- &lt;newline&gt; in the
line. If the line is empty, the current column shall be set to column position 1.</dd>
</dl>

<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>

<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>

<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:</p>

<ol>
<li>
<p>If the environment variable <i>EXINIT</i> is set, the editor shall execute the <i>ex</i> commands contained in that
variable.</p>
</li>

<li>
<p>If the <i>EXINIT</i> variable is not set, and all of the following are true:</p>

<ol type="a">
<li>
<p>The <i>HOME</i> environment variable is not null and not empty.</p>
</li>

<li>
<p>The file <b>.exrc</b> in the directory referred to by the <i>HOME</i> environment variable:</p>

<ol>
<li>
<p>Exists</p>
</li>

<li>
<p>Is owned by the same user ID as the real user ID of the process or the process has appropriate privileges</p>
</li>

<li>
<p>Is not writable by anyone other than the owner</p>
</li>
</ol>
</li>
</ol>

<p>the editor shall execute the <i>ex</i> commands contained in that file.</p>
</li>

<li>
<p>If and only if all of the following are true:</p>

<ol type="a">
<li>
<p>The current directory is not referred to by the <i>HOME</i> environment variable.</p>
</li>

<li>
<p>A command in the <i>EXINIT</i> environment variable or a command in the <b>.exrc</b> file in the directory referred to by the
<i>HOME</i> environment variable sets the editor option <b>exrc</b>.</p>
</li>

<li>
<p>The <b>.exrc</b> file in the current directory:</p>

<ol>
<li>
<p>Exists</p>
</li>

<li>
<p>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</p>
</li>

<li>
<p>Is not writable by anyone other than the owner</p>
</li>
</ol>
</li>
</ol>

<p>the editor shall attempt to execute the <i>ex</i> commands contained in that file.</p>
</li>
</ol>

<p>Lines in any <b>.exrc</b> file that are blank lines shall be ignored. If any <b>.exrc</b> file exists, but is not read for
ownership or permission reasons, it shall be an error.</p>

<p>After the <i>EXINIT</i> variable and any <b>.exrc</b> files are processed, the first file specified by the user shall be edited,
as follows:</p>

<ol>
<li>
<p>If the user specified the <b>-t</b> option, the effect shall be as if the <i>ex</i> <b>tag</b> 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.</p>
</li>

<li>
<p>Otherwise, if the user specified any command line <i>file</i> arguments, the effect shall be as if the <i>ex</i> <b>edit</b>
command was entered with the first of those arguments as its <i>file</i> argument.</p>
</li>

<li>
<p>Otherwise, the effect shall be as if the <i>ex</i> <b>edit</b> command was entered with a nonexistent filename as its
<i>file</i> 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>
</li>
</ol>

<p>If the <b>-r</b> option was specified, the first time a file in the initial argument list or a file specified by the <b>-t</b>
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>

<p>If the <b>-c</b> 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 <b>-r</b> 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- &lt;blank&gt;,
and the <i>ex</i> commands specified with the <b>-c</b> 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 <b>-t</b> option or a <b>tag</b> command is associated with this action, the <b>-c</b> option commands shall be
executed and then the movement to the tag shall be performed.</p>

<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 <b>-t</b> 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 <i>ex</i> <b>next</b> command shall edit
the first filename from the command line). If the <b>-t</b> option was not specified, the current argument list reference shall be
to the first of the filenames on the command line.</p>

<h5><a name="tag_04_45_13_02"></a>Addressing in ex</h5>

<p>Addressing in <i>ex</i> 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>

<p>Addresses are constructed as follows:</p>

<ol>
<li>
<p>The character <tt>'.'</tt> (period) shall address the current line.</p>
</li>

<li>
<p>The character <tt>'$'</tt> shall address the last line of the edit buffer.</p>
</li>

<li>
<p>The positive decimal number <i>n</i> shall address the <i>n</i>th line of the edit buffer.</p>
</li>

<li>
<p>The address <tt>"'x"</tt> refers to the line marked with the mark name character <tt>'x'</tt> , which shall be a lowercase
letter from the portable character set or one of the characters <tt>'`'</tt> or <tt>'&quot;</tt> . 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 <i>ex</i>
<b>mark</b> or <b>k</b> commands, or the <a href="../utilities/vi.html"><i>vi</i></a> <b>m</b> command.</p>
</li>

<li>
<p>A regular expression enclosed by slashes ( <tt>'/'</tt> ) 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 &lt;newline&gt; matches the regular expression. As stated in <a href="#tag_04_45_13_58">Regular Expressions in ex</a> ,
an address consisting of a null regular expression delimited by slashes <tt>"//"</tt> shall address the next line for which the
line excluding the terminating &lt;newline&gt; matches the last regular expression encountered. In addition, the second slash can
be omitted at the end of a command line. If the <b>wrapscan</b> 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