vi.html

IEEE 1003.1-2003, Single Unix Specification v3

<ol>
<li>
<p>A section boundary</p>
</li>

<li>
<p>A line whose first character is a period and whose second and third characters match a two-character pair in the
<b>paragraphs</b> edit option (see <a href="../utilities/ed.html"><i>ed</i></a>)</p>
</li>

<li>
<p>A line whose first character is a period and whose only other character matches the first character of a two-character pair in
the <i>paragraphs</i> edit option, where the second character of the two-character pair is a &lt;space&gt;</p>
</li>

<li>
<p>One or more sequential blank lines</p>
</li>
</ol>
</dd>

<dt><i>remembered&nbsp;search&nbsp;direction</i></dt>

<dd><br>
See the description of <i>remembered search direction</i> in <a href="../utilities/ed.html"><i>ed</i></a>.</dd>

<dt><i>sentence&nbsp;boundary</i></dt>

<dd><br>
A <i>sentence boundary</i> is one of the following: 

<ol>
<li>
<p>A paragraph boundary</p>
</li>

<li>
<p>The first non- &lt;blank&gt; that occurs after a paragraph boundary</p>
</li>

<li>
<p>The first non- &lt;blank&gt; that occurs after a period ( <tt>'.'</tt> ), exclamation mark ( <tt>'!'</tt> ), or question mark (
<tt>'?'</tt> ), followed by two &lt;space&gt;s or the end of a line; any number of closing parenthesis ( <tt>')'</tt> ), closing
brackets ( <tt>']'</tt> ), double quote ( <tt>' ),'</tt> or single quote ( <tt>'&quot;</tt> ) characters can appear between the
punctuation mark and the two &lt;space&gt;s or end-of-line</p>
</li>
</ol>
</dd>
</dl>

<p>In the remainder of the description of the <i>vi</i> utility, the term &quot;buffer line&quot; refers to a line in the edit buffer and
the term &quot;display line&quot; refers to the line or lines on the display screen used to display one buffer line. The term &quot;current
line&quot; refers to a specific &quot;buffer line&quot;.</p>

<p>If there are display lines on the screen for which there are no corresponding buffer lines because they correspond to lines that
would be after the end of the file, they shall be displayed as a single tilde ( <tt>'&#152;'</tt> ) character, plus the terminating
&lt;newline&gt;.</p>

<p>The last line of the screen shall be used to report errors or display informational messages. It shall also be used to display
the input for &quot;line-oriented commands&quot; ( <b>/</b>, <b>?</b>, <b>:</b>, and <b>!</b>). When a line-oriented command is executed,
the editor shall enter text input mode on the last line on the screen, using the respective command characters as prompt
characters. (In the case of the <b>!</b> command, the associated motion shall be entered by the user before the editor enters text
input mode.) The line entered by the user shall be terminated by a &lt;newline&gt;, a non- &lt;control&gt;-V-escaped
&lt;carriage-return&gt;, or unescaped &lt;ESC&gt;. It is unspecified if more characters than require a display width minus one
column number of screen columns can be entered.</p>

<p>If any command is executed that overwrites a portion of the screen other than the last line of the screen (for example, the <a
href="../utilities/ex.html"><i>ex</i></a> <b>suspend</b> or <b>!</b> commands), other than the <a href=
"../utilities/ex.html"><i>ex</i></a> <b>shell</b> command, the user shall be prompted for a character before the screen is
refreshed and the edit session continued.</p>

<p>&lt;tab&gt;s shall take up the number of columns on the screen set by the <b>tabstop</b> edit option (see <a href=
"../utilities/ed.html"><i>ed</i></a>), unless there are less than that number of columns before the display margin that will cause
the displayed line to be folded; in this case, they shall only take up the number of columns up to that boundary.</p>

<p>The cursor shall be placed on the current line and relative to the current column as specified by each command described in the
following sections.</p>

<p>In open mode, if the current line is not already displayed, then it shall be displayed.</p>

<p>In visual mode, if the current line is not displayed, then the lines that are displayed shall be expanded, scrolled, or redrawn
to cause an unspecified portion of the current line to be displayed. If the screen is redrawn, no more than the number of display
lines specified by the value of the <b>window</b> edit option shall be displayed (unless the current line cannot be completely
displayed in the number of display lines specified by the <b>window</b> edit option) and the current line shall be positioned as
close to the center of the displayed lines as possible (within the constraints imposed by the distance of the line from the
beginning or end of the edit buffer). If the current line is before the first line in the display and the screen is scrolled, an
unspecified portion of the current line shall be placed on the first line of the display. If the current line is after the last
line in the display and the screen is scrolled, an unspecified portion of the current line shall be placed on the last line of the
display.</p>

<p>In visual mode, if a line from the edit buffer (other than the current line) does not entirely fit into the lines at the bottom
of the display that are available for its presentation, the editor may choose not to display any portion of the line. The lines of
the display that do not contain text from the edit buffer for this reason shall each consist of a single <tt>'@'</tt>
character.</p>

<p>In visual mode, the editor may choose for unspecified reasons to not update lines in the display to correspond to the underlying
edit buffer text. The lines of the display that do not correctly correspond to text from the edit buffer for this reason shall
consist of a single <tt>'@'</tt> character (plus the terminating &lt;newline&gt;), and the &lt;control&gt;-R command shall cause
the editor to update the screen to correctly represent the edit buffer.</p>

<p>Open and visual mode commands that set the current column set it to a column position in the display, and not a character
position in the line. In this case, however, the column position in the display shall be calculated for an infinite width display;
for example, the column related to a character that is part of a line that has been folded onto additional screen lines will be
offset from the display line column where the buffer line begins, not from the beginning of a particular display line.</p>

<p>The display cursor column in the display is based on the value of the current column, as follows, with each rule applied in
turn:</p>

<ol>
<li>
<p>If the current column is after the last display line column used by the displayed line, the display cursor column shall be set
to the last display line column occupied by the last non- &lt;newline&gt; in the current line; otherwise, the display cursor column
shall be set to the current column.</p>
</li>

<li>
<p>If the character of which some portion is displayed in the display line column specified by the display cursor column requires
more than a single display line column:</p>

<ol type="a">
<li>
<p>If in text input mode, the display cursor column shall be adjusted to the first display line column in which any portion of that
character is displayed.</p>
</li>

<li>
<p>Otherwise, the display cursor column shall be adjusted to the last display line column in which any portion of that character is
displayed.</p>
</li>
</ol>
</li>
</ol>

<p>The current column shall not be changed by these adjustments to the display cursor column.</p>

<p>If an error occurs during the parsing or execution of a <i>vi</i> command:</p>

<ul>
<li>
<p>The terminal shall be alerted. Execution of the <i>vi</i> command shall stop, and the cursor (for example, the current line and
column) shall not be further modified.</p>
</li>

<li>
<p>Unless otherwise specified by the following command sections, it is unspecified whether an informational message shall be
displayed.</p>
</li>

<li>
<p>Any partially entered <i>vi</i> command shall be discarded.</p>
</li>

<li>
<p>If the <i>vi</i> command resulted from a <b>map</b> expansion, all characters from that <b>map</b> expansion shall be discarded,
except as otherwise specified by the <b>map</b> command (see <a href="../utilities/ed.html"><i>ed</i></a>).</p>
</li>

<li>
<p>If the <i>vi</i> command resulted from the execution of a buffer, no further commands caused by the execution of the buffer
shall be executed.</p>
</li>
</ul>

<h5><a name="tag_04_167_13_03"></a>Page Backwards</h5>

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

<dd>
<pre>
<b>[</b><i>count</i><b>]</b> <tt>&lt;control&gt;-B
</tt>
</pre>
</dd>
</dl>

<p>If in open mode, the &lt;control&gt;-B command shall behave identically to the <b>z</b> command. Otherwise, if the current line
is the first line of the edit buffer, it shall be an error.</p>

<p>If the <b>window</b> edit option is less than 3, display a screen where the last line of the display shall be some portion
of:</p>

<pre>
<tt>(</tt><i>current first line</i><tt>) -1
</tt>
</pre>

<p>otherwise, display a screen where the first line of the display shall be some portion of:</p>

<pre>
<tt>(</tt><i>current first line</i><tt>) -</tt> <i>count</i> <tt>x ((window edit option) -2)
</tt>
</pre>

<p>If this calculation would result in a line that is before the first line of the edit buffer, the first line of the display shall
display some portion of the first line of the edit buffer.</p>

<p><i>Current line</i>: If no lines from the previous display remain on the screen, set to the last line of the display; otherwise,
set to ( <i>line</i> - the number of new lines displayed on this screen).</p>

<p><i>Current column</i>: Set to non- &lt;blank&gt;.</p>

<h5><a name="tag_04_167_13_04"></a>Scroll Forward</h5>

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

<dd>
<pre>
<b>[</b><i>count</i><b>]</b> <tt>&lt;control&gt;-D
</tt>
</pre>
</dd>
</dl>

<p>If the current line is the last line of the edit buffer, it shall be an error.</p>

<p>If no <i>count</i> is specified, <i>count</i> shall default to the <i>count</i> associated with the previous &lt;control&gt;-D
or &lt;control&gt;-U command. If there was no previous &lt;control&gt;-D or &lt;control&gt;-U command, <i>count</i> shall default
to the value of the <b>scroll</b> edit option.</p>

<p>If in open mode, write lines starting with the line after the current line, until <i>count</i> lines or the last line of the
file have been written.</p>

<p><i>Current line</i>: If the current line + <i>count</i> is past the last line of the edit buffer, set to the last line of the
edit buffer; otherwise, set to the current line + <i>count</i>.</p>

<p><i>Current column</i>: Set to non- &lt;blank&gt;.</p>

<h5><a name="tag_04_167_13_05"></a>Scroll Forward by Line</h5>

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

<dd>
<pre>
<b>[</b><i>count</i><b>]</b> <tt>&lt;control&gt;-E
</tt>
</pre>
</dd>
</dl>

<p>Display the line count lines after the last line currently displayed.</p>

<p>If the last line of the edit buffer is displayed, it shall be an error. If there is no line <i>count</i> lines after the last
line currently displayed, the last line of the display shall display some portion of the last line of the edit buffer.</p>

<p><i>Current line</i>: Unchanged if the previous current character is displayed; otherwise, set to the first line displayed.</p>

<p><i>Current column</i>: Unchanged.</p>

<h5><a name="tag_04_167_13_06"></a>Page Forward</h5>

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

<dd>
<pre>
<b>[</b><i>count</i><b>]</b> <tt>&lt;control&gt;-F
</tt>
</pre>
</dd>
</dl>

<p>If in open mode, the &lt;control&gt;-F command shall behave identically to the <b>z</b> command. Otherwise, if the current line
is the last line of the edit buffer, it shall be an error.</p>

<p>If the <b>window</b> edit option is less than 3, display a screen where the first line of the display shall be some portion
of:</p>

<pre>
<tt>(</tt><i>current last line</i><tt>) +1
</tt>
</pre>

<p>otherwise, display a screen where the first line of the display shall be some portion of:</p>

<pre>
<tt>(</tt><i>current first line</i><tt>) +</tt> <i>count</i> <tt>x ((window edit option) -2)
</tt>
</pre>

<p>If this calculation would result in a line that is after the last line of the edit buffer, the last line of the display shall
display some portion of the last line of the edit buffer.</p>

<p><i>Current line</i>: If no lines from the previous display remain on the screen, set to the first line of the display;
otherwise, set to ( <i>line</i> + the number of new lines displayed on this screen).</p>

<p><i>Current column</i>: Set to non- &lt;blank&gt;.</p>

<h5><a name="tag_04_167_13_07"></a>Display Information</h5>

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

<dd>
<pre>
<tt>&lt;control&gt;-G
</tt>
</pre>
</dd>
</dl>

<p>This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> <b>file</b> command.</p>

<h5><a name="tag_04_167_13_08"></a>Move Cursor Backwards</h5>

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

<dd>
<pre>
<b>[</b><i>count</i><b>]</b> <tt>&lt;control&gt;-H
<br>
</tt><b>[</b><i>count</i><b>]</b> <tt>h
<br>
the current</tt> <i>erase</i> <tt>character (see stty)
</tt>
</pre>
</dd>
</dl>

<p>If there are no characters before the current character on the current line, it shall be an error. If there are less than
<i>count</i> previous characters on the current line, <i>count</i> shall be adjusted to the number of previous characters on the
line.</p>

<p>If used as a motion command:</p>

<ol>
<li>
<p>The text region shall be from the character before the starting cursor up to and including the <i>count</i>th character before
the starting cursor.</p>
</li>

<li>
<p>Any text copied to a buffer shall be in character mode.</p>
</li>
</ol>

<p>If not used as a motion command:</p>

<p><i>Current line</i>: Unchanged.</p>

<p><i>Current column</i>: Set to ( <i>column</i> - the number of columns occupied by <i>count</i> characters ending with the
previous current column).</p>

<h5><a name="tag_04_167_13_09"></a>Move Down</h5>

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

<dd>
<pre>
<b>[</b><i>count</i><b>]</b> <tt>&lt;newline&gt;
<br>
</tt><b>[</b><i>count</i><b>]</b> <tt>&lt;control&gt;-J
<br>
</tt><b>[</b><i>count</i><b>]</b> <tt>&lt;control&gt;-M
<br>
</tt><b>[</b><i>count</i><b>]</b> <tt>&lt;control&gt;-N
<br>
</tt><b>[</b><i>count</i><b>]</b> <tt>j
<br>
</tt><b>[</b><i>count</i><b>]</b> <tt>&lt;carriage-return&gt;
<br>
</tt><b>[</b><i>count</i><b>]</b> <tt>+
</tt>
</pre>
</dd>
</dl>

<p>If there are less than <i>count</i> lines after the current line in the edit buffer, it shall be an error.</p>

<p>If used as a motion command:</p>