sed.html

IEEE 1003.1-2003, Single Unix Specification v3

</ul>

<h5><a name="tag_04_126_13_03"></a>Editing Commands in sed</h5>

<p>In the following list of editing commands, the maximum number of permissible addresses for each function is indicated by [
<i>0addr</i>], [ <i>1addr</i>], or [ <i>2addr</i>], representing zero, one, or two addresses.</p>

<p>The argument <i>text</i> shall consist of one or more lines. Each embedded &lt;newline&gt; in the text shall be preceded by a
backslash. Other backslashes in text shall be removed, and the following character shall be treated literally.</p>

<p>The <b>r</b> and <b>w</b> command verbs, and the <i>w</i> flag to the <b>s</b> command, take an optional <i>rfile</i> (or
<i>wfile</i>) parameter, separated from the command verb letter or flag by one or more &lt;blank&gt;s; implementations may allow
zero separation as an extension.</p>

<p>The argument <i>rfile</i> or the argument <i>wfile</i> shall terminate the editing command. Each <i>wfile</i> shall be created
before processing begins. Implementations shall support at least ten <i>wfile</i> arguments in the script; the actual number
(greater than or equal to 10) that is supported by the implementation is unspecified. The use of the <i>wfile</i> parameter shall
cause that file to be initially created, if it does not exist, or shall replace the contents of an existing file.</p>

<p>The <b>b</b>, <b>r</b>, <b>s</b>, <b>t</b>, <b>w</b>, <b>y</b>, and <b>:</b> command verbs shall accept additional arguments.
The following synopses indicate which arguments shall be separated from the command verbs by a single &lt;space&gt;.</p>

<p>The <b>a</b> and <b>r</b> commands schedule text for later output. The text specified for the <b>a</b> command, and the contents
of the file specified for the <b>r</b> command, shall be written to standard output just before the next attempt to fetch a line of
input when executing the <b>N</b> or <b>n</b> commands, or when reaching the end of the script. If written when reaching the end of
the script, and the <b>-n</b> option was not specified, the text shall be written after copying the pattern space to standard
output. The contents of the file specified for the <b>r</b> command shall be as of the time the output is written, not the time the
<b>r</b> command is applied. The text shall be output in the order in which the <b>a</b> and <b>r</b> commands were applied to the
input.</p>

<p>Command verbs other than <b>{</b>, <b>a</b>, <b>b</b>, <b>c</b>, <b>i</b>, <b>r</b>, <b>t</b>, <b>w</b>, <b>:</b>, and <b>#</b>
can be followed by a semicolon, optional &lt;blank&gt;s, and another command verb. However, when the <b>s</b> command verb is used
with the <i>w</i> flag, following it with another command in this manner produces undefined results.</p>

<p>A function can be preceded by one or more <tt>'!'</tt> characters, in which case the function shall be applied if the addresses
do not select the pattern space. Zero or more &lt;blank&gt;s shall be accepted before the first <tt>'!'</tt> character. It is
unspecified whether &lt;blank&gt;s can follow a <tt>'!'</tt> character, and conforming applications shall not follow a <tt>'!'</tt>
character with &lt;blank&gt;s.</p>

<dl compact>
<dt><b>[</b><i>2addr</i><b>]&nbsp;{</b><i>function</i></dt>

<dt><i>function</i></dt>

<dt>...</dt>

<dt><b>}</b></dt>

<dd>Execute a list of <i>sed</i> functions only when the pattern space is selected. The list of <i>sed</i> functions shall be
surrounded by braces and separated by &lt;newline&gt;s, and conform to the following rules. The braces can be preceded or followed
by &lt;blank&gt;s. The functions can be preceded by &lt;blank&gt;s, but shall not be followed by &lt;blank&gt;s. The
&lt;right-brace&gt; shall be preceded by a &lt;newline&gt; and can be preceded or followed by &lt;blank&gt;s.</dd>

<dt><b>[</b><i>1addr</i><b>]a\</b></dt>

<dt><i>text</i></dt>

<dd>Write text to standard output as described previously.</dd>

<dt><b>[</b><i>2addr</i><b>]b&nbsp;[</b><i>label</i><b>]</b></dt>

<dd><br>
Branch to the <b>:</b> function bearing the <i>label</i>. If <i>label</i> is not specified, branch to the end of the script. The
implementation shall support <i>label</i>s recognized as unique up to at least 8 characters; the actual length (greater than or
equal to 8) that shall be supported by the implementation is unspecified. It is unspecified whether exceeding a label length causes
an error or a silent truncation.</dd>

<dt><b>[</b><i>2addr</i><b>]c\</b></dt>

<dt><i>text</i></dt>

<dd>Delete the pattern space. With a 0 or 1 address or at the end of a 2-address range, place <i>text</i> on the output and start
the next cycle.</dd>

<dt><b>[</b><i>2addr</i><b>]d</b></dt>

<dd>Delete the pattern space and start the next cycle.</dd>

<dt><b>[</b><i>2addr</i><b>]D</b></dt>

<dd>Delete the initial segment of the pattern space through the first &lt;newline&gt; and start the next cycle.</dd>

<dt><b>[</b><i>2addr</i><b>]g</b></dt>

<dd>Replace the contents of the pattern space by the contents of the hold space.</dd>

<dt><b>[</b><i>2addr</i><b>]G</b></dt>

<dd>Append to the pattern space a &lt;newline&gt; followed by the contents of the hold space.</dd>

<dt><b>[</b><i>2addr</i><b>]h</b></dt>

<dd>Replace the contents of the hold space with the contents of the pattern space.</dd>

<dt><b>[</b><i>2addr</i><b>]H</b></dt>

<dd>Append to the hold space a &lt;newline&gt; followed by the contents of the pattern space.</dd>

<dt><b>[</b><i>1addr</i><b>]i\</b></dt>

<dt><i>text</i></dt>

<dd>Write <i>text</i> to standard output.</dd>

<dt><b>[</b><i>2addr</i><b>]l</b></dt>

<dd>(The letter ell.) Write the pattern space to standard output in a visually unambiguous form. The characters listed in the Base
Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, Table 5-1, Escape Sequences and Associated Actions ( <tt>'\\'</tt> ,
<tt>'\a'</tt> , <tt>'\b'</tt> , <tt>'\f'</tt> , <tt>'\r'</tt> , <tt>'\t'</tt> , <tt>'\v'</tt> ) shall be written as the
corresponding escape sequence; the <tt>'\n'</tt> in that table is not applicable. Non-printable characters not in that table shall
be written as one three-digit octal number (with a preceding backslash) for each byte in the character (most significant byte
first). If the size of a byte on the system is greater than 9 bits, the format used for non-printable characters is
implementation-defined. 

<p>Long lines shall be folded, with the point of folding indicated by writing a backslash followed by a &lt;newline&gt;; the length
at which folding occurs is unspecified, but should be appropriate for the output device. The end of each line shall be marked with
a <tt>'$'</tt> .</p>
</dd>

<dt><b>[</b><i>2addr</i><b>]n</b></dt>

<dd>Write the pattern space to standard output if the default output has not been suppressed, and replace the pattern space with
the next line of input, less its terminating &lt;newline&gt;. 

<p>If no next line of input is available, the <b>n</b> command verb shall branch to the end of the script and quit without starting
a new cycle.</p>
</dd>

<dt><b>[</b><i>2addr</i><b>]N</b></dt>

<dd>Append the next line of input, less its terminating &lt;newline&gt;, to the pattern space, using an embedded &lt;newline&gt; to
separate the appended material from the original material. Note that the current line number changes. 

<p>If no next line of input is available, the <b>N</b> command verb shall branch to the end of the script and quit without starting
a new cycle or copying the pattern space to standard output.</p>
</dd>

<dt><b>[</b><i>2addr</i><b>]p</b></dt>

<dd>Write the pattern space to standard output.</dd>

<dt><b>[</b><i>2addr</i><b>]P</b></dt>

<dd>Write the pattern space, up to the first &lt;newline&gt;, to standard output.</dd>

<dt><b>[</b><i>1addr</i><b>]q</b></dt>

<dd>Branch to the end of the script and quit without starting a new cycle.</dd>

<dt><b>[</b><i>1addr</i><b>]r&nbsp;</b> <i>rfile</i></dt>

<dd>Copy the contents of <i>rfile</i> to standard output as described previously. If <i>rfile</i> does not exist or cannot be read,
it shall be treated as if it were an empty file, causing no error condition.</dd>

<dt><b>[</b><i>2addr</i><b>]s/</b><i>BRE</i><b>/</b><i>replacement</i><b>/</b><i>flags</i></dt>

<dd><br>
Substitute the replacement string for instances of the BRE in the pattern space. Any character other than backslash or
&lt;newline&gt; can be used instead of a slash to delimit the BRE and the replacement. Within the BRE and the replacement, the BRE
delimiter itself can be used as a literal character if it is preceded by a backslash. 

<p>The replacement string shall be scanned from beginning to end. An ampersand ( <tt>'&amp;'</tt> ) appearing in the replacement
shall be replaced by the string matching the BRE. The special meaning of <tt>'&amp;'</tt> in this context can be suppressed by
preceding it by a backslash. The characters <tt>"\</tt><i>n"</i>, where <i>n</i> is a digit, shall be replaced by the text matched
by the corresponding backreference expression. The special meaning of <tt>"\</tt><i>n"</i> where <i>n</i> is a digit in this
context, can be suppressed by preceding it by a backslash. For each other backslash ( <tt>'\'</tt> ) encountered, the following
character shall lose its special meaning (if any). The meaning of a <tt>'\'</tt> immediately followed by any character other than
<tt>'&amp;'</tt> , <tt>'\'</tt> , a digit, or the delimiter character used for this command, is unspecified.</p>

<p>A line can be split by substituting a &lt;newline&gt; into it. The application shall escape the &lt;newline&gt; in the
replacement by preceding it by a backslash. A substitution shall be considered to have been performed even if the replacement
string is identical to the string that it replaces. Any backslash used to alter the default meaning of a subsequent character shall
be discarded from the BRE or the replacement before evaluating the BRE or using the replacement.</p>

<p>The value of <i>flags</i> shall be zero or more of:</p>

<dl compact>
<dt><i>n</i></dt>

<dd>Substitute for the <i>n</i>th occurrence only of the BRE found within the pattern space.</dd>

<dt><b>g</b></dt>

<dd>Globally substitute for all non-overlapping instances of the BRE rather than just the first one. If both <b>g</b> and <i>n</i>
are specified, the results are unspecified.</dd>

<dt><b>p</b></dt>

<dd>Write the pattern space to standard output if a replacement was made.</dd>

<dt><b>w&nbsp;</b> <i>wfile</i></dt>

<dd>Write. Append the pattern space to <i>wfile</i> if a replacement was made. A conforming application shall precede the
<i>wfile</i> argument with one or more &lt;blank&gt;s. If the <b>w</b> flag is not the last flag value given in a concatenation of
multiple flag values, the results are undefined.</dd>
</dl>
</dd>

<dt><b>[</b><i>2addr</i><b>]t&nbsp;[</b><i>label</i><b>]</b></dt>

<dd><br>
Test. Branch to the <b>:</b> command verb bearing the <i>label</i> if any substitutions have been made since the most recent
reading of an input line or execution of a <b>t</b>. If <i>label</i> is not specified, branch to the end of the script.</dd>

<dt><b>[</b><i>2addr</i><b>]w&nbsp;</b> <i>wfile</i></dt>

<dd><br>
Append (write) the pattern space to <i>wfile</i>.</dd>

<dt><b>[</b><i>2addr</i><b>]x</b></dt>

<dd>Exchange the contents of the pattern and hold spaces.</dd>

<dt><b>[</b><i>2addr</i><b>]y/</b><i>string1</i><b>/</b><i>string2</i><b>/</b></dt>

<dd><br>
Replace all occurrences of characters in <i>string1</i> with the corresponding characters in <i>string2</i>. If a backslash
followed by an <tt>'n'</tt> appear in <i>string1</i> or <i>string2</i>, the two characters shall be handled as a single
&lt;newline&gt;. If the number of characters in <i>string1</i> and <i>string2</i> are not equal, or if any of the characters in
<i>string1</i> appear more than once, the results are undefined. Any character other than backslash or &lt;newline&gt; can be used
instead of slash to delimit the strings. If the delimiter is not <i>n</i>, within <i>string1</i> and <i>string2</i>, the delimiter
itself can be used as a literal character if it is preceded by a backslash. If a backslash character is immediately followed by a
backslash character in <i>string1</i> or <i>string2</i>, the two backslash characters shall be counted as a single literal
backslash character. The meaning of a backslash followed by any character that is not <tt>'n'</tt> , a backslash, or the delimiter
character is undefined.</dd>

<dt><b>[</b><i>0addr</i><b>]:</b><i>label</i></dt>

<dd>Do nothing. This command bears a <i>label</i> to which the <b>b</b> and <b>t</b> commands branch.</dd>

<dt><b>[</b><i>1addr</i><b>]=</b></dt>

<dd>Write the following to standard output: 

<pre>
<tt>"%d\n", &lt;</tt><i>current line number</i><tt>&gt;
</tt>