The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group

 NAME

vi - screen-oriented (visual) display editor

 SYNOPSIS



vi [-rR][-l][-c command][-t tagstring][-w size][file...]

vi [-rR][-l][+command][-t tagstring][-w size][file...]

 DESCRIPTION

The vi (visual) utility is a screen-oriented text editor. The user can switch back and forth between vi and the line editor ex and execute ex commands from within vi.

When using vi, the terminal screen acts as a window into the editing buffer. Changes made to the editing buffer are reflected in the screen display; the position of the cursor on the screen indicates the position within the editing buffer.

Certain block-mode terminals do not have all the capabilities necessary to support the complete vi definition. When these commands cannot be supported on such terminals, this condition will 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 specification or report an error describing the terminal-related deficiency.

 OPTIONS

The vi utility supports the XBD specification, Utility Syntax Guidelines  except for the obsolescent +command option.

The following options are supported:

-c command
+command
Begin editing by executing the specified ex command-mode commands. As with normal ex command-line entries, the command option-argument can consist of multiple ex commands separated by vertical-line characters (|). The use of commands that enter input mode in this manner produces undefined results.
-l
Set lisp mode (see Edit Options in ex ).
-r
Attempt to recover the named files after an editor or system crash, after the editor has been terminated by a signal or after the use of a pre (ex) editor command. If no file operands are given, all other options, the EXINIT variable, and any .exrc files will be ignored; a list of all recoverable files available to the invoking user will be written; and vi will exit without reading files or processing user commands.
-R
Set read-only mode, preventing accidental overwriting of the files. Any command that would write to a file requires the "!" suffix (see, for example, the write command) to be effective in this mode.
-t tagstring
Edit the file containing the specified tagstring and set the initial position within the edit buffer to the point of definition of the tag. (See ctags.) The tags feature represented by -t tagstring and the ta command is optional. It is provided on any system that also provides a conforming implementation of ctags; otherwise, the use of -t produces undefined results.
-w size
Set the value of the window editor option to size. See the window option.

If both the -t tagstring and -c command (or the obsolescent +command) options are given, the -t tagstring will be processed first; that is, the file containing the tag is selected by -t and then the command is executed.

 OPERANDS

The following operand is supported:
file
A pathname of a file to be edited.

 STDIN

The standard input consists of a series of commands and input text, as described in the EXTENDED DESCRIPTION section.

 INPUT FILES

Input files must be text files or files that would be text files except for an incomplete last line that is not longer than {LINE_MAX} - 1 bytes in length and contains no NUL characters. The editing of other forms of files may optionally be allowed by vi implementations.

The .exrc files (see the EXTENDED DESCRIPTION section) must be text files consisting of ex commands.

By default, vi will read lines from the files to be edited without interpreting any of those lines as any form of editor command.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of vi:
COLUMNS
Override the system-selected horizontal screen size. See the XBD specification, Environment Variables  for valid values and results when it is unset or null.
EXINIT
Determine a list of ex commands that will be executed on editor startup, before reading the first file. The list can contain multiple commands by separating them using a vertical-line (|) character. See also the EXTENDED DESCRIPTION section for more details of the initialisation phase.
HOME
Determine a pathname of a directory that will be searched for an editor startup file named .exrc; see the EXTENDED DESCRIPTION section.
LANG
Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.
LC_ALL
If set to a non-empty string value, override the values of all the other internationalisation variables.
LC_COLLATE
Determine the locale for the behaviour of ranges, equivalence classes and multi-character collating elements within regular expressions.
LC_CTYPE
Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files), the behaviour of character classes within regular expressions, the classification of characters as upper- or lower-case letters, the case conversion of letters, and the detection of word boundaries.
LC_MESSAGES
Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output.
NLSPATH
Determine the location of message catalogues for the processing of LC_MESSAGES .
LINES
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 XBD specification, Environment Variables  for valid values and results when it is unset or null.
PATH
Determine the search path for the shell command specified in the editor commands shell, read and write and the visual-mode command "!"; see the description of command search and execution in Command Search and Execution .
SHELL
Determine the preferred command-line interpreter for use in "!", shell, read and other commands with an operand of the form !string For the shell command the program will be invoked with the single argument -i, for all others it will be invoked with the two arguments -c and string. If this variable is null or not set, the sh utility will be used.
TERM
Determine the name of the terminal type. If this variable is unset or null, an unspecified default terminal type will be used.

 ASYNCHRONOUS EVENTS

The following actions will be taken upon receipt of signals:
SIGINT
The current editor command will be aborted. The editor will prompt for another command.
SIGCONT
The screen will be refreshed (if in visual mode).
SIGHUP
If the current buffer has changed since the last e or w command, vi will attempt to save the current file in a state such that it can be recovered later by an ex or vi -r command.

The action taken for all other signals is unspecified.

 STDOUT

If standard output is a terminal device, it may be used for writing prompts to the user, for informational messages and for writing lines from the file. If standard output is not a terminal device, undefined results occur.

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

The output from vi are text files that are identical to the input files if no changes have been made to those files by commands, with the exception that in all cases where a forced session termination (the ex command q!) has not been issued prior to any write of the file, a trailing newline character will be added to the last line of the file if one was not present in the input.

 EXTENDED DESCRIPTION

Only the visual mode of the editor is described in this section. See the ex utility for additional editing capabilities used in vi.

The pathname of the file being edited by vi is the current file. The text of the file will be read into a buffer, and all editing changes will be performed in this buffer; changes will have no effect on the file until the buffer is written out explicitly. Lines in the buffer may each be limited to {LINE_MAX} bytes and an error message may be displayed if the limit is exceeded during editing.

The alternative pathname is the name of the last file mentioned in an editor command, or the previous current pathname if the last file mentioned became the current file. When the character "%" appears in a pathname entered as part of a command argument, the character will be replaced by the current pathname; the character "#" will be replaced by the alternative pathname. The characters "%" and "#" can be escaped by preceding them with a backslash.

During initialisation, before the first file is read or any user commands from the terminal are processed, if the environment variable EXINIT is set, the editor will execute the ex commands contained in that variable. If the variable is not set, vi will attempt to read ex commands from the file $HOME/.exrc (the file .exrc in the directory referred to by the HOME environment variable). If and only if EXINIT or $HOME/.exrc sets the editor option exrc, vi finally will attempt to read ex commands from a file .exrc in the current directory. In the event that EXINIT is not set and the current directory is the user's home directory, any .exrc file will only be processed once. No .exrc file will be read unless it is owned by the same user ID as the effective user ID of the process. After any .exrc files are processed, any commands specified by the -c option will be processed.

After initialisation, vi will be in command mode; input mode can be entered by several commands used to insert or change text. In input mode, an escape character can be used to return to command mode; other uses of the escape character are described in Terminate Command or Input Mode . The results of entering newline characters in input mode are affected by the setting of the autoindent editor variable.

The last (bottom) line of the screen is used to display the input for search commands ("/" and "?"), for ex commands (":"), and system commands ("!"). It is also used to report errors or display informational messages. The editor prompts for input for commands by displaying the command ("/", "?", ":" or "!") at the beginning of the last line of the screen. All subsequent characters will be then taken as input until a line terminator is entered.

An interrupt typed during text input, or during the input of a command on the bottom line, will terminate the input (or cancel the command) and will return the editor to command mode. During command mode, an interrupt will alert the terminal. In general, an alert indicates an error (such as unrecognised key).

Lines displayed on the screen containing only a tilde (~) indicate that the last line above them is the last line in the editing buffer (the ~ lines are past the end of the editing buffer).

There may be lines on the screen marked with an "@". These indicate space on the screen not corresponding to lines in the file. This will happen if there is space at the bottom of the screen for some text, but the next line of the buffer will not fit. (It may also happen on a terminal with limited local intelligence. In this case, these lines can be removed by entering a <control>-R, forcing the editor to refresh the screen.)

 Command Descriptions in vi
The cursor, in general, is placed on the current line and in the current column position as noted for each command described below. If the current line is not in the display window, then the display window will be either scrolled or refreshed to cause the current line to be in the display window. If the screen is refreshed, the current line will be positioned as close to the center of the display window as possible. If the current line is less than one-half window lines from the beginning of the editing buffer, the first line of the buffer will be displayed on the first line of the display window. If the current line is less than one-half window lines from the end of the editing buffer, the remaining lines of the display window after the last line of the file will contain only a ~ character in column position 1. If the screen is scrolled rather than refreshed, the current line will be placed at the top of the display window if the current line is before the first line displayed. If the current line is after the last line displayed, the display window will be scrolled up and the current line will be placed on the last line of the display window.

As stated previously, the cursor is generally placed on the current column position of the current line. The one exception to this is if the current column position is beyond the end of the current line. In this case, the cursor will be placed on the last character of the current line. However, the current column position value will not be altered by this. Thus, if the current line changes to a longer line, the cursor will be moved back out to the current column position or to the end of the line if it is shorter than the current column.

Unless otherwise specified, the commands are interpreted in command mode and have no special effect in input mode.

Some of the following command descriptions (such as a, A, c, and so on) move the cursor and enter input mode. The indications of Current line and Current column are for the cursor movement up to the beginning of input mode. Depending on the text inserted, the cursor will generally wind up in a totally different location by the time command mode is reentered. The cursor movement that accompanies the transition from input mode to command mode is described in Terminate Command or Input Mode .

The following symbols are used in this section to represent arguments to commands, to describe commands or to specify the new values of the current line and column indicators following execution of the command.

bigword
A maximal sequence of non-blank characters preceded and followed by blank characters or the beginning or end of a line or the file.
buffer
One of a number of named areas for saving text. Commands that change or delete text can be preceded by a buffer specification argument buffer. It is specified in the form "c, where c represents the name of a buffer, one of the lower-case letters of the POSIX locale. Specifying buffer will cause the area of text affected by the command to be stored into the buffer as it was before the command took effect. This argument is also used on the put commands (p and P) to specify the buffer that will provide the text to insert. When a command synopsis shows both [buffer] and [count] preceding the command letter, either can precede the other. If the buffer name is specified in upper-case, and the buffer is to be modified (as with a deletion or yanking command) the buffer will be appended to rather than being overwritten. If the buffer is not to be modified (as in a visual mode put commands) the buffer name can be specified in lower-case or upper-case with the same results. There will be also one unnamed buffer, which is the repository for all text deleted (with the delete or visual mode d command) or yanked (with the yank or visual mode y command) when no buffer is specified. There are also numbered buffers, 1 to 9, inclusive, which are accessible only from visual mode. These buffers are special in that, in visual mode, when deleted text is placed in the unnamed buffer, it also will be placed in buffer 1, the previous contents of buffer 1 will be placed in buffer 2, and so on. Any text in buffer 9 will be lost. Text that is yanked (or otherwise copied) into the unnamed buffer will not modify the numbered buffers. Text cannot be placed directly into the numbered buffers although it can be retrieved from them by using a visual mode put command with the buffer name given as a number. When the buffer modifier is not used in the commands below, the unnamed buffer is the default.
column
The (previous) value of the current column indicator.
count
A positive integer used as an optional argument to most commands, either to give a size or a position (for display or movement commands), or as a repeat count (for commands that change text). This argument is optional and defaults to 1 unless otherwise noted in the individual command description.
end-of-line
A description of the current column indicator value meaning that the current column indicator will be set always to indicate the last character of the current line. Until the current column indicator is changed, the cursor will be always positioned to the last character of whatever line is current.
line
The (previous) value of the current line indicator.
non-blank
A description of the current column indicator value meaning that the current column indicator will be set to the position of the first non-blank character of the current line. If the current line has no non-blank characters, the indicator will be set to the position of the last character of the line.
motion
A command used as an optional trailing argument to some commands, indicating the extent of text to be affected by the command. The motion argument can be either the command character repeated or a cursor movement command. In the former case, exactly the current line is affected. In the latter case, the region specified will be from the current cursor position to just before the cursor position indicated by the motion command. If the command operates on lines only, then all the lines that fall partly or wholly within this region are affected. Otherwise, the exact region as described above is affected. The following commands are considered to be cursor motion commands:
$ ^ e M
% " <control>-F <control>-N
'' `letter F N
'letter { f n
( | G <control>-P
) } <control>-H <space>
, 0 H <control>-T
- <control>-B <control>-J T
/ B j t
; b k <control>-U
? <control>-D L W
[[ <control>-E l w
]] E <control>-M <control>-Y

The optional count prefix available for some of the motion commands can be included and is considered part of the motion argument. For example, in c2w, the 2w is the motion argument.

previous context
A state set whenever a non-relative motion command is executed in vi.

paragraph
An area of text that begins with either the beginning of a file, an empty line, or section boundary and continues until either an empty line, section boundary or the end of the editing buffer. Additional paragraph boundaries can be defined by the ex paragraph option.

section
An area of text that starts with a line whose first character is either a form-feed character or an open brace ({) and continues until the next section or the end of the editing buffer. The beginning and end of the editing buffer are also considered section boundaries. Additional section boundaries can be defined by the ex sections option.

sentence
An area of text that begins with either the beginning of the editing buffer or the first non-blank character following the previous sentence, paragraph or section boundary and continues until the end of the editing buffer or a period, exclamation point or question mark (".", "!", "?") character followed by either an end-of-line or two space characters. Any number of closing parentheses, brackets or double-quote (")", "]", """) characters can appear between the period, exclamation point or question mark and the space characters or end-of-line.

window
The current value of the editor option window.

word
In the POSIX locale, vi recognises two kinds of words:

  • A maximal sequence of letters, digits and underscores, delimited at both ends by: characters other than letters, digits or underscores; the beginning or end of a line; or the end of the editing buffer.

  • A maximal sequence of characters other than letters, digits, underscores or white space, delimited at both ends by: a letter, digit, underscore or white space; the beginning or end of a line; or the end of the editing buffer.

!
A character that can be appended to the command to modify its operation as detailed in the individual command descriptions.

After processing a command, if the current line and column indicators have been changed to specify a character not currently on the screen, the editor will scroll or page the text to bring the needed character onto the screen. If the new current line is within window lines of the previous current line, and the terminal is capable of scrolling in the indicated direction, the text will be scrolled the minimum number of lines necessary to present the needed character. Otherwise, the screen will be redisplayed with the new current line positioned in the middle of the screen.

The following rules specify how exceptions will be handled. When a movement command would cause a window to display beyond the beginning of the editing buffer, the window displayed is the window beginning with the first line of the editing buffer. When a movement command would cause a window to be displayed beyond the end of the editing buffer, the terminal will be alerted and the command aborted. When the current line is empty, the cursor will be placed in the first position of the line on the screen. When the current column indicator value is beyond the end of the current line, the cursor will be placed on the last character of the current line, but the current column indicator will be unchanged.

The following rules specify how position exceptions will be handled. When the current column indicator is at the beginning (end) of a line and would be set to a position before the beginning (after the end) of the current line, the command will not be executed, the terminal will be alerted, and the current position will remain unchanged. Otherwise, when the current column indicator would be set to a position before the beginning (after the end) of the current line, it will be set instead to the position of the first (last) character of that line. When the current line indicator would be set to a position before the beginning (after the end) of the editing buffer, the command will not be executed, the terminal will be alerted, and the current position will remain unchanged.

 Page Backwards

Synopsis:   [count] <control>-B

Page backward in the file, allowing two lines of overlap, by displaying the window starting at line [line - (count * (window-2))].

Current line : The last line displayed.

Current column : Move to the first non-blank character of the current line or the first character if the line is a blank line.

 Scroll Forward

Synopsis:   [count] <control>-D

Scroll forward count lines in the file. If count is not specified, the same number of lines will be scrolled as by the previous <control>-D or <control>-U command. On the first <control>-D or <control>-U command, the amount scrolled will be one-half the number of lines in a screenful. See the ex scroll option.

Current line : (line + amount scrolled).

Current column : Move to the first non-blank character of the current line or the first character if the line is a blank line.

 Scroll Forward by Line

Synopsis:   [count] <control>-E

Scroll forward count lines, leaving the current line and column as is if possible.

Current line : Unchanged unless the current line scrolls off the screen; otherwise, move to the first line displayed.

Current column : Unchanged unless the current line scrolls off the screen; otherwise, move to the first character if it is a blank line or the last character of the line if the position of the current column is further into the line than the position of the last column of the line.

 Page Forward

Synopsis:   [count] <control>-F

Page forward in the file, allowing two lines of overlap, by displaying the window starting at line [line + (count * (window-2))].

Current line : The first line displayed.

Current column : Move to the first non-blank character of the current line or the first character if the line is a blank line.

 Display Information

Synopsis:   <control>-G

Display an informational message listing the current pathname, current line, number of lines and other unspecified information, as does the ex command file.

Current line : Unchanged.

Current column : Unchanged.

 Move Cursor Backwards

Synopsis:   [count] <control>-H

Synopsis: [count] h

Move the cursor back count characters on the current line. No characters will be erased from the screen by this command. In input mode, <control>-H will have the exact same function.

Current line : Unchanged.

Current column : Set to (column - the number of columns occupied by count characters ending with the previous current column) or the beginning of the line if count is greater than the number of characters preceding the current character in the current line.

 Move Down in Column

Synopsis:   [count] <control>-J

Synopsis: [count] j
Synopsis: [count] <control>-N

Move the cursor down count lines without changing the current column.

Current line : current line + count. Unchanged if count is greater than the number of lines in the buffer following the current line.

Current column : Unchanged.

 Clear and Redisplay

Synopsis:   <control>-L

Clear and redisplay the screen.

Current line : Unchanged.

Current column : Unchanged.

 Move Cursor Down to Non-blank

Synopsis:   [count] <control>-M

Synopsis: [count] +

Move the cursor down count lines to the first non-blank character of that line.

Current line : line + count.

Current column : Move to the first non-blank character of the current line or the first character if the line is a blank line.

 Move Up in Column

Synopsis:   [count] <control>-P

Synopsis: [count] k

Move the cursor up count lines without changing the current column.

Current line : line - count.

Current column : Unchanged.

 Redraw Screen

Synopsis:   <control>-R

Redraw the current screen. If any lines have been deleted from the logical screen and flagged as deleted on the terminal using the "@" convention (see the beginning of the EXTENDED DESCRIPTION section), they will be deleted, and the logical screen will be redisplayed. Lines flagged with @ because they do not fit on the terminal display will not be affected.

Current line : Unchanged.

Current column : Unchanged.

 Move Forward with Tabs

Synopsis:   <control>-T

Move the cursor forward shiftwidth (see the ex shiftwidth option) positions in insert mode by inserting tab characters, followed by space characters, as necessary, if the current cursor position is at the beginning of a line or preceded only by blank characters.

Current line : Unchanged.

Current column : column + shiftwidth.

 Scroll Backward

Synopsis:   [count] <control>-U

Scroll backward count lines in the file. If count is not specified, the same number of lines will be scrolled as by the previous <control>-D or <control>-U command. On the first <control>-D or <control>-U command, the amount scrolled will be the value of the ex scroll editor option.

Current line : (line - amount scrolled).

Current column : Move to the first non-blank character of the current line or the first character if the line is a blank line.

 Escape Next Character

Synopsis:   <control>-V character

Synopsis: <control>-Q character

Allow the entry of a subsequent character, removing any special meaning to the editor it has in input mode (for example, the escape character). The character ^ will be displayed in the current cursor position until the subsequent character is typed, which then replaces the character ^.

Current line : Unchanged.

Current column : Unchanged.

 Delete Word

Synopsis:   <control>-W

Delete the word preceding the cursor (including any blank characters between the end of the word and the current cursor position) in input mode by moving the cursor back to the beginning of the word. No characters will be erased from the screen by this command. Only text entered during the current input mode session and on the current line can be deleted with this command.

Current line : Unchanged.

Current column : Moved back as described above.

 Scroll Backward by Line

Synopsis:   [count] <control>-Y

Scroll backward count lines, leaving the current line and column as is, if possible.

Current line : Unchanged unless the current line scrolls off the screen; otherwise, the last line displayed.

Current column : Unchanged unless the current line scrolls off the screen; otherwise, move to the first character if it is a blank line or the last character of the line if the position of the current column is further into the line than the position of the last column of the line.

 Terminate Command or Input Mode

Synopsis:   <ESC>

The effects of the escape character depend on the mode and the command being entered, as follows:

Current line : When a line-oriented command is being terminated, the current line indicator will be set as given for that command. Otherwise, unchanged.

Current column : When a line-oriented command is being terminated, the current column indicator will be set as given for that command. When terminating input mode, if the cursor is not at the beginning of a line, the current column position will be set to (column - the width of the last character inserted). Otherwise, unchanged.

 Move Cursor Forward

Synopsis:   [count] <space>

Synopsis: [count] l (ell)

Move the cursor forward count characters without changing the current line.

Current line : Unchanged.

Current column : (current column + the width of the next count characters) or the end of the line if count is greater than the number of characters in the line following the current column.

 Replace Text with Results from Shell Command

Synopsis:   [count] ! motion shell-commands <newline>

Pass the lines specified by count and motion as standard input to a shell command, for the program named in the SHELL environment variable, and replace those lines with the standard output of the shell command. An implementation may consider a motion command that does not result in an integral number of lines to be an error. After the motion is entered, the text of the command will be prompted for on the last line of the display as described at the beginning of the EXTENDED DESCRIPTION section. A warning will be issued if the buffer has been changed since the last write.

Within the text of command, "%" and "#" will be expanded as pathnames (the current and alternative pathnames, respectively), and "!" will be replaced with the text of the previous "!" or :! command. (Thus, !! will repeat the previous "!" command.) If no "!" or :! command has yet been executed, an informational message will be displayed stating the problem.

The special meanings of "%", "#" and "!" can be overridden by escaping them with a backslash character. This command is affected by the ex editor options autowrite and writeany.

Current line : The first line in range.

Current column : The first column of the replaced text.

 Move Cursor to End-of-line

Synopsis:   [count] $

Move the cursor forward to the end of a line. The count argument specifies the number of lines, including the current line, to move forward.

Current line : line + count - 1.

Current column : end-of-line.

 Move to Matching Character

Synopsis:   %

Move the cursor to the parenthesis or curly brace matching the parenthesis or curly brace at the current position or on the current line forward from the current position. Matching will be determined as follows: for a left parenthesis (respectively curly brace) the editing buffer will be searched forward until either a left or right parenthesis is found. If a left parenthesis is found, a counter is incremented by one and if a right parenthesis is found, a counter is decremented by one, and the search continues (until the end of the editing buffer is found). If a right parenthesis is found when the count is less than or equal to zero, it is the matching parenthesis. For a right parenthesis (respectively curly brace) the editing buffer will be searched backward (to the beginning of the editing buffer), and each right parenthesis increments the counter, and each left parenthesis decrements it. When searching for parentheses, curly braces are not counted, and vice versa. If there is no matching character, the terminal will be alerted and the current position will remain unchanged.

Current line : Move to the line containing the matching character, as described above.

Current column : Move to the column containing the matching character, as described above.

 Repeat Substitution

Synopsis:   &

Repeat the previous substitution command (equivalent to the ex & command) using the current line as the target. Flags specified on the previous substitution command will be ignored by this command.

Current line : Unchanged.

Current column : Unchanged if the previous current column indicator value was end-of-line; otherwise, move to the first non-blank character of the current line or the first character if the line is a blank line.

 Return to Previous Context at Beginning of Line

Synopsis:   "

Synopsis: ' letter

Return to the previous context when followed by a ' character, if the context still exists, placing the cursor at the first non-blank character of the line or the last character if the line is a blank line. If the previous context no longer exists, the ' command will have no effect. When followed by a lower-case letter from the POSIX locale, return to the line marked with that letter (see the m command), at the first non-blank character in the line.

When used with an operator such as d to specify an extent of text, the operation takes place over complete lines. (See also Return to Previous Context .)

Current line : Move to the line from the previous context.

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Return to Previous Context

Synopsis:   "

Synopsis: ` letter

When followed by a ` character, return to the previous context, placing the cursor at the character position marked. (The previous context will be set whenever a non-relative move is made.) When followed by a lower-case letter from the POSIX locale, return to the line marked with that letter (see the m command), at the character position marked.

When used with an operator such as d to specify an extent of text, the operation takes place from the exact marked place to the current position within the line. (See also Return to Previous Context at Beginning of Line .)

Current line : Move to the line from the previous context.

Current column : Set to the position of the character marked from the previous context.

 Return to Previous Section

Synopsis:   [[

Back up to the previous section boundary. This command is affected by the ex sections option. Note that the brackets in this command are part of the command syntax itself and are not metacharacters.

If the lisp option is set, a section boundary is also identified by a line with a leading "(".

Current line : Move to the previous line that is a section boundary or to the first line of the editing buffer if no more section boundaries exist preceding the current line.

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Move to Next Section

Synopsis:   ]]

Move forward to a section boundary. This command is affected by the ex sections option. Note that the brackets in this command are part of the command syntax itself and are not metacharacters.

If the lisp option is set, a section boundary is also identified by a line with a leading "(".

Current line : Move to the next line that is a section boundary or to the last line of the editing buffer if no more section boundaries exist following the current line.

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Move to First Non-blank Position on Current Line

Synopsis:   ^

Move to the first non-blank position on the current line.

Current line : Unchanged.

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Move Back to Beginning of Sentence

Synopsis:   [count] (

Move backward to the beginning of a sentence. A count will move back that many sentences.

If the lisp option is set, a lisp s-expression is considered a sentence for this command.

Current line : Move to the line containing the beginning of the sentence.

Current column : Move to the first non-blank character of the sentence.

 Move Forward to Beginning of Sentence

Synopsis:   [count] )

Move forward to the beginning of a sentence. A count will move forward that many sentences.

If the lisp option is set, a lisp s-expression is considered a sentence for this command.

Current line : Move to the line containing the beginning of the sentence.

Current column : Move to the first non-blank character of the sentence.

 Move Back to Preceding Paragraph

Synopsis:   [count]{

Move back to the beginning of the preceding paragraph. A count specifies the number of paragraphs to move backward. This command is affected by the ex paragraph option.

Current line : Move to the line containing the beginning of the previous paragraph.

Current column : Move to the first non-blank character of the current line.

 Move Forward to Next Paragraph

Synopsis:   [count] }

Move forward to the beginning of the next paragraph. A count specifies the number of paragraphs to move forward. This command is affected by the ex paragraph option.

Current line : Move to the line containing the beginning of the next paragraph.

Current column : Move to the first non-blank character of the current line.

 Move to Specific Column Position

Synopsis:   [count] |

Place the cursor in the column position identified by count (if that position exists on the line). If count is omitted, it defaults to 1. If the length of the current line is less than count, the cursor will be placed at the end of the current line. If the column position is spanned by a tab or a wide character, the cursor will be placed on the character following the count-th column position.

Current line : Unchanged.

Current column : Move to the column position represented by count.

 Reverse Find Character

Synopsis:   [count] ,

Reverse the last f, F, t or T command, looking the other way in the current line. A count will be equivalent to repeating the search that many times.

Current line : Unchanged.

Current column : Move to the first column position of the next character found.

 Move to First Non-blank of Previous Line

Synopsis:   [count] -

Move to the first non-blank character in the previous line. A count specifies how many lines to move back.

Current line : line - count

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Repeat

Synopsis:   [count] .

Repeat the last command that changed the buffer. A count will be passed on to the command being repeated.

Current line : Dependent on the results of the execution of the last command that changed the buffer.

Current column : Dependent on the results of the execution of the last command that changed the buffer.

 Find Regular Expression

Synopsis:    /

Prompt the user to enter a string on the last line on the screen, interpret it as a regular expression (see Regular Expressions in ex ), and scan forward for the next occurrence of a matching string. The search will begin when a newline character or an escape character is entered to terminate the pattern; it can be prematurely terminated with an interrupt.

When used with an operator to specify an extent of text, the defined region is from the current cursor position to the beginning of the matched string. Whole lines can be specified by giving an offset from the matched line (using a closing / followed by a +n or -n).

Current line : Move to the line in which the first (or next) regular expression match occurred.

Current column : Move to the column of the first character of the matched string.

 Move to First Character in Line

Synopsis:   0  (zero)

Move to the first character on the current line. (The zero will not be interpreted as a command when it is preceded by a non-zero digit.)

Current line : Unchanged.

Current column : Column position 1.

 Execute an ex Command

Synopsis:    :

Execute an ex command. The implementation need not support an ex command that enters input mode (that is, append, change or insert). The : character, as well as the entered command, will be displayed on the bottom line. The command will be executed when the input is terminated by entering a newline character or an escape character. Typing a <control>-V (or <control>-Q) character will escape the following character, allowing its literal value to be entered.

Note:
This special property of <control>-V and <control>-Q is only effective in visual or open modes and in ex commands called from visual or open mode with the ":" command.

If the ex command causes the screen to be scrolled or causes an escape to the shell, vi will display a message indicating that it is waiting for a newline character. When a newline or an escape character is entered, the screen will be refreshed.

When executing an individual ex command by entering ":", it is not possible to enter a newline character as part of the command because it is considered the end of the command. As explained in Replacement Strings in ex , a <control>-M preceded by a <control>-V (or <control>-Q) escape character in a regular expression substitution is mapped into a newline character. A different approach is to enter ex command mode by using the vi Q command (and later resuming visual mode with the ex vi command). In ex command mode, the single-line limitation does not exist. So, for example, the following is valid:


Q
s/break here/break\
here/
vi

Current line : Dependent on the results of the execution of the ex command.

Current column : Dependent on the results of the execution of the ex command.

 Repeat Find

Synopsis:   [count] ;

Repeat the last character find using f, F, t or T. A count will move the cursor to (or next to) the count-th occurrence of the character.

Current line : Unchanged.

Current column : Move to the column containing the character being searched for. If no matching character is found, it will be unchanged.

 Shift Left

Synopsis:   [count] < motion

Shift lines left one shiftwidth (see the ex shiftwidth option). The command must be followed by a motion command to specify lines. A count will be passed through to the motion command.

When motion is "<", it will shift the current line (or count lines starting at the current one).

Current line : Unchanged.

Current column : Move to the first non-blank character of the line or the last character if the line is a blank line.

 Shift Right

Synopsis:   [count] > motion

Shift lines right one shiftwidth (see the ex shiftwidth option). The command must be followed by a motion command to specify lines. A count will be passed through to the motion command.

When motion is ">", it will shift the current line (or count lines starting at the current one).

Empty lines will not be changed.

Current line : Unchanged.

Current column : Move to the first non-blank character of the line or the last character if the line is a blank line.

 Scan Backwards for Regular Expression

Synopsis:   ?

Scan backwards, the reverse of /.

Current line : Move to the line in which the next succeeding regular expression match occurred.

Current column : Move to the column of the first character of the matched string.

 Execute

Synopsis:   @buffer

Execute each line of the named buffer as one or more vi commands (including ex commands, as described in Execute an ex Command ). If the buffer name is @, then the last buffer executed is used; if there is no last buffer, an error will occur. The text of a macro may contain an @ character calling another macro; however, recursively calling the same macro produces undefined behaviour. A vi error will terminate all currently executing macros. All changes made during a macro call will be treated as a unit and can be undone with a single u command.

Current line : Dependent on the results of the execution of the vi commands.

Current column : Dependent on the results of the execution of the vi commands.

 Reverse Case

Synopsis:   [count] ~

Reverse the case of the count characters beginning at the current cursor position. Lower-case alphabetic characters will be changed to upper-case and upper-case characters changed to lower-case. This command will have no effect on non-alphabetic characters.

Current line : Unchanged.

Current column : Move to the next column unless it is on the last character of the line, in which case it will remain unchanged.

 Reindent

Synopsis:   [count]=[motion]

If the lisp option is set, reindents the specified lines, as though they were typed in with lisp and autoindent set.

Current line : Unchanged.

Current column : Move to the first non-blank character of the line or the last character if the line is a blank line.

 Append

Synopsis:   [count] a

Enter input mode, appending the entered text after the current cursor position. A count will cause the inserted text up to the first newline character to be replicated that many times; if a newline character appears in the inserted text, only one occurrence of it and any characters following it will be inserted. For example, if the current line is abc, the command:


03afoo<newline>bar

changes that line to:

afoofoofoo
barbc

Current line : Unchanged.

Current column : column + 1.

 Append at End-of-line

Synopsis:   [count] A

Append count copies of the input text at the end of the current line, equivalent to $[count] a.

Current line : Unchanged.

Current column : See the a command.

 Move Backward to Preceding Word

Synopsis:   [count] b

Move the cursor backward to the beginning of a word by repeating the following algorithm count times: If the current position is at the beginning of a word, the current position will move to the first character of the preceding word. Otherwise, the current position will move to the first character of the word at the current position. If no preceding word exists on the current line, the current position will move to the first character of the last word on the first preceding line that contains a word. For this command, an empty or blank line will be considered to contain exactly one word.

Current line : Set to the line containing the word selected.

Current column : Set to the first character of the word selected.

 Move Backward to Preceding Bigword

Synopsis:   [count] B

Move the cursor backward to the beginning of a bigword by repeating the following algorithm count times: If the current position is at the beginning of a bigword or the character at the current position cannot be part of a bigword, the current position will move to the first character of the preceding bigword. Otherwise, the current position will move to the first character of the bigword at the current position. If no preceding bigword exists on the current line, the current position will move to the first character of the last bigword on the first preceding line that contains a bigword. For this command, an empty or blank line is considered to contain exactly one bigword.

Current line : Set to the line containing the bigword selected.

Current column : Set to the first character of the bigword selected.

 Change

Synopsis:   [buffer][count] c motion

Delete the specified region of text and enter input mode to replace it with the entered text. If more than part of a single line is affected, the deleted text will be saved in the numeric buffers. If only part of the current line is affected, then the last character to be deleted will be marked with a $. A count will be passed through to the motion command.

Current line : The current line and column position are dependent on the motion command following the c. For example, cw changes a word, c[[ changes from the beginning of the current section, and so on.

Current column : See Current line , above

 Change to End-of-line

Synopsis:   [buffer][count] C

Change text from the current position to the end-of-line (line + count - 1); equivalent to:


[buffer][count] c$

Current line : See the c command.

Current column : See the c command.

 Delete

Synopsis:   [buffer][count] d motion

Delete the specified region of text. If more than part of a line is affected, the text will be saved in the numeric buffers as well as any named buffer. A count will be passed through to the motion command.

Current line : The current line and column position are dependent on the motion command following the d. For example, dw deletes a word, d$ deletes to the end of the line, and so on.

Current column : See Current line , above.

 Delete to End-of-line

Synopsis:   [buffer] D

Delete the text from the current position to the end of the current line; equivalent to:


[buffer] d$

Current line : Unchanged.

Current column : Set to maximum of column - 1 or 1.

 Move to End-of-word

Synopsis:   [count] e

Move the cursor forward to the end of a word, by repeating the following algorithm count times: If the current position is the end of a word, the current position will move to the last character of the following word. Otherwise, the current position will move to the last character of the word at the current position. If no succeeding word exists on the current line, the current position will move to the last character of the first word on the next following line that contains a word. For this command, an empty or blank line is considered to contain exactly one word.

Current line : Set to the line containing the word selected.

Current column : Set to the last character of the word selected.

 Move to End-of-bigword

Synopsis:   [count] E

Move the cursor forward to the end of a bigword, by repeating the following algorithm count times: If the current position is the end of a bigword or the character at that position cannot be part of a bigword, the current position will move to the last character of the following bigword. Otherwise, the current position will move to the last character of the bigword at the current position. If no succeeding bigword exists on the current line, the current position will move to the last character of the first bigword on the next following line that contains a bigword.

For this command, an empty or blank line is considered to contain exactly one bigword.

Current line : Set to the line containing the bigword selected.

Current column : Set to the last character of the bigword selected.

 Find Character in Current Line (Forward)

Synopsis:   [count] f character

Scan the rest of the current line for the single character character and move the cursor to it if it is found. A count will repeat the find that many times.

Current line : Unchanged.

Current column : Set to the column position containing the character that was scanned for. Unchanged if insufficient characters were found to satisfy the count.

 Find Character in Current Line (Reverse)

Synopsis:   [count] F character

Scan backwards in the current line for the single character character, moving the cursor to it if it is found. A count will be equivalent to repeating the search that many times. If the search is unsuccessful, the terminal will be alerted and the current column position will remain unchanged.

Current line : Unchanged.

Current column : Set to the last character found moving backwards.

 Move to Line

Synopsis:   [count] G

Move the cursor to line count, or to the last line of the editing buffer if count is not specified.

Current line : count, if specified; otherwise, the last line.

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Move to Top of Screen

Synopsis:   [count] H

Move the cursor to the line (count - 1) lines from the top of the current window (that is, the count-th line, one-based, currently displayed).

Current line : count on the screen, as described above.

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Insert Before Cursor

Synopsis:   [count] i

Enter input mode, inserting the entered text before the cursor. (See also the a command.) A count will cause the inserted text up to the first newline character to be replicated that many times; if a newline character appears in the inserted text, only one occurrence of it and any characters following it will be inserted.

Current line : Unchanged.

Current column : Unchanged.

 Insert at Beginning of Line

Synopsis:   [count] I

Enter input mode at the beginning of a line. This command behaves identically to the ^[count]i command.

Current line : Unchanged.

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Join

Synopsis:   [count] J

Join the current line with the next one, supplying appropriate spacing (in the POSIX locale): one space character between words, two space characters after a period, and no space characters at all when the last character of the first line is a blank character or when the first character of the next line is ")". In the case of lines ending with blank characters, the blanks characters will be retained, no spaces will be added, and the lines will be joined together. A count will cause that many lines (minimum 2) to be joined, rather than 2. A count of 1 will be treated as 2.

Current line : Unchanged.

Current column : Move to the character after the last character of the original line.

 Move to Bottom of Screen

Synopsis:   [count] L

Move the cursor to the first non-blank character of the last line on the screen. A count will move to that line counting from the bottom. When used with an operator, whole lines are affected.

Current line : last line - count

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Mark Position

Synopsis:   m letter

Mark the current position of the cursor with a single POSIX locale lower-case letter letter. The exact position is referred to by ` letter ; the line is referred to by 'letter.

Current line : Unchanged.

Current column : Unchanged.

 Move to Middle of Screen

Synopsis:   M

Move the cursor to the middle line on the screen, at the first non-blank position on the line.

Current line : Move to a line approximately in the middle of the display window.

Current column : Move to the first non-blank character of the current line or the last character if the line is a blank line.

 Repeat Regular Expression Find (Forward)

Synopsis:   n

Repeat the last / or ? scanning command.

Current line : Set to the line containing the character string found by the scan. Unchanged if no match was found.

Current column : Move to the first character of the character string found by the scan. Unchanged if no match was found.

 Repeat Regular Expression Find (Reverse)

Synopsis:   N

Scan for the next match of the last pattern given to / or ?, but in the reverse direction; this is the reverse of n.

Current line : Move to the matched line if a match is found or unchanged if no match is found.

Current column : Move to the first column position of the matched string or unchanged if no match is found.

 Insert Empty Line Below

Synopsis:   o

Open a line below the current line and enter input mode.

Current line : The newly-created line, (line+1).

Current column : If the editor option autoindent is not set, move to the first column; otherwise, as in the description of the ex autoindent option.

 Insert Empty Line Above

Synopsis:   O

Open a new line above the current line and enter input mode.

Current line : Unchanged.

Current column : If the editor option autoindent is not set, move to the first column; otherwise, as described in the description of autoindent in ex.

 Put from Buffer Following

Synopsis:   [buffer] p

Insert text from buffer buffer following the current column or current line, as described for the P command. If buffer is omitted, the unnamed buffer is used.

Current line : (Current line+1) if the buffer contains whole lines; otherwise, unchanged.

Current column : First non-blank character of the inserted text if the buffer contained whole lines; otherwise, the last character of the inserted text.

 Put from Buffer Before

Synopsis:   [buffer] P

Put the last deleted text back before and above the cursor. The text will go back as whole lines above the cursor if it was deleted as whole lines. Otherwise, the text will be inserted just before the cursor.

The command can be preceded by a named buffer specification ("x), to retrieve the contents of the buffer.

Current line : Unchanged.

Current column : Move to the last column position of the inserted characters. If the buffer contains whole lines, the current column will be the first non-blank character of the inserted characters.

 Enter ex Mode

Synopsis:   Q

Quit from vi and enter ex command mode.

Current line : Unchanged.

Current column : Unchanged.

 Replace Character

Synopsis:   [count] r character

Replace a character on the screen with the character entered. If count is specified, the single character entered will replace the current character and each of the next count - 1 characters in the line. (For example, 7rx changes the next seven characters to be xxxxxxx). Unlike the R command, entering a newline character will replace the character with a newline character; however, when used with count, the next count characters in the line will be replaced by a single newline character.

Current line : Unchanged unless the replacement character is a newline character, in which case the current line will be incremented by 1.

Current column : Set to the last column position occupied by the replacement character, unless the replacement character is a newline character, in which case the current column position will be 1.

 Replace Characters

Synopsis:   R

Replace characters on the screen with characters entered. If the end of the existing line is encountered, it will be as if insert mode was entered at that point. If a newline character is entered before the end of the existing line, it will be entered into the editing buffer as if it was inserted, and replacement will continue on the newly created line. No other line but the one in which the R command was given will be affected.

Current line : Set to the line at the end of the replaced text.

Current column : Set to the end of the replaced text, if text was replaced. If no text was replaced, set to the column position of the character after which text would have been replaced if that character is on the current line; otherwise, 1.

 Substitute Character

Synopsis:   [buffer][count] s

Substitute count characters in the current line starting with the current column position; equivalent to:


[buffer][count] c<space>

Current line : Unchanged.

Current column : Unchanged.

 Substitute lines

Synopsis:   [buffer][count] S

Change whole lines (same as cc). A count will change that many lines; count lines will be deleted and vi will enter input mode.

Current line : Unchanged.

Current column : Set to column position 1 or to the position indicated by the previous line if autoindent is set.

 Move Cursor to Before Character (Forward)

Synopsis:   [count] t character

Move the cursor forward within the current line to the character position just before a subsequent occurrence of character. A count will place the cursor just before the count-th occurrence of the character when searching the line forwards. If the search is unsuccessful, the terminal will be alerted and the cursor position will remain unchanged.

Current line : Unchanged.

Current column : Move to the position before an occurrence of character following column (non-inclusive).

 Move Cursor to After Character (Reverse)

Synopsis:   [count] T character

Scan backwards in the current line for the single character character and if found, place the cursor just after that character. A count will place the cursor just after the count-th occurrence of the character when searching the line backwards. If count-th occurrences of the character do not exist, the terminal will be alerted and the current column position will remain unchanged.

Current line : Unchanged.

Current column : Set to the column after the scanned character. Unchanged if the character was not found.

 Undo

Synopsis:   u

Reverse the last change made to the current buffer. If repeated, the command will alternate between these two states, thus is its own inverse. When used after an insert that inserted text on more than one line, the lines will be saved in the numeric named buffers.

Current line : Move to the position of the first line changed, if the reversal affects only one line or represents an addition or change; otherwise, move to the line preceding the deleted text.

Current column : Move to the first non-blank character on the updated current line.

 Undo Current Line

Synopsis:   U

Restore the current line to its state before the cursor was last moved to it.

Current line : Unchanged.

Current column : Set to column position 1 or to the position indicated by the previous line if autoindent is set.

 Move to Beginning of Word

Synopsis:   [count] w

Move the cursor forward to the beginning of a word by repeating the following algorithm count times: If the current position is at the beginning of a word, the current position will move to the first character of the next word. If no subsequent word exists on the current line, the current position will move to the first character of the first word on the first following line that contains a word.

For this command, an empty or blank line is considered to contain exactly one word.

Current line : Set to the line containing the word selected.

Current column : Set to the first character of the word selected.

 Move to Beginning of Bigword

Synopsis:   [count] W

Move the cursor forward to the beginning of a bigword by repeating the following algorithm count times: If the current position is within a bigword or the character at that position cannot be part of a bigword, the current position will move to the first character of the next bigword. If no subsequent bigword exists on the current line, the current position will move to the first character of the first bigword on the first following line that contains a bigword. For this command, an empty or blank line is considered to contain exactly one bigword.

Current line : Set to the line containing the bigword selected.

Current column : Set to the first character of the bigword selected.

 Delete Character at Cursor

Synopsis:   [buffer][count] x

Delete count characters in the current line starting with the current column position; equivalent to:


[buffer][count] dl

If the number of characters to be deleted is greater than or equal to the number of characters to the end of the line, delete all of the characters from the current position to the end of the line and move the cursor to the new last character on the line.

Current line : Unchanged.

Current column : Set to the greater of - the width of the count deleted characters) or 1.

 Delete Character Before Cursor

Synopsis:   [buffer][count] X

Delete the character before the cursor; equivalent to:


[buffer][count] dh

A count will repeat the effect, but only characters on the current line will be deleted.

Current line : Unchanged.

Current column : Set to the greater of - the width of the count deleted characters) or 1.

 Yank

Synopsis:   [buffer][count] y motion

Copy (yank) the area of text specified by count and motion into the unnamed buffer, as well as into any named buffer specified by buffer.

Current line : Unchanged.

Current column : Unchanged.

 Yank Current Line

Synopsis:   [buffer][count] Y

Copy (yank) count lines starting with the current line into the unnamed buffer, as well as into any named buffer specified by buffer; equivalent to a:


[buffer][count] yy

command.

Current line : Unchanged.

Current column : Unchanged.

 Redraw Window

Synopsis:   [count1] z [count2] character

Redraw the screen with a window count2 lines long containing line count1 placed as specified by character: a newline character specifies the top of the screen, "." specifies the center of the screen, and "-" specifies the bottom of the screen. If count1 is not specified, it defaults to the current line; if count2 is not specified, it defaults to window.

Current line : count1, if specified; otherwise, unchanged.

Current column : Move to the first non-blank character of the current line or the first character if the line is a blank line.

 Exit

Synopsis:   ZZ

Exits the editor, writing out the buffer if it was changed since the last write to any file. This command behaves identically to the ex command xit.

The uses described for <control>-V can also be accomplished with <control>-Q, which is useful on terminals that use <control>-V for the down-arrow function. However, most historical implementations use <control>-Q for the termios START character, so the editor will generally not receive the <control>-Q unless stty -ixon mode is set. Any of the command characters described in this specification can be made ineffective by their selection as termios control characters, using the stty utility or other methods described in the XBD specification, General Terminal Interface  .

 EXIT STATUS

The following exit values are returned:
0
Successful completion.
>0
An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

None.

 EXAMPLES

None.

 FUTURE DIRECTIONS

The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about parts of this interface definition to the IEEE PASC Shell and Utilities Working Group which is identifying the corrections. A future revision of this specification will align with IEEE Std. 1003.2b when finalised.

 SEE ALSO

ex.

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]