On-line Manual Page for 1(ex)

Table of Contents

NAME

ex, edit - extended line-oriented text editor

SYNOPSIS

ex [-] [-l] [-r] [-R] [-t tag] [-v] [-V] [-wsize] [-x] [+command] [file ...]

XPG4 Synopsis
ex [-rR] [-s | -v] [-c command] [-t tag] [-w size] [file ...]

Obsolescent Options
ex [-rR] [-| -v] [+command] [-t tag] [-w size] [file ...]

edit [-] [-l] [-r] [-R] [-t tag] [-v] [-V] [-wsize] [-x] [+command] [file ...]

Remarks
The program names ex, edit, vi, view, and vedit are separate personalities of the same program. This manual entry describes the behavior of the ex/edit personality. On many HP-UX and other similar systems, e is a synonym for ex.

DESCRIPTION

The ex program is the line-oriented personality of a text editor that also supports screen-oriented editing (see vi(1)).

(XPG4 only.) Certain block-mode terminals do not have all the capabilities necessary to support the complete ex definition, such as the full-screen editing commands (visual mode or openmode). When these commands cannot be supported on such terminals, this condition shall neither produce an error message such as "not an editor command" nor report a syntax error.

The edit program is identical to ex, except that some editor option defaults are altered to make the editor somewhat friendlier for beginning and casual users (see Editor Options below).

Options and Arguments
ex recognizes the following command-line options and arguments:

-: (Obsolescent) Suppress all interactive-user feedback. This is useful when editor commands are taken from scripts.

-s: (XPG4 only.)

Suppress all interactive-user feedback. This is useful when editor commands are taken from scripts.

Ignore the value of the TERM and any implementation terminal type and assume the terminal is a type incapable of supporting visual mode.

Suppress the use of the EXINIT environment variable and the reading of the .exrc file.

-l: Set the lisp editor option (see Editor Options below).

-r: Recover the specified files after an editor or system crash. If no file is specified, a list of all saved files is printed. You must be the owner of the saved file in order to recover it (superuser cannot recover files owned by other users).

-R: Set the readonly editor option to prevent overwriting a file inadvertently (see Editor Options below).

-t tag: (XPG4 only.) Edit the file containing the specified tag and proceed as if the first command were :tag tag -t tag and the ta command is optional. It shall be provided on any system that also provides a confirming implementation of ctags, Otherwise, the use of the -t produces undefined results.

Execute the tag tag command to load and position a predefined file. See the tag command in Command Descriptions and the tags editor option in Editor Options below.

-v: Invoke visual mode (vi).

-V: Set verbose mode. Editor commands are displayed as they are executed when they are input from an .exrc file or a source file (see the source command in Command Descriptions below).

-w size: Set the value of the window editor option to size (see Editor Options below). If size is omitted, it defaults to 3.

-x: Set encryption mode. You are prompted for a key to initiate the creation or editing of an encrypted file (see the crypt command in Command Descriptions below).

-c command: (XPG4 only.)

+command (Obsolescent) Begin editing by executing the specified ex search or positioning command.

file: Specify the file or files to be edited. If more than one file is specified, they are processed in the order given. If the -r option is also specified, the files are read from the recovery area.

(XPG4 only.) If both the -t tag and -c command options are given, the

-t tag shall be processed first;i.e, the file containing the tag is: selected by the -t and then the command is executed.

Definitions
Current file. The name of the file being edited by ex is called the current file. Text from the current file is read into a work area, and all editing changes are performed on this work area. Changes do not affect the original file until the work area is explicitly written back to the file. If the % character is used as a file name, it is replaced by the current file name.

Alternate file. The alternate file is the name of the last file mentioned in an editor command, or the previous current file name if the last file mentioned becomes the current file. If the # character is used as a file name, it is replaced by the alternate file name.

Buffers. Twenty-six buffers named a through z can be used for saving blocks of text during the edit. If the buffer name is specified in uppercase, text is appended to the existing buffer contents rather than overwriting it.

Readonly flag. The readonly flag can be cleared from within the editor by setting the noreadonly editor option (see Editor Options below). Writing to a different file is allowed even when the readonly flag is set. Also, a write can be forced to a readonly file by using ! after the write command (see the write command in Command Descriptions below).

Interrupt. If an interrupt signal is received, and commands are being supplied from a keyboard, ex returns to command mode. If editor commands are coming from a file, an interrupt signal causes ex to abort.

System crash. If the system crashes or ex aborts due to an internal error or unexpected signal, ex attempts to preserve the work area if any unwritten changes were made. Use the -r command-line option to retrieve the saved changes.

Command mode/input mode. ex starts up in command mode, as indicated by the colon (:) prompt. ex switches to input mode whenever an append, change, or insert command is encountered. To terminate input mode and return to command mode, type a period (.) alone at the beginning of a line.

Comments. Command lines beginning with a quotation mark (") are ignored (this is useful for placing comments in an editor script).

Multiple commands can be combined on a single line by separating them with a vertical bar character (|). However, global commands, comments, and the shell escape command must be the last command on a line because they cannot be terminated by a | character.

Addressing
(XPG4 only.) Addressing in ex relates to the current line. In general, the current line shall be the last line affected by the command; the exact effect on the current line is discussed under the description of each command. When the buffer contains no lines, the current line shall be set to zero.

ex recognizes the following line address forms:

.: Dot or period (.) refers to the current line. There is always a current line whose position can be the result of an explicit movement command or the result of a command that affects multiple lines (in which case it is usually the last line affected).

n: The nth line in the work area. Lines are numbered sequentially, starting at line 1.

$: The last line in the work area.

%: Abbreviation for 1,$, meaning the entire work area.

+n, +[+]...

-n, -[-]...: An offset relative to the current line or the preceding line specification. + means forward; means backward. For example, the forms .+3, +3, and +++ are equivalent.

/re/: The line containing the pattern re, scanning

?re?: forward (/) or backward (?). The trailing / or ? can be omitted if the line is only being displayed. If re is omitted, ex uses the more recently set of either the scanning string or the substitution string (see Regular Expressions below).

`x: Lines can be marked using single lowercase letters (see the mark command in Command Descriptions below). `x refers to the line marked with x. In addition, the previous current line is marked before each nonrelative motion. This line can be referred to by using ` for x (thus `' refers to the previous current line).

(XPG4 only.) Commands require zero, one or two addresses. Commands that require zero addresses shall regard the presence of an address as an error.

(XPG4 only.) Adjacent address in a range shall be separated from each other by a comma (,) or a semicolon(;). In the latter case, the current line(.) shall be set to the first address, and only then is the second address calculated. This feature can be ued to determine the starting line for forwards and backwards searches. The second address of any two-address sequence shall correspond to the first address. The first address shall be less than or equal to the second address. The first address shall be greater than or equal to the first line of the editing buffer, and the last address shall be less than or equal to the last line of the editing buffer. Any other case shall be an error.

Addresses for commands consist of a series of line addresses (specified as above), separated by a comma (,) or semicolon (;). Such address lists are evaluated left-to-right. When the separator is a semicolon, the current line is set to the value of the previous address before the next address is interpreted. If more addresses are given than the command requires, then all but the last one or two are ignored. Where a command requires two addresses, the first line addressed must precede the second one in the work area. A null (missing) address in a list defaults to the current line.

Regular Expression
The editor maintains copies of two regular expression strings at all times: the substitution string, and the scanning string. The substitute command sets the substitution string to the regular expression used. Both the global-command and the regular-expression form of line addressing (see Addressing above) for all commands set the scanning string to the regular expression used. These strings are used as default regular expressions as described under Addressing, the global command, and the substitute command.

The editor supports Basic Regular Expressions (see regexp(5)) with the following modifications:

\<: The \< matches the beginning of a "word"; that is, the matched string must begin in a letter, digit, or underline, and must be preceded by the beginning of the line or a character other than the above. This construct can only be used at the beginning of a regular expression (as in \<word), but not in the middle (word1 \<word2).

\>: The \> matches the end of a "word" (see previous paragraph). This construct can only be used at the end of a regular expression (as in word\>), but not in the middle (word1\> word2).

~: Match the replacement part of the last substitute command.

[string]: The positional quoting within bracket expressions defined by Basic Regular Expressions is replaced by the use of the backslash (\) to quote bracketexpression special characters.

nomagic: When the editor option nomagic is set, the only characters with special meanings are ^ at the beginning of a pattern, $ at the end of a pattern, and \. The characters ., *, [, and ~ lose their special meanings unless escaped by a \.

Replacement Strings
The character & in the replacement string stands for the text matched by the pattern to be replaced. Use \& if the nomagic editor option is set.

The character ~ is replaced by the replacement part of the previous substitute command. Use \~ if the nomagic editor option is set.

The sequence \n, where n is an integer, is replaced by the text matched by the subpattern enclosed in the nth set of parentheses $ and $.

The sequence \u (\l) causes the immediately following character in the replacement to be converted to uppercase (lowercase), if the character is a letter. The sequence \U (\L) turns case conversion on, until the sequence \E or \e is encountered, or the end of the replacement string is reached.

Command Names and Abbreviations
The following table summarizes the line-mode commands. The commands whose names are enclosed in parentheses are available only in their abbreviated forms.

Command Descriptions
In the following command descriptions, some arguments appear frequently. They are described below.

line: A single line address, in any of the forms described in Addressing above. The default is the current line.

range: A pair of line addresses separated by a comma or semicolon, as described in Addressing above. The default is the current line (.,.).

count: A positive integer specifying the number of lines to be affected by the command. The default is 1 or the number of lines in range.

When count is specified, range is ineffective. Instead, only a line number should be specified to indicate the first line affected by the command. (If a range is given, the last line of the range is interpreted as the starting line for the command.)

flags: One or more of the characters #, p, and l. The corresponding command to print the line is executed after the command completes. Any number of + or characters can also be given with these flags. The default is no flags.

These modifiers are all optional.

When only a line or a range is specified (with a null command), the implied command is print. If a null line is entered, the next line is printed (equivalent to .+1p)

buffer: XPG4 Feature. One of a number of named areas for saving text. The named buffers are specified by the lowercase letters of the POSIX locale. Specifying buffer shall cause the area of the 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 command and the visual mode "put" commands (p and P), to specify the buffer that shall provide the text to insert.

If the buffer name is specified in uppercase, and the buffer is to be modified, the buffer shall be appended to rather than being overwritten. If the buffer is not to be modified, the buffer name can be specified in lowercase or uppercase with the same results. There shall be also one unnamed buffer, which is the repository for all text deleteed or yanked when no buffer is specified.

There are also numbered buffers, 1 through 9, which shall be accessible only from visual mode. These buffers are special in that, in the visual mode, when deleted text is placed in the unnamed buffer, it also shall be placed in buffer 1, the previous contents buffer 1 shall be placed in buffer 2 and so on. Any text in the buffer 9 shall be lost. Text that is yanked into the unnamed buffer shall not modify the numbered buffers. Text cannot be placed directly into the numbered buffered, although it can be retrieved from them by using a visual mode "put" command with the buffer name given as s number. When the buffer modifier is not used in the commands below, the unnamed buffer shall be the default.

word: XPG4 Feature. In the POSIX Locale, a word consists of a maximal sequence of letters, digits and underscores, delimited at both ends by characters other than letters, digits, or underscores, or by the beginning or end of a word or the file. ! A character that can be appended to the command to modify its operation, as detailed in the individual command descriptions.

If both a count and range is specified for a command that uses them, the number of lines affected shall be taken from the count value rather than the range. The starting line for the command shall be taken to be the first line addressed by the range.

When only a line or range is specified with no command, the implied command shall be either print, list, or number ( p, l, or #). The command selected shall be the last of these three commands to be used. When no range or count is specified and the command line is a blank line, the current line shall be written, and the current line shall be set to .+1.

Zero or mode <blank> characters can precede or follow the addresses, count or command name. Any object following a command name (such as buffer, file etc) that begins with an alphabetic character shall be separated from the command name with at least one <blank>.

For each of the commands listed below, the command can be entered as the abbreviation (those characters in the Synopsis command word preceding the [), the full command (all characters shown for the command word, omitting the [ and ]), or any subset of the characters of the full command down to the abbreviation.

abbreviate: ab[breviate] word replacement

Add the named abbreviation to the current list. In visual mode, if word is typed as a complete word during input, it is replaced by the string replacement.

append: line a[ppend][!]

Enter input mode; the input text is placed after the specified line. If line 0 is specified, the text is placed at the beginning of the work area. The last input line becomes the current line, or the target line if no lines are input.

Appending ! to the command toggles the autoindent editor option setting for this insert only.

args: ar[gs]

Prints the argument, placing the current argument between [ and ].

change: range c[hange][!] count

Enter input mode; the input text replaces the specified lines. The last input line becomes the current line; if no lines are input, the effect is the same as a delete.

Appending ! to the command toggles the autoindent editor option setting for this insert only.

chdir: chd[ir][!] [directory] cd[!] [directory]

Change the working directory to directory. If directory is omitted, the value of the HOME environment variable is used. If the work area has been modified since the last write and the name of the file being edited does not begin with a slash (/), a warning is issued and the working directory is not changed. To force a change of directory in this case, append the character ! to the command.

copy: range co[py] line flags range t line flags

A copy of the specified lines (range) is placed after the specified destination line; line 0 specifies that the lines are to be placed at the beginning of the work area. (The letter t is an alternative abbreviation for the copy command.)

crypt: cr[ypt] X

The user is prompted for a key with which to enter encryption mode. This command can also be used to change the key entered from a previous crypt command or the -x command line option. If no key is supplied in response to the prompt (that is, only carriage return is pressed), encryption mode is canceled and the work area is written out in plaintext form by subsequent write commands.

While in encryption mode, all file input is decrypted using the current key. However, while an input file is being processed, if a block of text (approximately 1024 bytes) is encountered that contains only 7-bit ASCII characters, that block of text is assumed to be plain-text and is not decrypted. All file output, except that piped via a ! shell escape to another command, is encrypted using the current key.

The temporary file used by the editor to manage the work area is not encrypted until the current work area is discarded (or written out) and editing begins on a new file. When creating a new file that requires encryption protection, ensure that the work area file is also encrypted by specifying the -x option when invoking the editor.

delete: range d[elete] buffer count

The specified lines are deleted from the work area. If a named buffer is specified, the deleted text is saved in it. If no buffer is specified, the unnamed buffer is used (that is, the buffer where the most recently deleted or yanked text is placed by default). The new current line is the line after the deleted lines or the last line of the file if the deleted lines were at the end of the file.

edit: e[dit][!] [+ line] file ex[!] [+ line] file

Begin editing a new file (ex is an alternative name for the edit command). If the current work area has been modified since the last write, a warning is printed and the command is aborted. This action can be overridden by appending the character ! to the command (e! file). The current line is the last line of the work area unless it is executed from within vi, in which case the current line is the first line of the work area. If the +line option is specified, the current line is set to the specified position, where line can be a number (or $) or specified as /re or ?re.

file: f[ile]

Print the current file name and other information, including the number of lines and the current position.

global: range g[lobal][!] /re/ command ... range v /re/ command ...

Perform command on lines within range (or on the entire work area if no range is given) that contain re. First mark the lines within the given range that match the pattern re. If the pattern is omitted, the more recently set of either the substitution string or the scanning string is used (see Regular Expressions above). Then the given commands are executed with . set to each marked line. Any character other than a letter or a digit can be used to delimit the pattern instead of the /.

command can be specified on multiple lines by hiding new-lines with a backslash. If command is omitted, each line is printed. append, change, and insert commands are allowed; the terminating dot can be omitted if it ends command or commands. The visual command is also permitted (unless the global command itself has been issued from visual mode), and takes input from the terminal. (If command contains a visual-mode command (that is, open or visual), the visual-mode command must be terminated by the visual-mode Q command in order to proceed to the next marked line.)

The global command itself and the undo command are not allowed in command. The editor options autoprint, autoindent, and report are inhibited.

Appending a ! to the global command (that is, g! ...) or using the alternate name v causes command to be run on the lines within range that do not match the pattern.

insert: line i[nsert][!]

Enter input mode; the input text is placed before the specified line. The last line input becomes the current line, or the line before the target line, if no lines are input.

Appending ! to the command toggles the autoindent editor option setting for this insert only.

join: range j[oin][!] count flags

Join together the text from the specified lines into one line. White space is adjusted to provide at least one blank character (two if a period appears at the end of a line, or none if the first character of a line is a closing parenthesis ())). Extra white space at the beginning of a line is discarded.

Appending a ! to the command causes a simpler join with no white-space processing.

list: range l[ist] ount flags

Print the specified lines with tabs displayed as ^I and the end of each line marked with a trailing $. (The only useful flag is # for line numbers.) The last line printed becomes the current line.

map: map key|#n action map! key|#n action

The map and map! commands define macros for use in visual mode. The first argument, key, can be a single character or a multicharacter sequence. In the special sequence, #n, n is a digit referring to the function key n. Special characters, whitespace, and newline must be escaped with a ^V to be entered in the arguments. The key argument cannot contain a colon (:) as its first character, nor can a multicharacter sequence begin with an alphabetic character.

Macros defined by map are effective in visual command mode. Macros defined by map! are effective in visual input mode. When key or the function key corresponding to #n is entered, the editor interprets the operation as though action were typed.

The map or map! command without options displays the corresponding current list of macros.

See also the editor options keyboardedit, keyboardedit!, timeout, and timeoutlen in Editor Options below.

mark: line ma[rk] x line k x

The specified line is given the specified mark x, which must be a single lowercase letter (a-z). x must be preceded by a space or tab. The current line position is not affected. k is an alternate name for mark.

move: range m[ove] line

Move the specified lines (range) to follow the target line. The first line moved becomes the current line.

next: n[ext][!] [ file ...]

The next file from the command line argument list is edited. Appending a ! to the command overrides the warning about the work area having been modified since the last write (and discards any changes unless the autowrite editor option is set). The argument list can be replaced by specifying a new one on this command line.

number: range nu[mber] count flags range # count flags

(The # character is an alternative abbreviation for the number command.) Print the lines, each preceded by its line number (the only useful flag is l). The last line printed becomes the current line.

open: line o[pen] /re/ flags

Enter open mode, which is similar to visual mode with a one-line window. All the visual-mode commands are available. If a match is found in line for the optional regular expression, the cursor is placed at the start of the matching pattern. Use the visual mode command Q to exit from open mode. For more information, see vi(1).

pop: pop[!]

Load the file whose name is stored at the top of the tag stack and set the current line to the stored location. The top entry of the tag stack is deleted. (The current file name is placed on the stack when you execute the line mode tag command or the visual mode ^] command.)

! overrides the warning about the work area having been modified since the last write; any changes are discarded unless the autowrite editor option is set).

preserve: pre[serve]

The current editor work area is saved as if the system had just crashed. Use this command in emergencies, for example when a write does not work and the work area cannot be saved in any other way. Use the -r command-line option to recover the file.

After the file has been preserved, a mail message shall be sent to the user. The message shall contain the name of the file, the time of preservation and an ex command that could be used to recover the file. Additional information may be included in the mail message.

print: range p[rint] count

Print the specified lines, with non-printing characters printed as control characters in the form ^x; DEL is represented as ^?. The last line printed becomes the current line.

put: line pu[t] buffer

Place deleted or "yanked" lines after line. A buffer can be specified; otherwise, the text in the unnamed buffer (that is, the buffer in which deleted or yanked text is placed by default) is restored. The current line indicator shall be set to the first line put back.

quit: q[uit][!]

Terminate the edit. If the work area has been modified since the last write, a warning is printed and the command fails. To force termination without preserving changes, append ! to the command.

read: line r[ead] file

Place a copy of the specified file in the work area after the target line (which can be line 0 to place text at the beginning). If no file is named, the current file is the default. If no current file exists, file becomes the current file. The last line read becomes the current line except in visual mode where the first line read becomes the current line.

If file is given as !string, string is interpreted as a system command and passed to the command interpreter; the resultant output is read into the work area. A blank or tab must precede the !.

recover: rec[over][!] file

Recover file from the save area, after an accidental hangup or a system crash. If the current work area has been modified since the last write, a warning is printed and the command is aborted. This action can be overridden by appending the character ! to the command (rec! file).

rewind: rew[ind][!]

The argument list is rewound, and the first file in the list is edited. This shall be equivalent to a next command with the current argument list as its operands. If the current buffer has been modified since the last write, a warning shall be written and the command shall be aborted. Any warnings can be overridden by appending a !. The current indicator line shall be affected by the editor options, autowrite and writeany.

set: se[t] [all] se[t] [no]boolean-option? se[t] value-option[?] se[t] boolean-option se[t] noboolean-option se[t] value-option=value

Set and display the values of the editor options (see Editor Options below).

With no arguments, the command prints those editor options whose values have been changed from the default settings. If all is specified, it prints all current option values.

The second and third forms display the current value of the specified option. The ? is necessary only for Boolean options.

The fourth form turns a Boolean option on. The fifth form turns a Boolean option off.

The sixth form assigns values to string and numeric options. Spaces and tabs in strings must be escaped with a leading backslash (\).

The last five forms can be combined; interpretation is left-to-right.

shell: sh[ell]

Execute the command interpreter specified by the shell editor option (see Editor Options below). Editing is resumed when you exit from the command interpreter.

source: so[urce] file

Read and execute commands from the specified file. so commands can be nested. The maximum supported nesting depths is implementation defined, but shall be at least one.

substitute: range s[ubstitute] /re/repl/ options count flags range s options count flags range & options count flags range sr options count flags range ~ options count flags range s\?repl range s\&repl

On each specified line, the first instance of the pattern re is replaced by the string repl. (See Regular Expressions and Replacement Strings above.) Any character other than a letter or a digit can be used to delimit the pattern instead of the /.

If you include the g (global) option, all instances of the pattern in the line are substituted.

If you include the c (confirm) option, you are queried about whether to perform each individual substitution, as follows: Before each substitution the line is displayed with the pattern to be replaced marked underneath with carets (^). Type y to cause the substitution to be performed; any other input to abort it. The last line substituted becomes the current line.

If the substitution pattern re is omitted (s//repl/), the more recently set of either the substitution string or the scanning string is used (see Regular Expressions above).

If the s or & forms of the command are used, the substitution pattern defaults to the previous substitution string and the replacement string defaults to the previous replacement string used.

If the sr or ~ forms of the command are used, the substitution pattern defaults to the more recently set of either the substitution string or the scanning string and the replacement string defaults to the previous replacement string used.

The form s\?repl is equivalent to s/scan-re/repl/, where scan-re is the previous scanning string.

The form s\&repl is equivalent to s/subs-re/repl/, where subs-re is the previous substitution string.

suspend: su[spend][!]

stop: st[op][!] susp

Suspend the editor job and return to the calling shell. stop and susp are equivalent to suspend. susp is the user process control suspend character, which is typically the character ^Z (ASCII SUB) (see stty(1)). This command is disabled if the calling shell does not support job control or has disabled it.

The work area is written to the current file before the editor is suspended if the autowrite editor option is set, the readonly editor option is not set, and the work area has been modified since the last write. To override this action, append the ! character to the suspend or stop command.

tag: ta[g][!] tag

Search the files specified by the tags editor option (see Editor Options below) sequentially until a tag definition for tag is found. If tag is found, load the associated file into the work area and set the current position to the address specified in the tag definition.

The work area is written to the current file before the new file is loaded if the new file is different from the current file, the autowrite editor option is set, the readonly editor option is not set, and the work area has been modified since the last write. To override this action, append the ! character to the command.

If the tagstack editor option is set, the current file name and line number is pushed onto the tag stack for later recall with the line mode pop command or the visual mode ^] command.

unabbreviate: una[bbreviate] word

Delete word from the list of abbreviations (see the abbreviate command above).

undo: u[ndo]

Reverse the changes made by the previous editing command. For this purpose, global and visual are considered single commands. Commands that affect the external environment, such as write, edit, and next, cannot be undone. An undo can itself be reversed.

unmap: unm[ap][!] key

The macro definition for key is removed (see the map command above).

version: ve[rsion]

Print the current version information for the editor.

visual: line vi[sual] type count flags

Enter visual mode at the specified line.

The type can be one of the characters +, -, ., or ^, as in the z (window) command, to specify the position of the specified line on the screen window The default is to place the line at the top of the screen window.

A count specifies an initial window size; the default is the value of the editor option window.

The flags # and l (ell) cause the lines in the visual window to be displayed in the corresponding mode (see the number and list commands).

Use the Q command to exit visual mode. For more information, see vi(1).

write: [range] w[rite][!][>>] file [range] wq[!][>>] file

Write the specified lines (or the entire work area, if no range is given) out to file, printing the number of lines and characters written. If file is not specified, the default is the current file (the command fails with an error message if there is no current file and no file is specified).

If an alternate file is specified and the file exists, the write fails, but can be forced by appending ! to the command. To append to an existing file, append >> to the command. If the file does not exist, an error is reported.

If the file is specified as !string, string is interpreted as a system command, the command interpreter is invoked, and the specified lines are passed as standard input to the command.

The command wq is equivalent to a w followed by a q. wq! is equivalent to w! followed by q. wq>> is equivalent to w>> followed by q.

xit: x[it][!][>>] file

If changes have been made to the work area, a write command is executed with any options (such as !, >>, or file) used by the write command. Then (in any case) the quit command is executed.

yank: range ya[nk] buffer count

Place the specified lines in the named buffer. If no buffer is specified, the unnamed buffer is used (that is, the buffer where the most recently deleted or yanked text is placed by default).

(execute buffer) * [buffer]
@ [buffer]

Execute the contents of buffer as an editor command. buffer can be the letter of a named buffer (a-z) or * or @. The * and the @ forms of this command are equivalent. If a buffer is not specified or buffer is * or @, the buffer last named in a * or @ command is executed.

(line number): line = flags

Print the line number of the specified line. The default is the last line. The current line position is not affected.

(scroll): ^D

Print the next n lines, where n is the value of the scroll editor option.

(shell escape): ! command range ! command

Pass the remainder of the line after the ! to the system command interpreter for execution. A warning is issued if the work area has been changed since the last write. A single ! is printed when the command completes. The current line position is not affected.

Within the text of command, % and # are expanded as file names, and ! is replaced with the text of the previous ! command. Thus, !! repeats the previous ! command. When such expansion is performed, the expanded line is echoed.

If you specify range, the specified lines are passed to the command interpreter as standard input. The output from the command replaces the specified lines.

(shift left): range < count flags

Shift the specified lines to the left. The number of spaces to be deleted is determined by the editor option shiftwidth. Only whitespace (blanks and tabs) is lost in shifting; other characters are not affected. The last line changed becomes the current line.

(shift right): range > count flags Shift the specified lines to the right by inserting whitespace The number of spaces inserted is determined by the editor option shiftwidth. The last line changed becomes the current line.

(window): line z type count flags

The number of lines specified by count are displayed. The default for count is the value of the editor option window.

If type is omitted, count lines following the specified line are printed.

If type is specified, it must be one of the following characters:

+: Display a window of lines following the addressed line.

-: Place the addressed line at the bottom of the window of displayed lines.

.: Place the addressed line at the center of the window.

^: Display a window of lines that is two windows prior to the addressed line.

=: Display the addressed line at the center of the window with a line of dashes above and below the addressed line.

The last line printed becomes the current line, except for the =, where the addressed line becomes the current line.

Editor Options
The command ex has a number of options that modify its behavior. These options have default settings, which can be changed using the set command (see above). Options can also be set at startup by putting a set command string in the environment variable EXINIT, or in the file .exrc in the HOME directory, or in .exrc in the current directory. If EXINIT exists, the .exrc file in the HOME directory is not executed. If the current directory is not the HOME directory and the exrc editor option is set (see below), the .exrc file in the current directory is executed after EXINIT or the HOME directory .exrc.

The editor obtains the horizontal and vertical size of the terminal screen from the terminfo database (see terminfo(4)). These values can be overridden by setting the UNIX95 environment variable, which specifies to use the XPG4 behavior for this command. COLUMNS and LINES environment variables. See the window editor option below for more information.

The following table shows the defaults that differ for the various editor personalities:

Name: Default Editor Options

_____: _______________________________________________________ edit nomagic novice noreadonly report=1 showmode

ex: magic nonovice noreadonly report=5 noshowmode vedit nomagic novice noreadonly report=1 showmode

vi: magic nonovice noreadonly report=5 noshowmode

view: magic nonovice readonly report=5 noshowmode

Editor options are Boolean unless otherwise specified. Abbreviations are shown in parentheses.

autoindent (ai): Indent each line in input mode (using blanks and tabs) to align with the previous line. Indentation begins after the line appended, or before the line inserted or the first line changed. Additional indentation can be provided as usual. Succeeding lines are automatically indented to the new alignment.

Reducing the indent is achieved by typing ^D one or more times: the cursor is moved back to the next multiple of shiftwidth spaces for each ^D. A ^ followed by a ^D removes all indentation temporarily for the current line. A 0 followed by a ^D removes all indentation.

Reversed by noautoindent (noai). The default is noautoindent.

autoprint (ap): The current line is printed after each command that changes work area text. Autoprint is suppressed in global commands. Reversed by noautoprint (noap). The default is autoprint.

autowrite (aw): The work area is written out to the current file if the work area has been modified and a next, rewind, or ! command is given. Reversed by noautowrite (noaw). The default is noautowrite.

beautify (bf): Cause all control characters other than tab, newline, and formfeed to be discarded from the input text. Reversed by nobeautify (nobf). The default is nobeautify.

directory=dirname (dir)
Specify the directory in which the editor work area should be placed. This option only takes effect when a new work area is created. It should be set in EXINIT or .exrc to affect the location of the work area file for the edit file specified on the command line. The default is /var/tmp.

If the specified directory is set from EXINIT or a .exrc file and is not writable by the user, the editor quits; if set interactively by the user, the editor issues an error message.

doubleescape: When set, two consecutive ESC (escape) characters are required to leave input mode. In input mode, a single ESC character followed by a different character causes vi to issue an audible or visual warning (see the flash editor option) and insert both characters into the work area. Reversed by nodoubleescape. The default is nodoubleescape.

The character sequences transmitted by the keyboard editing keys of some terminals are identical to some sequences of vi user commands. If the mapping of these keys is enabled (see the keyboardedit and keyboardedit! options), vi might not be able to reliably distinguish between the character sequence transmitted by an editing key and the same character sequence typed by a user. This problem is most likely to occur when the user types ESC to terminate input mode immediately followed by another vi command. If you set the doubleescape option, the ambiguity of this case is removed.

edcompatible (ed): Cause the presence of g and c suffixes on substitute commands to be remembered, and toggled by repeating the suffixes. Reversed by noedcompatible (noed). The default is noedcompatible.

errorbells (eb): When set, error messages are preceded with a bell only on terminals that do not support a standout or highlighting mode such as inverse video. If the terminal supports highlighting, the bell is never used prior to error messages and this option has no effect. Note that visual-mode errors are signaled by the bell (regardless of the setting of this option) without an accompanying error message.

Reversed by noerrorbells (noeb). The default is noerrorbells.

exrc: When set, the .exrc file in the current directory is processed during editor initialization if the current directory is not the HOME directory. This option is not set by default and must be set in the EXINIT environment variable or the HOME directory .exrc file to have any effect. See the Editor Options introductory text above. Reversed by noexrc. The default is noexrc.

flash (fl): When set, the screen flashes instead of beeping, provided an appropriate flash_screen entry is present in the /usr/share/lib/terminfo database for the terminal being used. Reversed by noflash (nofl). The default is flash.

hardtabs=number (ht)
Define the spacing between hardware tab settings and the number of spaces used by the system when expanding tab characters. Tab stops are placed in each column number (starting at the left edge of the screen) that corresponds to an integer multiple of number. The default is hardtabs=8.

ignorecase (ic): All uppercase characters in the text are mapped to lowercase in regular expression matching. Also, all uppercase characters in regular expressions are mapped to lowercase, except in character class specifications. Reversed by noignorecase (noic). The default is noignorecase.

keyboardedit: When set, any keyboard editing key mappings that are loaded automatically at initialization for command-mode use are enabled. If not set, these mappings are disabled (but not deleted). Use the map command to get a list of the currently enabled command-mode mappings. Reversed by nokeyboardedit. The default is keyboardedit.

keyboardedit!: When set, the keyboard editing key mappings automatically loaded at initialization for input mode use are enabled. If not set, these mappings are disabled (but not deleted). Use the map! command to list the currently enabled input-mode mappings. Reversed by nokeyboardedit!. The default is nokeyboardedit! for terminals whose keyboard editing keys send HP-style escape sequences (an ESC followed by a single letter). The default is keyboardedit! for all other terminals.

lisp: Modify autoindent mode and the (, ), [[, ]], {, and } commands in visual mode for lisp source code. Reversed by nolisp. The default is nolisp.

list: Display all printed lines with tabs shown as ^I, and the end of line marked by a $. Reversed by nolist. The default is nolist.

magic: Affect the interpretation of characters in regular expressions and substitution replacement strings (see Regular Expressions and Replacement Strings above). Reversed by nomagic. The ex, vi, and view default is magic. The edit and vedit default is nomagic.

mesg: Allows other users to use the write command (see write(1)) to send messages to your terminal, possibly disrupting the screen display. Unsetting this option (nomesg) blocks write permission to your terminal from other system users while you are using the editor. Reversed by nomesg. The default is mesg.

modelines (ml): If set when the editor reads in a file, any ex commands embedded in the first five and last five lines of the file are executed after .exrc and

EXINIT commands are processed but before editing control is given to the user. The ex commands must be prefixed by ex: or vi: and terminated by : in a single line. Any number of other characters with the exception of the colon (:) can precede or follow the embedded command. Reversed by nomodelines (noml). The default is nomodelines.

novice: Use the version of the editor available for novices, known as edit or vedit. Reversed by nonovice. The ex, vi, and view default is nonovice. The edit, and vedit default is novice.

number (nu): Cause lines to be printed with line numbers. Reversed by nonumber (nonu). The default is nonumber.

optimize (opt): Suppress automatic carriage returns on terminals that do not support direct cursor addressing. This streamlines text output in certain situations such as when printing multiple lines that contain leading whitespace. Reversed by nooptimize (noopt). The default is nooptimize.

paragraphs=pair-string (para)
The value of this option is a string whose successive pairs of characters specify the names of text-processing macros that begin paragraphs. (A macro appears in the text in the form .xx, where the . is the first character in the line.)

If any macros have a single-character name, use a space character to substitute for the missing second character in the name. To type a space character in such situations, precede the space with a backslash (\) to prevent the editor from interpreting it as a delimiter.

The default is paragraphs=IPLPPPQPP\ LIpplpipnpbp.

prompt: When set, command mode input is prompted for with a colon (:); when unset, no prompt is displayed. Reversed by noprompt. The default is prompt.

readonly (ro): Set the readonly flag for the file being edited, thus preventing accidental overwriting at the end of the session. This option is equivalent to invoking ex, edit, vi, or vedit with the -R option or using the view command. Reversed by noreadonly (noro). The ex, edit, vi, and vedit default is noreadonly. The view default is readonly.

redraw: Simulate an intelligent terminal on a dumb terminal. During input mode, lines are continuously reprinted as text is entered. Since this is likely to require a large amount of output to the terminal, it is useful only at high transmission speeds. If noredraw is set, lines are reprinted only when input mode is terminated and deleted lines are marked with an @ in the left margin. Reversed by noredraw. The default is redraw.

remap: If set, macro translation allows for macros defined in terms of other macros; translation continues until the final product is obtained. If unset, a one-step translation only is done. Reversed by noremap. The default is remap.

report=n: The value of n gives the number of lines that must be changed by a command before a report is displayed on the number of lines affected. If n is 5, then changes are reported for 6 or more lines. The ex, vi, and view default is report=5. The edit, and vedit default is report=1.

scroll=n: The value of n determines the number of lines scrolled by a ^D command and the number of lines displayed by the z command (twice the value of scroll). The default is half the value of the window option.

sections=pair-string
The value of this option is a string, in that successive pairs of characters specify the names of text-processing macros that begin sections. See the paragraphs editor option above. The default is sections=NHSHH\ HUuhsh+c.

shell=filename (sh) Set the file name of the shell to be used for the ! shell escape and the shell command. It defaults to the value of your SHELL environment variable, if set, and otherwise to /usr/bin/sh.

shiftwidth=n (sw): Sets the indentation step value used by autoindent and the shift (< and >) commands. The default is shiftwidth=8.

showmatch (sm): In visual mode, jump momentarily to the matching ( or { when you type a ) or }, if the match is still on the screen. Reversed by noshowmatch (nosm).

The default is noshowmatch.

showmode (smd): Display the current editor mode (such as INPUT MODE, REPLACE 1 CHAR, REPLACE MODE) in the lower right-hand corner of the screen during visual and open mode. Reversed by noshowmode (nosmd). The ex, vi, and view default is noshowmode. The edit, and vedit default is showmode.

slowopen (slow): In visual mode, slowopen prevents screen updates during input to improve throughput on unintelligent terminals. Reversed by noslowopen (noslow). The default is noslowopen.

tabstop=n (ts): Sets the spacing of the software tab stops used by the editor to expand tabs in the input file. The default is tabstop=8.

taglength=n (tl): Set the maximum number of characters that should be treated as significant in a tag. Characters beyond the limit are ignored. A value of zero means that all characters in the tag are significant. The default is taglength=0.

tags=[filename ]... Specify the tags files to be used by the tag command and the -t command-line option. The default is tags=tags /usr/lib/tags, specifying the file tags in the current directory and the file /usr/lib/tags. File names are separated by whitespace.

Each line of a tags file contains the following three fields separated by whitespace: the tag name, the name of the file to be edited, and an address specification (see Addressing above). A tags file must be sorted in order by tag name.

The ctags command (see ctags(1)) creates tags files from C, Pascal and FORTRAN source files.

tagstack (tgst): Enable the pushdown stack of activated tags. Reversed by notagstack (notgst). The default is tagstack.

When you enter a line mode tag command or visual mode ^] command, the current line number and file name are stored on the tag stack. A future line mode pop command or visual mode ^T command will return to the stored file name at the stored line number.

If the tag stack is disabled and then reenabled again, the stack continues where it left off. The pop command does not work when the tag stack is disabled.

term=termtype: Define the type of terminal being used with the editor. The default value is obtained from the TERM environment variable. If TERM is unset or null, term is set to unknown. There is no difference between the term and ttytype editor options. Setting either one results in both being changed.

terse: Use shorter error messages. Reversed by noterse. The default is noterse.

timeout (to): If set, require that all the characters of a multicharacter macro name (the first argument in a map command) must be received within the amount of time specified by the timeoutlen option in order to be accepted as a match for the macro name. If not set, no limit is placed on how long to wait for the completion of a macro name. Reversed by notimeout (noto). The default is timeout.

timeoutlen=n: Set, in milliseconds (ms), the length of the macro timeout period (see the timeout editor option). This option has no effect unless timeout is set. The value of n must be at least 1. The default is timeoutlen=500 (half a second).

ttytype=termtype (tty)
Define the type of terminal being used with the editor. See the term editor option for details. There is no difference between the term and ttytype editor options. Setting either one results in both being changed.

warn: Before executing a ! or shell command escape, display the message [No write since last change] if the work area has been modified since it was last loaded or fully written to a file. Reversed by nowarn. The default is warn.

window=lines (wi): Set the number of lines in a text window in visual mode. The default value is one less than the size of your terminal screen (as defined by the LINES environment variable, if set, or the entry for your terminal in the terminfo(4) data base otherwise). However, if the terminal baud rate (see stty(1) is set to less than 1200 or 2400, the default value is reduced to a maximum of 8 or 16 lines, respectively. The startup value can be specified with the -w command-line option.

w300=lines: If the terminal baud rate is less than 1200, set the window editor option to the value specified.

w1200=lines: If the terminal baud rate is greater than or equal to 1200 but less than 2400, set the window editor option to the value specified.

w9600=lines: If the terminal baud rate is greater than or equal to 2400, set the window editor option to the value specified.

wrapmargin=n (wm): In visual mode only, if n is greater than zero, a newline is automatically inserted in an input line at a word boundary, so that lines end at least n spaces from the right margin of the terminal screen. The default is wrapmargin=0.

wrapscan (ws): When set, editor searches using /re/ (or ?re?) continue silently from the beginning (or end) of the file upon reaching the end (or beginning) of the file (that is, the scan "wraps around"). When unset, editor searches stop at the beginning or the end of the file, as appropriate. Reversed by nowrapscan (nows). The default is wrapscan.

writeany (wa): Inhibits the checks otherwise made before write commands, allowing a write to any file (provided the system allows it). Reversed by nowriteany (nowa). The default is nowriteany.

EXTERNAL INFLUENCES

Environment Variables
COLUMNS This variable shall override the system-selected horizontal screen size.

LINES overrides the system-selected vertical screen size, used as the number of lines in a screenful and as the vertical screen size in visual mode.

PATH determines the search path for the shell command specified in the editor commands, shell, read, and write.

SHELL is variable that shall be interpreted as the preferred commandline interpreter for use in !, shell, read, and other commands with an operand of the form !string. For the shell command, the program shall be invoked with the single argument -i. For all others, it shall be invoked with the two arguments -c and string. If no SHELL environment variable is set, or it is set to a null string, the sh utility shall be used.

TERM is a variable that shall be interpreted as the name of the terminal type. If this variable is unset or null, an unspecified default terminal type shall be used.

EXINIT is a variable that shall be interpreted to contain a list of ex commands that are executed on editor startup, before reading the first file. The list can contain multiple commands by separating then using a vertical line (|) character.

HOME shall be interpreted as a pathname of a directory that shall be searched for an editor startup file name .exrc.

LC_COLLATE determines the collating sequence used in evaluating regular expressions and in processing the tags file. If it is not specified or is null, it defaults to the value of LANG.

LC_CTYPE determines the interpretation of text as single and/or multibyte characters, the classification of characters as uppercase or lowercase letters, the shifting of the case of letters, and the characters matched by character class expressions in regular expressions. If it is not specified or is null, it defaults to the value of LANG.

LANG determines the language in which messages are displayed. If it is not specified or is null, it defaults to "C" (see lang(5)).

LC_ALL determines the locale to be used to override any values for locale categories specified by the setting of LANG or any environment variable (beginning with LC_ ).

LC_MESSAGES determines the processing of affirmative responses and the language in which messages should be written.

If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see environ(5)).

When set, the TMPDIR environment variable specifies a directory to be used for temporary files, overriding the default directory /var/tmp.

International Code Set Support
Single- and multibyte character code sets are supported.

ASYNCHRONOUS EVENTS (XPG4 Only)

The following actions shall be taken upon receipt of signals:

SIGINT
When an interrupt occurs, ex shall alert the terminal and write a message. The current editor command shall be aborted, and ex shall return to the command level and prompt for another command. If the standard input is not a terminal device, ex shall exit at the interrupt and return a nonzero exit status.

SIGCONT
The screen shall be refreshed.

SHIGHUP
If the current buffer has changed since the last e or w command, ex shall attempt to save the current file in a state such that it can be recovered later by an ex -r command.

The action taken for all other signals is unspecified.

EXTENDED DESCRIPTION (XPG4 Only)

The pathname of the file being edited by ex is referred to as the current file. The text of the file shall be read into a working version of the file (called buffer in this clause), and all editing changes shall be performed on that version; the changes shall have no effect on the original file until an ex command causes the file to be written out. Lines in the buffer may be limited to { LINE_MAX } bytes, and an error message may be written if the limit is exceeded during editing.

The alternate 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 % appears in a pathname entered as part of a command argument, it shall be replaced by the altername pathname. Any character, including % and # shall retain its literal value when preceded by a backslash.

When an error occurs, ex shall alert ther terminal and write a message.

If the system crashes, ex shall attempt to preserve the buffer if any unwritten changes were made. The command-line option -r can be used to retrieve the saved changes.

During initialization (before the first file is read or any user commands from the terminal are processed), if the environment variable EXINIT is set, the editor shall execute ex commands contained in that variable. If the variable is not set, ex shall attempt to read commands from the $HOME/.exrc. If and only if EXINIT or $HOME/.exrc sets the editor option exrc, ex finally shall attempt to read commands from a file .exrc in the current directory. In the event that EXINIT is not set and the current directory is the home directory of the user, any .exrc file shall only be processed once. No .exrc shall 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 shall be processed.

By default, ex shall start in the command mode, which shall be indicated by the ":" prompt. The input mode can be entered by append, insert, or change commands. There is one other mode, visual mode, in which full screen editing is available. This is described more fully under the visual command. The command line can consist of multiple ex commands separated by vertical-line characters(|). The use of commands that enter input or visual modes in this manner, unless they are the final command on the line, produces undefined results.

Command lines beginning with the double-quote character (") shall be ignored. This can be used for comments in an editor script.

WARNINGS

The undo command causes all marks to be lost on lines that are changed and then restored.

The z command prints a number of logical rather than physical lines. More than a screenful of output can result if long lines are present.

Null characters are discarded in input files and cannot appear in resultant files.

On some systems, the recovery of an edit file with the -r option is possible only if certain system-dependent actions are taken when the system is restarted.

Edit preserve files can only be recovered on systems running the same HP-UX release in which they were preserved. Preserve files are not recoverable across different releases.

On HP terminals, the attribute field of any function key specified by a map #n ... command should be set to normal rather than to the default of transmit.

For information about line length limits, file size limits, etc., see the WARNINGS section of vi(1).