NAME

ex - text editor

 SYNOPSIS

ex [-rR][-l][-s | -v ][-c command]-t tagstring][-w size][file...]

ex [-rR][-l][- | -v ][+command][-t tagstring][-w size][file...]

 DESCRIPTION

The ex utility is a line-oriented text editor that supports both line and full-screen editing (see vi).

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 open mode . When these commands cannot be supported on such terminals, this condition will not produce an error message such as "not an editor command" nor 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. The affected commands are noted as they occur later in this section.

 OPTIONS

The ex utility supports the XBD specification, Utility Syntax Guidelines  .

The following options are supported:

-c command

+command

Begin editing by executing the specified ex command-mode commands. As with normal editing 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 or visual modes in this manner produces undefined results.

-l

(The letter ell.) Set lisp mode; indents appropriately for Lisp code; the (), {}, [[ and ]] commands in visual mode are modified to have meaning for Lisp.

-r

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 preserve editor command. A crash in this context is an unexpected failure of the system or utility that requires restarting the failed system or utility. A system crash implies that any utilities running at the time also crash. In the case of an editor or system crash, the degree of recovery (the number of changes to the buffer since the most recent preserve command) available is unspecified. 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 ex 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 will require the "!" suffix (see, for example, the write command) to be effective in this mode.

-s

-

Prepare ex for batch use by taking the following actions:

• Suppress writing prompts and informational (but not diagnostic) messages.
• Ignore the value of TERM and any implementation default terminal type and assume the terminal is a type incapable of supporting visual mode; see the visual command and the description of vi.
• Suppress the use of the EXINIT environment variable and the reading of any .exrc file (see the EXTENDED DESCRIPTION section).

-t tagstring

Edit the file containing the specified tagstring and proceed as if the first command were :tag tagstring. (See ctags.) The tags feature represented by -t tagstring and the ta command are optional. It is provided on any system that also provides a conforming implementation of ctags; otherwise, the use of -t produces undefined results.

-v

Invoke vi.

-w size

Set the value of the window editor option to size.

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 must be a text file consisting of commands, 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 ex implementations.

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

By default, ex reads 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 ex:

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 are executed on editor start-up, before reading the first file. The list can contain multiple commands by separating them using a vertical-line (|) character. See 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 start-up file named .exrc; see the EXTENDED DESCRIPTION section for details.

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.

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.

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

PATH

Determine the search path for the shell command specified in the editor commands shell, read and write; 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 no SHELL environment variable is set, or it is set to a null string, 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

When an interrupt occurs, ex will alert the terminal and write a message. The current editor command will be aborted and ex will return to the command level and prompt for another command. If the standard input is not a terminal device, ex will exit at the interrupt and return a non-zero exit status. (The alerting action can be modified by the use of the errorbells editor option; see Edit Options in ex .)

SIGCONT

The screen will be refreshed (if in visual mode).

SIGHUP

If the current buffer has changed since the last e or w command, ex will 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.

 STDOUT

The standard output is used only for writing prompts to the user, for informational messages and for writing lines from the file.

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

The output from ex must be text files that are identical to the input files if no changes have been made to the 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 file write, a trailing newline character will be added to the last line of the file if one was not present in the input.

 EXTENDED DESCRIPTION

The pathname of the file being edited by ex is referred to as the current file. The text of the file is read into a working version of the file (called buffer in this section; intermediate versions of the buffer may be kept in a file that is created in the directory indicated by the directory editor option) and all editing changes are performed on that version; the changes have no effect on the original file until an ex command causes the file to be written out. Lines in the buffer may each be limited to {LINE_MAX} bytes and an error message may be written 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, it is replaced by the current pathname; the character "#" is replaced by the alternative pathname. Any character, including "%" and "#", retains its literal value (is escaped) when preceded by a backslash.

When an error occurs, ex will alert the terminal and write a message. (The alerting action can be modified by the use of the errorbells editor option.)

If the system crashes, ex will 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 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, ex will attempt to read 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, ex finally will 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 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.

By default, ex starts in the command mode, which is indicated by the : prompt. The input mode can be entered by append, insert or change commands; it can be exited (and command mode reentered) by typing a period (.) alone at the beginning of a line. There is one other mode, visual mode, in which full-screen editing is available. This is described more fully under the visual command and in the vi utility description. 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 ( ) are ignored. This can be used for comments in an editor script.

 Addressing in ex

Addressing in ex relates to the current line. In general, the current line is the last line affected by a 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 is set to zero.

Addresses are constructed by one of the following methods:

1. The address . (period) refers to the current line.

2. The address "$" refers to the last line of the buffer.

3. The address n, where n is a decimal number, refers to the nth line of the buffer.

4. The address 'x refers to the line marked with the mark-name character x, which must be a lower-case letter of the POSIX locale. Lines can be marked with the ma or k commands described below.

5. A regular expression (RE) enclosed by slashes (/) is an address, and refers to the first line found by searching forward from the line following the current line toward the end of the buffer and stopping at the first line containing a string matching the RE. The second slash can be omitted at the end of a command line. If the wrapscan option is set, the search will wrap around to the beginning of the buffer and continue up to and including the current line, so that the entire buffer is searched.

6. An RE enclosed in question marks (?) addresses the first line found by searching backward from the line preceding the current line toward the beginning of the buffer and stopping at the first line containing a string matching the RE. The second question mark can be omitted at the end of a command line. If the wrapscan option is set, the search will wrap around from the beginning of the buffer to the end of the buffer and continue up to and including the current line, so that the entire buffer is searched.

7. An address followed by a plus sign (+) or a minus sign (-) followed by a decimal number is an offset address, and refers to the first address plus (respectively minus) the indicated number of lines. If the address is omitted, the addition or subtraction is taken with respect to the current line.

8. An address of "+" or "-" followed by a number is taken with respect to the current line number; for example, -5 is understood to mean .-5.

9. An address ending with "+" or "-" has 1 added to or subtracted from the address, respectively. As a consequence of this rule and of rule 8 above, the address "-" refers to the line preceding the current line. Moreover, trailing "+" and "-" characters have a cumulative effect; for example, -- refers to the current line less 2.

10. A percent sign (%) stands for the address pair 1,$.

Commands require zero, one or two addresses. See the descriptions of line and range in Command Descriptions in ex . Commands that require zero addresses regard the presence of an address as an error.

Adjacent addresses in a range must be separated from each other by a comma (,) or a semicolon (;). In the latter case, the current line (.) is set to the first address, and only then is the second address calculated. This feature can be used to determine the starting line for forward and backward searches (see rules 5 and 6 above). The second address of any two-address sequence corresponds to a line that follows, in the buffer, the line corresponding to the first address. The first address must be less than or equal to the second address. The first address must be greater than or equal to the first line of the editing buffer and the last address must be less than or equal to the last line of the editing buffer. Any other case is an error.

All of the following examples are valid addresses:

+++

three lines after the current line

/re/-

one line before the next occurrence of re

-2

two lines before the current line.

 Command Descriptions in ex

The following symbols are used in this section to represent optional modifiers. Any or all can be omitted; the defaults are shown.

line

A single line address, given in any of the forms described in Addressing in ex ; the default for line is the current line.

range

A line, or a pair of line addresses, separated by a comma or semicolon (see Addressing in ex for the difference between the two); the default for range is the current line only (.,.). A percent sign (%) stands for the range (1,$). If the range specified is such that the starting address exceeds the ending address, the range is invalid and the command will not be performed. If more than the expected number of addresses are given in a range, the greatest valid number of the last ones given will be used. For example, 1,3,5p prints lines 3 to 5, inclusive (because two is the greatest valid number in the range accepted by print).

count

A positive integer, specifying the number of lines to be affected by the command; the default for count is 1.

flags

One of the characters "#", p or l (ell), or both "#" and l to add numbers to list-format output. When a command with such a flag completes, the addressed lines will be written out as if by the corresponding #, p or l command. The use of flags applies to all lines written by the list, number, open, print, substitute, visual, & and z commands; for other commands, it applies to the current line at the completion of the command. In addition, any number of "+" or "-" characters can also be given after the flags, in which case the line written is not the one affected by the command, but rather the line addressed by the offset address as described above. The default for flags is null.

buffer

One of a number of named areas for saving text. The named buffers are specified by the lower-case letters of the POSIX locale. Specifying buffer causes 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 command and the visual mode put commands (p and P) to specify the buffer that will provide the text to insert. 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 command) the buffer name can be specified in lower-case or upper-case with the same results. There is 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 is placed in buffer 1, the previous contents of buffer 1 are 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 does 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.

file

A pattern used to derive a pathname; the default is the current file, as defined above. If no current file has yet been established, a warning will be written and the command will be aborted, except where specifically noted in the individual command descriptions that follow. The pattern will be subjected to the process of shell word expansions (see Word Expansions ); if more than a single pathname results and the command is expecting one file, the effects are unspecified.

word

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 line 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 a range are specified for a command that uses them, the number of lines affected will be taken from the count value rather than the range. The starting line for the command is taken to be the first line addressed by the range.

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

Zero or more blank characters can precede or follow the addresses, count, flags or command name. Any object following a command name (such as buffer, file and so on) that begins with an alphabetic character will be separated from the command name with at least one blank character.

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. For example, the args command (shown as ar[gs] in the Synopsis) can be entered as ar, arg or args.

 Abbreviate

Synopsis: ab[brev] word rhs

Add the named abbreviation to the current abbreviation list. In visual mode, if word is typed so that it is preceded and followed by characters that cannot be part of a word (as defined previously), it will be replaced by the string rhs.

 Append

Synopsis: [line] a[ppend][!]

Enter input mode; the input text will be placed after the specified line. If line 0 is specified, the text will be placed at the beginning of the buffer. The current line indicator will be set to the last input line; if no lines are input, it will be set to the target line, or to the first line of the file if a target of 0 was specified. Following the command name with ! causes the autoindent editor option setting to be toggled for the duration of this command only.

 Arguments

Synopsis: ar[gs]

Write the argument list with the current argument inside "[" and "]". The argument list is the list of operands on start-up, which can subsequently be replaced by the operands of the next command.

 Change

Synopsis: [range] c[hange][!] [count]

Enter input mode; the input text will replace the specified lines (range). The current line indicator will be set to the last line input; if no lines were input, it will be set to the line before the target line, or to the first line of the file if there are no lines preceding the target. Following the command name with "!" causes the autoindent editor option setting to be toggled for the duration of this command only.

 Change Directory

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

Change the current working directory to directory. The argument will be subjected to the process of shell word expansions (see Word Expansions ). When invoked with no directory argument, and the HOME environment variable is set to a non-empty value, the directory name in the HOME environment variable will become the new working directory. If HOME is empty or undefined, the default behaviour is implementation-dependent. If the current buffer has been modified since the last write, a warning will be written and the command will fail. This warning can be overridden by appending "!" to the command name, which will allow the command to complete.

 Copy

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

Place a copy of the specified lines (range) after the specified destination line; line 0 specifies that the lines will be placed at the beginning of the buffer.

 Delete

Synopsis: [range] d[elete] [buffer] [count] [flags]

Delete the specified lines from the buffer. If a named buffer is specified, the deleted text will be saved in it; otherwise, the deleted text will be saved in the unnamed buffer. If the command name is followed by a letter that could be interpreted as either a buffer name or a flag value (because neither a count nor an additional flags value was given), ex will consider the letter to be a flags value if the letter directly follows the command name, without any blank character separation; if the letter is preceded by one of more blank characters, it is considered a buffer name.

For example:

1dp or 1deletep

Deletes the first line and prints the line that was second.

1d p

Deletes the first line, saving it in buffer p.

1d p1l

(Pee-one-ell.) Deletes the first line, saving it in buffer p, and listing the line that was second.

The current line indicator will be set to the line following the deleted lines, or to the last line if the deleted lines were at the end.

 Edit

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

Begin editing file. If the current buffer has been modified since the last write, a warning will be written and the command will be aborted. This action can be overridden by appending the character "!" to the command name (e! file). The current line indicator will be affected as follows:

• If file is omitted or results in the current file, the current line indicator will not be changed.

• Otherwise, the current line indicator will be the last line of the buffer; however, if this command is executed from within visual mode, the current line indicator will be the first line of the buffer.

If the +line option is specified, the current line indicator will be set to the specified position, where line can be a number (or "$") or specified as "/pattern" or "?pattern". Preceding the pattern with a "/" will start a search from the beginning of the file. Preceding the pattern with a "?" will start a search from the end of the file. This command is affected by the editor options autowrite and writeany.

 File

Synopsis: f[ile] [file]

Write the current pathname, the number of lines, and the current position when no file argument has been specified; ex may write other unspecified information. If no current file has yet been established, an unspecified message will be written to indicate that no file is being edited. With file, ex will change the current filename to file without changing the contents of the buffer or the previous current file.

 Global

Synopsis: [range] g[lobal] /pattern/ [commands]
Synopsis: [range] v /pattern/ [commands]

Mark the lines within the given range that match (g) or do not match (v) the given pattern. Then execute the ex commands given by commands with the current line (.) set to each marked line. The range defaults to the entire file.

Multiple commands can be specified, one per line, by escaping each newline character with a backslash. If commands are omitted, each line will be written. For the append, change and insert commands, the input text will be included as part of the global command line; in this case the terminating period can be omitted if it ends commands. The visual command can be specified as one of the commands. In this mode, input will be taken from the terminal. Entering a Q from visual mode causes the next line matching the pattern to be selected and visual mode to be reentered, until the list is exhausted.

The global command itself and the undo command cannot be used in commands. The editor options autoprint, autoindent and report will be inhibited for the duration of the g or v command.

 Insert

Synopsis: [line] i[nsert][!]

Enter input mode; the input text will be placed before the specified line. The current line indicator will be set to the last line input; if no lines were input, it will be set to the line before the target line, or to the first line of the file if there are no lines preceding the target. Following the command name with the character "!" causes the autoindent editor option setting to be toggled for the duration of this command only.

 Join

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

Join the text from the specified lines together into one line. In the POSIX locale, when the last character on the first line of a pair of lines to be joined is a period, two space characters will be added following the period; when the last character of the first line is a blank character or when the first character on the second line of the pair is a ")", no space characters will be added; otherwise, one space character will be added following the last character of the first line. Extra blank characters at the start of a line will be discarded.

Appending a character "!" to the join command name causes a simpler join with no white-space processing, independent of the current locale.

 List

Synopsis: [range] l[ist] [count] [flags]

Write the addressed lines in a way that should be unambiguous: non-printable characters will be written as implementation-dependent multi-character sequences; the end of the line will be marked with a "$".

Long lines will be folded; the length at which folding occurs is unspecified, but should be appropriate for the output device. The only useful flag is "#", for line numbers. The current line indicator will be set to the last line written.

 Map

Synopsis: map[!] [x rhs]

Define macros for use in visual mode. The first argument must be a single character or the sequence #digit (the latter meaning one of the terminal's numbered function keys). When this character or function key is typed in visual mode, the action will be as if the corresponding rhs had been typed. If the character "!" is appended to the command name map, the mapping is effective during input mode rather than command mode. This allows x to have two different macro definitions at the same time: one for command mode and one for input mode. Non-printable characters, except for a tab character, require escaping with a <control>-V (or <control>-Q) to be entered in the arguments. On certain block-mode terminals, the mapping need not occur immediately (for example, it may occur after the terminal transmits a group of characters to the system), but it will achieve the same results of modifying the file as if it occurred immediately. Implementations may restrict the set of commands accepted within rhs; the list of restrictions is implementation-dependent.

The map command with no arguments will write all of the macros currently defined. If "!" is appended to the command, only the macros effective during input mode will be written; otherwise, only the macros effective during command mode will be written.

 Mark

Synopsis: [line] ma[rk] x
Synopsis: [line] k x

Give the specified line the specified mark x, which must be a single lower-case letter of the POSIX locale. The current line position will not be affected. The expression 'x can then be used as an address in any command requiring one. For example ".,'xd" deletes all the lines from the current one to the marked line. Also see the vi `` and '' commands for uses of the mark in visual mode. If the 'x command is used in non-visual mode, the character marked will be the first non-blank character of the current line. Otherwise, the character marked will be the character at the current column of the current line.

 Move

Synopsis: [range] m[ove] line

Move the specified lines (range) to be after the target line (line). The current line indicator will be set to the first of the moved lines.

 Next

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

Edit the next file from the argument list. If the current buffer has been modified since the last write, a warning will be written and the command will be aborted. This action can be overridden by appending the character "!" to the command name (n!). The argument list can be replaced by specifying a new one as operands to this command. Editing then starts with the first file on this new list. The current line indicator will be reset as described for the edit command. This command is affected by the editor options autowrite and writeany; see Edit Options in ex for details.

 Number

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

Write the selected lines, each preceded with its line number in decimal. Non-printable characters, except for a tab character, will be expanded as specified by the print command. The format is as follows:

"%+6d\t%s", <line number>, <line text>

The only meaningful flag is l, which causes the additional expanded writing of tab characters and end-of-lines done by the list command to be performed. The current line indicator will be set to the last line written.

 Open

Synopsis: [line] o[pen] /pattern/ [flags]

Enter open mode, which is equivalent to visual mode with a one-line window. All the visual mode commands are available. If a match is found for the optional regular expression in line, the cursor will be placed at the start of the matching pattern. The visual mode command Q (see vi) will exit open mode. This command need not be supported on block-mode terminals.

 Preserve

Synopsis: pre[serve]

Save the current buffer in a form that can later be recovered by using ex -r or by using the recover command. After the file has been preserved, a mail message will be sent to the user. This message can be read by invoking the mailx utility. The message will 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

Synopsis: [range] p[rint] [count] [flags]

Write the addressed lines. Non-printable characters, except for the tab character, will be written as implementation-dependent multi-character sequences.

Long lines will be folded; the length at which folding occurs is unspecified, but should be appropriate for the output device. The only meaningful flags are "#" and l. The current line indicator will be set to the last line written.

 Put

Synopsis: [line] pu[t] [buffer]

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

 Quit

Synopsis: q[uit][!]

Terminate the editing session. If the current buffer has been modified since the last write, a warning will be written and the command will fail. This warning can be overridden and an exit forced, discarding changes, by appending the character "!" to the command name.

 Read

Synopsis: [line] r[ead][!] [file]

Place a copy of the specified file in the current buffer 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 there is no current file, then file will become the current file. If there is no current file nor file operand, the command will fail.

The current line indicator will be set to the last line read. In visual mode, the current line indicator will be set to the first line read. If file is preceded by "!", file is taken to be an operating system command and passed to the program named in the SHELL environment variable; the resultant output will be read in to the buffer. The special meaning of "!" can be overridden by escaping it with a backslash character.

 Recover

Synopsis: rec[over] file

Attempt to recover file if it was saved as the result of a preserve command, the receipt of a signal (see the ASYNCHRONOUS EVENTS section), or a system or editor crash. The current line indicator will be reset as described for the read editor command.

 Rewind

Synopsis: rew[ind][!]

Rewind the argument list; that is, the current file will be set to the first file in the argument list. This is 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 will be written and the command will be aborted. The action can be overridden by appending the character "!" to the command name (rew!). The current line indicator will be reset as described for the read editor command. This command is affected by the editor options autowrite and writeany; see Edit Options in ex for details.

 Set

Synopsis: se[t] [option[=[value]] ...] [nooption ...] [option? ...] [all]

When no arguments are specified, write those options whose values have been changed from the default settings; when the argument all is specified, write all of the option values.

Giving an option name followed by the character "?" causes the current value of that option to be written. The "?" can be separated from the option name by zero or more blank characters. The "?" is necessary only for Boolean valued options. Boolean options can be given values by the form se option to turn them on or se nooption to turn them off; string and numeric options can be assigned by the form seoption Blank characters in strings can be included as is by preceding each such character with a backslash. More than one option can be set or listed by a single set command by specifying multiple arguments, each separated from the next by one or more blank characters.

See Edit Options in ex for further details about options.

 Shell

Synopsis: sh[ell]

Invoke the program named in the SHELL environment variable with the argument -i (interactive mode). Editing will be resumed when the program exits.

 Source

Synopsis: so[urce] file

Read and execute commands from the file specified by the mandatory argument file. Such so commands can be nested. The maximum supported nesting depth is implementation-dependent, but will be at least one.

 Substitute

Synopsis: [range] s[ubstitute] [/pattern/repl/[options] [count] [flags]]

Replace the first instance of the pattern pattern by the string repl on each specified line. (See Regular Expressions in ex and Replacement Strings in ex .) If the /pattern/repl/ argument is not present, the /pattern/repl/ from the previous substitute command will be used. If options includes the letter g (global), all non-overlapping instances of the pattern in the line will be substituted. If the option letter c (confirm) is included, then before each substitution the line will be written with ^ characters written on the following line, adjacent to and identifying the pattern to be replaced; an affirmative response causes the substitution to be done, while any other input aborts it. An affirmative response consists of a line with the affirmative response (as defined by the current locale) at the beginning of the line. Such a line will be subject to editing in the same way as the command line (the "/" or ":" line at the bottom of the screen). The current line indicator will be set to the last line substituted. When the c option is used, typing the interrupt character or receiving the SIGINT signal will stop the substitute operation and ex will return to command mode. All substitutions completed before the interrupt occurred will be retained, and none will be made after that point. The current line indicator will be set to the last line substituted. This command is affected by the LC_MESSAGES environment variable and the wrapscan option.

 Suspend

Synopsis: su[spend][!]
Synopsis: st[op][!]

Allow control to return to the invoking process; ex will suspend itself as if it had received the SIGTSTP signal. The suspension will occur only if job control is enabled in the invoking shell (see the description of set -m).

Following either suspend or stop with the character "!" will affect the operation of the autowrite editor option for this command only.

The current susp character (see stty) will also cause the suspension.

 Tag

Synopsis: ta[g][!] tagstring

Search for the tagstring, which can be in a different file. If the tag is in a different file, then the new file will be opened for editing. If the current buffer has been modified since the last write, a warning will be written and the command will be aborted. The action can be overridden by appending the character "!" to the command name. The current line indicator will be reset to the line indicated by the tag. This command is affected by the editor options autowrite and writeany; see Edit Options in ex and ctags for details. This command is affected by the tags editor option.

The tag command will search for tagstring in the tag file referred to by the tags editor option until a reference to tagstring is found. The file pointed to by this reference will be loaded into the buffer, and the current line will be set to the first occurrence of the pattern specified in the tag file associated with the supplied tagstring; if the tag file contained a line-number reference, the current line will be set to that line. If the pattern or line number is not found, an error message will be written. If a file referred to by the tags editor option does not exist or is not readable, an error message will be written. The results are unspecified if the format of a tags file is not as specified by the ctags utility description.

 Unabbreviate

Synopsis: una[bbrev] word

Delete word from the list of abbreviations, as described by the abbrev editor command.

 Undo

Synopsis: u[ndo]

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

 Unmap

Synopsis: unm[ap][!] x

If no "!" is specified, remove the command-mode macro definition for x; otherwise, remove the input-mode macro definition for x. See the map command.

 Visual

Synopsis: [line] vi[sual] [type] [count] [flags]

Enter visual mode with the current line indicator set to line. The type is optional, and can be "-", ".", "+" or "^", as in the z 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 the number of lines that will initially be written; the default is the value of the editor option window. The command Q will exit visual mode. (For more information, see vi.) This command need not be supported on block-mode terminals.

 Write

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

Write the specified lines (the whole buffer, if no range is given) out to the file represented by the pathname file, writing to standard output the number of lines and bytes written.

If file is specified and is not the current file, and the file named by file exists, then the write will fail. If the current file has been changed by the file command and that file exists, the write will fail. In either case, the write can be forced by appending the character "!" to the command name. An existing file can be appended to by appending >> to the command name. If the file does not exist, the result is implementation-dependent.

If the file is preceded by "!", the program named in the SHELL environment variable will be invoked with file as its second argument, and the specified lines will be passed as standard input to the command. The ! in this usage must be separated from the w command by at least one blank character. The special meaning of the ! can be overridden by escaping it with a backslash character. This command is affected by the editor options writeany and readonly.

The command wq is equivalent to a w followed by a q; wq! is equivalent to w! followed by q. If the current buffer has no pathname associated with it, the write command will fail.

 Write and Exit

Synopsis: [range] x[it][!] [file]

Perform a write command if any changes have been made to the current buffer since the last write to any file. The range defaults to the entire file.

Unless the command fails because an attempt to write lines to a file did not succeed, the ex utility will exit after an x command. This command is affected by the editor options writeany and readonly.

 Yank

Synopsis: [range] ya[nk] [buffer] [count]

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

 Adjust Window

Synopsis: [line] z [type] [count] [flags]

If type is omitted, then count lines following the specified line (line) will be written. The default for count is the value of the editor option window. The type argument will change the position at which line will be written on the screen by affecting the number of lines written before and after line.

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

-

Place line at the bottom of the screen.

+

Place line at the top of the screen.

.

Place line in the middle.

^

Write out count lines starting count*2 lines before the addressed line; the net effect of this will be that a z^ command following another z command writes the previous page.

=

Centre the addressed line on the screen with a line of hyphens written immediately before and after it. The number of preceding and following lines of text written will be reduced to account for these lines of hyphens.

In all cases the current line indicator will be set to the last line written, with the exception of the "=" type, which causes the current line indicator to be set to that addressed in the command.

 Escape

Synopsis: ! command
Synopsis: [range]! command

Pass the remainder of the line after the ! character to the program named in the SHELL environment variable for execution. A warning will be issued if the buffer has been changed since the last write. A single ! character will be written when the command completes. The current line position will not be affected.

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 ! command. (Thus, !! will repeat the previous ! command.) If any such expansion is done, the expanded line will be echoed.

The special meanings of %, # and ! can be overridden by escaping them with a backslash character. This command is affected by the editor options autowrite and writeany; see Edit Options in ex for details.

In the second form of the ! command, the remainder of the line after the ! will be passed to the program named in the SHELL environment variable, as described above. The specified lines will be provided to the program as standard input; the resulting output will replace the specified lines.

 Shift Left

Synopsis: [range] < [count] [flags]

Shift the specified lines to the left; the number of character positions to be shifted will be determined by the editor option shiftwidth. Only leading blank characters will be lost in shifting; other characters will not be affected. The current line indicator will be set to the last line changed.

 Shift Right

Synopsis: [range] > [count] [flags]

Shift the specified lines to the right, by inserting blank characters, using tab characters where possible, as determined by the editor option shiftwidth. Empty lines will not be changed. The current line indicator will be set to the last line changed.

 Resubstitute

Synopsis: [range] & [options] [count] [flags]
Synopsis: [range] s[ubstitute] [options] [count] [flags]
Synopsis: [range] ~ [options] [count] [flags]

Repeat the previous substitute command, as if & were replaced by the previous:

s/pattern/repl/

command. The same effect can obtained by omitting the:

/pattern/repl/

string in the substitute command. The version of the command using tilde will be the same as & and s, but the pattern used will be the last regular expression used in any command, not necessarily the one used in the last substitute command. For example, in the sequence:

s/red/blue/
/green
~

the "~" is equivalent to:

s/green/blue/

 Scroll

Synopsis: eof

Write the next n lines, where n is the value of the editor option scroll. The command is invoked with the eof character (see the description of the stty eof character). The current line indicator will be set to the last line written. This command need not be supported on block-mode terminals.

 Write Line Number

Synopsis: [line] = [flags]

Write the line number of the specified line (default last line). The current line position will not be affected.

 Execute

Synopsis: @ buffer
Synopsis: * buffer

Execute each line of the named buffer as an ex command. If no buffer is specified or is specified as "@" or "*", the last buffer executed will be used. If there is no last buffer, an error occurs.

 Regular Expressions in ex

The ex utility supports the basic regular expressions described in the XBD specification, Basic Regular Expressions  . A null RE (//) is equivalent to the last RE encountered.

Regular expressions can be used in addresses to specify lines and, in some commands (for example, the substitute command), to specify portions of a line to be substituted.

The following constructs can be used to enhance the basic regular expressions:

\<

Match the beginning of a word. (See the definition of word at the beginning of Command Descriptions in ex .)

\>

Match the end of a word.

~

Match the replacement part of the last substitute command. The tilde (~) character can be escaped in a regular expression to become a normal character with no special meaning.

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 "~" are treated as ordinary characters unless preceded by a "\"; when preceded by a "\" they regain their special meaning.

 Replacement Strings in ex

The character & (\& if the editor option nomagic is set) in the replacement string will stand for the text matched by the pattern to be replaced. The character ~ (\~ if nomagic is set) will be replaced by the replacement part of the previous substitute command. The sequence \n where n is an integer, will be replaced by the text matched by the pattern enclosed in the nth set of parentheses \( and \).

The strings \l, \u, \L and \U can be used to modify the case of elements in the replacement string (using the \& or \<digit> notation. The string \l (\u) causes the first character (actually inserted by the substitution) that follows the \l (\u) to be converted to lower-case (upper-case). The strings \L (\U) causes all characters subsequent to them to be converted to lower-case (upper-case) as they are inserted by the substitution until the string \e or \E, or the end of the replacement string, is encountered.

An example of case conversion with the s command is as follows:

:p
The cat sat on the mat.
:s/\<.at\>/\u&/gp
The Cat Sat on the Mat.
:s/S\(.*\)M/S\U\1\eM/p
The Cat SAT ON THE Mat.

In visual mode, a <control>-V <control>-M (or <control>-Q <control>-M) sequence in the replacement string will be mapped to a newline character, and so can be used to split lines. A literal <control>-M requires escaping by preceding it with a backslash (\^V^M or \^Q^M).

 Edit Options in ex

The ex utility has a number of options that modify its behaviour. These options have default settings, which can be changed using the set command.

Options are Boolean unless otherwise specified.

 autoindent, ai

[Default off]

If autoindent is set, each line in input mode will be indented (using first as many tab characters as possible, as determined by the editor option tabstop, and then using space characters) to align with the previous line. (Starting indentation will be determined by the line appended after, or the line inserted before or the first line changed, with an a, i or c command, respectively.) When a newline character is inserted in the middle of a line, and when autoindent is on, the first non-blank character to the right of the cursor will be aligned to the current margin on a new line immediately following the current line. Any blank characters to the left of the cursor position at which the newline character was entered will be retained. When autoindent is off, a new line will be created, but no blank characters will be discarded. Additional indentation can be provided as usual; succeeding lines will automatically be indented to the new alignment. A line entered during input mode with autoindent that contains no user-entered characters will be empty, despite the appearance of indentation during entry.

Reducing the indent can be achieved when the cursor is at the current left margin by typing <control>-D one or more times; the cursor will be moved back to the previous integral number of shiftwidth spaces for each <control>-D. A ^ followed by a <control>-D will remove all indentation temporarily (for the current line); a 0 followed by a <control>-D will remove all indentation permanently (for the current line and subsequent lines until input mode is reentered or until the indentation is specifically set to some other value). Changing the indent with <control>-D need not be supported on block-mode terminals.

 autoprint, ap

[Default on]

If autoprint is set, the current line will be written after each command that changes buffer text. (Autoprint will be suppressed in the global [g and v] commands and for any command on which print operands [flags] are used to write explicitly the current line.)

 autowrite, aw

[Default off]

If autowrite is set, when a next, rewind, tag, edit, suspend, stop or "!" command is given, the buffer will be written (to the current file) if it has been modified. Appending the character "!" to the command name for any of these commands except "!" causes the write not to occur. If the write fails, the command will be aborted and an error message will be written.

 beautify, bf

[Default off]

If beautify is set, all non-printable characters, other than tab, newline and form-feed characters, will be discarded from text read in from files.

 directory, dir

[Default implementation-dependent]

The value of this option specifies the directory in which the editor buffer is to be placed. If this directory is not writable by the user, the editor quits.

 edcompatible, ed

[Default off]

Causes the presence of g and c suffixes on substitute commands to be remembered, and toggled by repeating the suffixes.

 errorbells, eb

[Default off]

If errorbells is set, error messages will be preceded by an alert action. Setting this option off causes the user to be informed of an error even when in visual mode, but rather than using the alert character, an error message will be written, using a standout mode of the terminal (such as inverse video) instead of the normal effect of the alert character, when the effect of the alert character is to cause the terminal to ring a bell or make other sounds. The editor should place the error message in a standout mode of the terminal, such as inverse video instead of ringing the bell, when the terminal capabilities allow this.

 exrc

[Default off]

If exrc is set, ex will access any .exrc file in the current directory, as described previously. If exrc is not set, ex will ignore any .exrc file in the current directory during initialisation, unless the current directory is that named by the HOME variable.

 ignorecase, ic

[Default off]

If ignorecase is set, characters that have upper-case and lower-case representations will have those representations considered as equivalent for purposes of regular expression comparison.

 lisp

[Default off]

Autoindent mode and the (, ), {, }, [[ and ]] commands in visual mode are suitably modified for lisp code.

 list

[Default off]

If list is set, write the addressed lines in a way that should be unambiguous: non-printable characters will be written as implementation-dependent multi-character sequences; the end of the line will be marked with a "$".

 magic

[Default on]

If magic is set, change the interpretation of characters in regular expressions and substitution replacement strings (see Regular Expressions in ex and Replacement Strings in ex ).

 mesg

[Default on]

If mesg is set, the permission for others to use the write or talk commands to write to the terminal will be turned on while in visual mode. The shell-level command mesg n takes precedence over any setting of the ex mesg option; that is, if mesg y was issued before ex started (or in a shell escape), such as:

:!mesg y

the mesg option in ex can suppress incoming messages, but the mesg option cannot enable incoming messages if mesg n was issued.

 number, nu

[Default off]

If number is set, lines will be written with line numbers, as with the number command.

 paragraphs, para

[Default implementation-dependent]

The paragraph option defines additional paragraph boundaries for the { and } commands in visual mode. The paragraph option can be set to a character string consisting of zero or more character pairs. The default value is implementation-dependent.

In the text to be edited, the character string <newline>. char-pair , where <char-pair> is one of the character pairs found in paragraph, defines a paragraph boundary. For example, if:

paragraph=LaA ##

then all of the following additional paragraph boundaries would be recognised:

<newline>.La
<newline>.A<space>
<newline>.##

 prompt

[Default on]

If prompt is set, command mode input will be prompted for with a colon (:); when unset, no prompt will be written.

 readonly

[Default see text]

If readonly is set, read-only mode will be enabled. Writing to a different file will be allowed in read-only mode; in addition, the write can be forced by using the character "!" (see the editor command write). The default setting will be off unless the file lacks write permission or the command-line option -R is used.

 redraw

[Default off]

The editor simulates an intelligent terminal on a dumb terminal. (Since this is likely to require a large amount of output to the terminal, it is useful only at high transmission speeds.)

 remap

[Default on]

If remap is set, macro translation will allow for macros defined in terms of other macros; translation will continue until the final product is obtained. If unset, only a one-step translation will be done.

 report

[Default 5]

The value of this option will give the number of lines that can be changed by an editor command before a report is generated on the number of lines affected.

 scroll

[Default window/2]

The value of this option will determine the number of lines scrolled on a eof command (see Scroll and the description of the stty eof character). Changing the value of window in EXINIT , one of the .exrc files, or with a set command will not affect the value of scroll. This editor option need not be supported on block-mode terminals.

 sections

[Default implementation-dependent]

The sections option defines additional section boundaries for the [[ and ]] commands in visual mode. The sections option can be set to a character string consisting of zero or more character pairs. The default value is implementation-dependent.

In the text to be edited, the character string <newline>. char-pair , where <char-pair> is one of the character pairs found in sections, defines a section boundary in the same manner that paragraph boundaries are defined. (See the paragraphs command.)

 shell, sh

[Default from the environment SHELL ]

The value of this option can be a string representing the pathname of the shell to be invoked for the "!" shell escape command, and by the shell command. The default is taken from the SHELL variable in the environment; see the ENVIRONMENT VARIABLES section for default values for SHELL .

 shiftwidth, sw

[Default 8]

The value of this option gives the width of an indentation level used during autoindent and by the shift commands.

 showmatch, sm

[Default off]

If showmatch is set, in visual mode, when a ")" or "}" is typed, the matching "(" or "{" will be shown if it is still on the screen. This editor option need not be supported on block-mode terminals.

 showmode

[Default off]

If showmode is set, in visual mode, the current mode that the editor is in will be written on the last line of the screen. Modes that will be reported are command mode and input mode; other unspecified modes may be written.

 slowopen

[Default off]

In visual mode, this option prevents screen updates during input to improve throughput on unintelligent terminals.

 tabstop, ts

[Default 8]

The value of this option specifies the software tab stops to be used by the editor to expand tabs in the input.

 tags

[Default see text]

The value of this option can be a string representing space-character-separated pathnames that will be used as tag files for the tag command. A requested tag will be searched for sequentially in the specified files. By default, filenames of tags will be searched for in the current directory and in other implementation-dependent directories.

 term

[Default from the environment TERM ]

The value of this option can be a string representing the terminal type of the output device. The default is taken from the TERM variable in the environment; see the ENVIRONMENT VARIABLES section for default values for TERM .

 terse

[Default off]

If terse is set, error messages may be less verbose. However, except for this caveat, error messages are unspecified. Furthermore, not all error messages need change for different settings of this option.

 warn

[Default on]

If warn is set, ex will write a warning message to standard error if the contents of the buffer have not been saved before a "!" command escape.

 window

[Default see text]

The value of this option determines the default number of lines in a screenful, as written by the z command. When in visual mode, the number of lines output when moving up or down the file by a screenful. The value of window can be unrelated to the real screen size, except that it will be set on entry to be the current number of screen lines. (The current number of screen lines will be determined by the system or overridden by the user, as described for LINES in the ENVIRONMENT VARIABLES section and the XBD specification, Environment Variables  .) The baud rate of the terminal line may reduce the default in an implementation-dependent manner. The default value of windows also can be overridden by specifying a window size using the -w command-line option.

 wrapscan, ws

[Default on]

If wrapscan is set, searches (using // or ??) will wrap around the end of the editing buffer; when unset, searches will stop at the beginning of the editing buffer for ??, or at the end of the editing buffer for //.

 wrapmargin, wm

[Default 0]

If the value of this option is greater than zero (say n) in visual mode during text entry, then, in the POSIX locale, a newline character will replace all consecutive blank characters, at the boundary between a blank character and a non-blank character, so that lines will end at least n spaces from the ending margin of the terminal screen. (The ending margin will be determined by the system or overridden by the user, as described for COLUMNS in the ENVIRONMENT VARIABLES section and the XBD specification, Environment Variables  .) If a line consists of a sequence of non-blank characters long enough such that it extends continuously from the beginning margin to beyond the ending margin, that sequence will not be broken by the action of this option. If the value is zero, no wrapping will be performed.

 writeany, wa

[Default off]

If writeany is set, file-overwriting checks will be inhibited that would otherwise be made before write and xit commands, or before an automatic write (see editor option autowrite), allowing a write to any file (provided permissions allow it).

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

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

• If the standard input is a terminal device file, all input will be flushed, and a new command read.

• If the standard input is a regular file, ex will terminate with a non-zero exit status.

• If the command in error was one of those specified with the command-line -c option (or the obsolescent "+" option), all of the remaining -c commands will be flushed, and a new command read from standard input.

 APPLICATION USAGE

If a SIGSEGV signal is received while ex is saving a file, the file might not be successfully saved.

The next command can accept more than one file, so usage such as:

next `ls [abc]*`

is valid; it would not be valid for the edit or read commands, for example, because they expect only one file and unspecified results occur.

 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

ed, sed, vi.