ed.html

IEEE 1003.1-2003, Single Unix Specification v3

<tt>'%'</tt> or <tt>'!'</tt> are performed, the modified line shall be written to the standard output before <i>command</i> is
executed. The <b>!</b> command shall write:</p>

<pre>
<tt>"!\n"
</tt>
</pre>

<p>to standard output upon completion, unless the <b>-s</b> option is specified. The current line number shall be unchanged.</p>

<h5><a name="tag_04_42_13_33"></a>Null Command</h5>

<dl compact>
<dt><i>Synopsis</i>:</dt>

<dd>
<pre>
<tt>(.+1)
</tt>
</pre>
</dd>
</dl>

<p>An address alone on a line shall cause the addressed line to be written. A &lt;newline&gt; alone shall be equivalent to
<tt>"+1p"</tt> . The current line number shall be set to the address of the written line.</p>
</blockquote>

<h4><a name="tag_04_42_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>Successful completion without any file or command errors.</dd>

<dt>&gt;0</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_42_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>When an error in the input script is encountered, or when an error is detected that is a consequence of the data (not) present
in the file or due to an external condition such as a read or write error:</p>

<ul>
<li>
<p>If the standard input is a terminal device file, all input shall be flushed, and a new command read.</p>
</li>

<li>
<p>If the standard input is a regular file, <i>ed</i> shall terminate with a non-zero exit status.</p>
</li>
</ul>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_42_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>Because of the extremely terse nature of the default error messages, the prudent script writer begins the <i>ed</i> input
commands with an <b>H</b> command, so that if any errors do occur at least some clue as to the cause is made available.</p>

<p>In previous versions, an obsolescent <b>-</b> option was described. This is no longer specified. Applications should use the
<b>-s</b> option. Using <b>-</b> as a <i>file</i> operand now produces unspecified results. This allows implementations to continue
to support the former required behavior.</p>
</blockquote>

<h4><a name="tag_04_42_17"></a>EXAMPLES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_42_18"></a>RATIONALE</h4>

<blockquote>
<p>The initial description of this utility was adapted from the SVID. It contains some features not found in Version 7 or
BSD-derived systems. Some of the differences between the POSIX and BSD <i>ed</i> utilities include, but need not be limited to:</p>

<ul>
<li>
<p>The BSD <b>-</b> option does not suppress the <tt>'!'</tt> prompt after a <b>!</b> command.</p>
</li>

<li>
<p>BSD does not support the special meanings of the <tt>'%'</tt> and <tt>'!'</tt> characters within a <b>!</b> command.</p>
</li>

<li>
<p>BSD does not support the <i>addresses</i> <tt>';'</tt> and <tt>','</tt> .</p>
</li>

<li>
<p>BSD allows the command/suffix pairs <b>pp</b>, <b>ll</b>, and so on, which are unspecified in this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001.</p>
</li>

<li>
<p>BSD does not support the <tt>'!'</tt> character part of the <b>e</b>, <b>r</b>, or <b>w</b> commands.</p>
</li>

<li>
<p>A failed <b>g</b> command in BSD sets the line number to the last line searched if there are no matches.</p>
</li>

<li>
<p>BSD does not default the <i>command list</i> to the <b>p</b> command.</p>
</li>

<li>
<p>BSD does not support the <b>G</b>, <b>h</b>, <b>H</b>, <b>n</b>, or <b>V</b> commands.</p>
</li>

<li>
<p>On BSD, if there is no inserted text, the insert command changes the current line to the referenced line -1; that is, the line
before the specified line.</p>
</li>

<li>
<p>On BSD, the <a href="../utilities/join.html"><i>join</i></a> command with only a single address changes the current line to that
address.</p>
</li>

<li>
<p>BSD does not support the <b>P</b> command; moreover, in BSD it is synonymous with the <b>p</b> command.</p>
</li>

<li>
<p>BSD does not support the <i>undo</i> of the commands <b>j</b>, <b>m</b>, <b>r</b>, <b>s</b>, or <b>t</b>.</p>
</li>

<li>
<p>The Version 7 <i>ed</i> command <b>W</b>, and the BSD <i>ed</i> commands <b>W</b>, <b>wq</b>, and <b>z</b> are not present in
this volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</p>
</li>
</ul>

<p>The <b>-s</b> option was added to allow the functionality of the now withdrawn <b>-</b> option in a manner compatible with the
Utility Syntax Guidelines.</p>

<p>In early proposals there was a limit, {ED_FILE_MAX}, that described the historical limitations of some <i>ed</i> utilities in
their handling of large files; some of these have had problems with files larger than 100000 bytes. It was this limitation that
prompted much of the desire to include a <a href="../utilities/split.html"><i>split</i></a> command in this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001. Since this limit was removed, this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires that
implementations document the file size limits imposed by <i>ed</i> in the conformance document. The limit {ED_LINE_MAX} was also
removed; therefore, the global limit {LINE_MAX} is used for input and output lines.</p>

<p>The manner in which the <b>l</b> command writes non-printable characters was changed to avoid the historical
backspace-overstrike method. On video display terminals, the overstrike is ambiguous because most terminals simply replace
overstruck characters, making the <b>l</b> format not useful for its intended purpose of unambiguously understanding the content of
the line. The historical backslash escapes were also ambiguous. (The string <tt>"a\0011"</tt> could represent a line containing
those six characters or a line containing the three characters <tt>'a'</tt> , a byte with a binary value of 1, and a 1.) In the
format required here, a backslash appearing in the line is written as <tt>"\\"</tt> so that the output is truly unambiguous. The
method of marking the ends of lines was adopted from the <a href="../utilities/ex.html"><i>ex</i></a> editor and is required for
any line ending in &lt;space&gt;s; the <tt>'$'</tt> is placed on all lines so that a real <tt>'$'</tt> at the end of a line cannot
be misinterpreted.</p>

<p>Systems with bytes too large to fit into three octal digits must devise other means of displaying non-printable characters.
Consideration was given to requiring that the number of octal digits be large enough to hold a byte, but this seemed to be too
confusing for applications on the vast majority of systems where three digits are adequate. It would be theoretically possible for
the application to use the <a href="../utilities/getconf.html"><i>getconf</i></a> utility to find out the CHAR_BIT value and deal
with such an algorithm; however, there is really no portable way that an application can use the octal values of the bytes across
various coded character sets, so the additional specification was not worthwhile.</p>

<p>The description of how a NUL is written was removed. The NUL character cannot be in text files, and this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001 should not dictate behavior in the case of undefined, erroneous input.</p>

<p>Unlike some of the other editing utilities, the filenames accepted by the <b>E</b>, <b>e</b>, <b>R</b>, and <b>r</b> commands
are not patterns.</p>

<p>Early proposals stated that the <b>-p</b> option worked only when standard input was associated with a terminal device. This has
been changed to conform to historical implementations, thereby allowing applications to interpose themselves between a user and the
<i>ed</i> utility.</p>

<p>The form of the substitute command that uses the <b>n</b> suffix was limited in some historical documentation (where this was
described incorrectly as &quot;backreferencing&quot;). This limit has been omitted because there is no reason why an editor processing
lines of {LINE_MAX} length should have this restriction. The command <b>s/x/X/2047</b> should be able to substitute the 2047th
occurrence of <tt>'x'</tt> on a line.</p>

<p>The use of printing commands with printing suffixes (such as <b>pn</b>, <b>lp</b>, and so on) was made unspecified because
BSD-based systems allow this, whereas System V does not.</p>

<p>Some BSD-based systems exit immediately upon receipt of end-of-file if all of the lines in the file have been deleted. Since
this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 refers to the <b>q</b> command in this instance, such behavior is not allowed.</p>

<p>Some historical implementations returned exit status zero even if command errors had occurred; this is not allowed by this
volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</p>

<p>Some historical implementations contained a bug that allowed a single period to be entered in input mode as &lt;backslash&gt;
&lt;period&gt; &lt;newline&gt;. This is not allowed by <i>ed</i> because there is no description of escaping any of the characters
in input mode; backslashes are entered into the buffer exactly as typed. The typical method of entering a single period has been to
precede it with another character and then use the substitute command to delete that character.</p>

<p>It is difficult under some modes of some versions of historical operating system terminal drivers to distinguish between an
end-of-file condition and terminal disconnect. IEEE&nbsp;Std&nbsp;1003.1-2001 does not require implementations to distinguish
between the two situations, which permits historical implementations of the <i>ed</i> utility on historical platforms to conform.
Implementations are encouraged to distinguish between the two, if possible, and take appropriate action on terminal disconnect.</p>

<p>Historically, <i>ed</i> accepted a zero address for the <b>a</b> and <b>r</b> commands in order to insert text at the start of
the edit buffer. When the buffer was empty the command <b>.=</b> returned zero. IEEE&nbsp;Std&nbsp;1003.1-2001 requires conformance
to historical practice.</p>

<p>For consistency with the <b>a</b> and <b>r</b> commands and better user functionality, the <b>i</b> and <b>c</b> commands must
also accept an address of 0, in which case 0<i>i</i> is treated as 1<i>i</i> and likewise for the <b>c</b> command.</p>

<p>All of the following are valid addresses:</p>

<dl compact>
<dt><tt>+++</tt></dt>

<dd>Three lines after the current line.</dd>

<dt><tt>/</tt><i>pattern</i><tt>/-</tt></dt>

<dd>One line before the next occurrence of pattern.</dd>

<dt><tt>-2</tt></dt>

<dd>Two lines before the current line.</dd>

<dt><tt>3&nbsp;----&nbsp;2</tt></dt>

<dd>Line one (note the intermediate negative address).</dd>

<dt><tt>1&nbsp;2&nbsp;3</tt></dt>

<dd>Line six.</dd>
</dl>

<p>Any number of addresses can be provided to commands taking addresses; for example, <tt>"1,2,3,4,5p"</tt> prints lines 4 and 5,
because two is the greatest valid number of addresses accepted by the <b>print</b> command. This, in combination with the semicolon
delimiter, permits users to create commands based on ordered patterns in the file. For example, the command <tt>"3;/foo/;+2p"</tt>
will display the first line after line 3 that contains the pattern <i>foo</i>, plus the next two lines. Note that the address
<tt>"3;"</tt> must still be evaluated before being discarded, because the search origin for the <tt>"/foo/"</tt> command depends on
this.</p>

<p>Historically, <i>ed</i> disallowed address chains, as discussed above, consisting solely of comma or semicolon separators; for
example, <tt>",,,"</tt> or <tt>";;;"</tt> were considered an error. For consistency of address specification, this restriction is
removed. The following table lists some of the address forms now possible:</p>

<center>
<table border="1" cellpadding="3" align="center">
<tr valign="top">
<th align="center">
<p class="tent"><b>Address</b></p>
</th>
<th align="center">
<p class="tent"><b>Addr1</b></p>
</th>
<th align="center">
<p class="tent"><b>Addr2</b></p>
</th>
<th align="center">
<p class="tent"><b>Status</b></p>
</th>
<th align="center">
<p class="tent"><b>Comment</b></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">7,</p>
</td>
<td align="left">
<p class="tent">7</p>
</td>
<td align="left">
<p class="tent">7</p>
</td>
<td align="left">
<p class="tent">Historical</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">7,5,</p>
</td>
<td align="left">
<p class="tent">5</p>
</td>
<td align="left">
<p class="tent">5</p>
</td>
<td align="left">
<p class="tent">Historical</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">7,5,9</p>
</td>
<td align="left">
<p class="tent">5</p>
</td>
<td align="left">
<p class="tent">9</p>
</td>
<td align="left">
<p class="tent">Historical</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">7,9</p>
</td>
<td align="left">
<p class="tent">7</p>
</td>
<td align="left">
<p class="tent">9</p>
</td>
<td align="left">
<p class="tent">Historical</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">7,+</p>
</td>
<td align="left">
<p class="tent">7</p>
</td>
<td align="left">
<p class="tent">8</p>
</td>
<td align="left">
<p class="tent">Historical</p>
</td>