EX(1POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 ex(1POSIX) — POSIX Programmer's Manual 💖

okay bestie, welcome to ex, straight out of the POSIX Programmer's Manual. Buckle up, she's a whole legend. 🎀

🌸 PROLOG 🌸

so like, real talk first: this manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (fr, go check the corresponding Linux manual page for the deets on Linux behavior), or honestly the interface may not even be implemented on Linux at all. 💀

✨ NAME ✨

ex — text editor. that's it, that's the name. icon behavior. 💅

🦋 SYNOPSIS 🦋

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

look at her. gorgeous. ✨

💜 DESCRIPTION 💜

okay so the ex utility is a line-oriented text editor. There are two other modes of the editor — open and visual — in which screen-oriented editing is available. This is described more fully by the ex open and visual commands and in vi. bestie she's got range. 👑

If an operand is -, the results are unspecified. (iykyk — don't do it, it's giving chaos. 🙈)

This section uses the term edit buffer to describe the current working text. No specific implementation is implied by this term. All editing changes are performed on the edit buffer, and no changes to it shall affect any file until an editor command writes the file. like, she holds it in her head until she's ready. 💅

Certain 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 shall not produce an error message such as ``not an editor command'' or report a syntax error. The implementation may either:

accept the commands and produce results on the screen that are the result of an unsuccessful attempt to meet the requirements of this volume of POSIX.1‐2017, or
report an error describing the terminal-related deficiency.

either way, no fake error messages, no cap. 🫶

💅 OPTIONS 💅

The ex utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines, except for the unspecified usage of -, and that + may be recognized as an option delimiter as well as -. (she's flexible like that. 🎀)

The following options shall be supported:

-c command — Specify an initial command to be executed in the first edit buffer loaded from an existing file (see the EXTENDED DESCRIPTION section). Implementations may support more than a single -c option. In such implementations, the specified commands shall be executed in the order specified on the command line. ⭐
-r — Recover the named files (see the EXTENDED DESCRIPTION section). Recovery information for a file shall be saved during an editor or system crash (for example, when the editor is terminated by a signal which the editor can catch), or after the use of an ex preserve 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 number of changes to the edit buffer (since the most recent preserve command) that will be recovered is unspecified.

If no file operands are given and the -t option is not specified, all other options, the EXINIT variable, and any .exrc files shall be ignored; a list of all recoverable files available to the invoking user shall be written, and the editor shall exit normally without further action. she just shows you the receipts and dips. 💀

-R — Set readonly edit option. (look, don't touch. 🙈)
-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 open or visual modes; 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.
- Suppress autoindentation, ignoring the value of the autoindent edit option.

four things, all at once, she's efficient like that. ✨

-t tagstring — Edit the file containing the specified tagstring; see ctags. The tags feature represented by -t tagstring and the tag command is optional. It shall be provided on any system that also provides a conforming implementation of ctags; otherwise, the use of -t produces undefined results. On any system, it shall be an error to specify more than a single -t option. one tag, one time, periodt. 🚫
-v — Begin in visual mode (see vi). 👑
-w size — Set the value of the window editor option to size.

🌈 OPERANDS 🌈

The following operand shall be supported:

file — A pathname of a file to be edited. 💖

🍓 STDIN 🍓

The standard input consists of a series of commands and input text, as described in the EXTENDED DESCRIPTION section. The implementation may limit each line of standard input to a length of {LINE_MAX}.

If the standard input is not a terminal device, it shall be as if the -s option had been specified. (no tty? she's going batch mode automatically, she's got you. 🫶)

If a read from the standard input returns an error, or if the editor detects an end-of-file condition from the standard input, it shall be equivalent to a SIGHUP asynchronous event. 😭

🧚 INPUT FILES 🧚

Input files shall 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. By default, any incomplete last line shall be treated as if it had a trailing <newline>. The editing of other forms of files may optionally be allowed by ex implementations. 💜

The .exrc files and source files shall be text files consisting of ex commands; see the EXTENDED DESCRIPTION section.

By default, the editor shall read lines from the files to be edited without interpreting any of those lines as any form of editor command. she's just reading, not scheming. 📖

💖 ENVIRONMENT VARIABLES 💖

The following environment variables shall affect the execution of ex:

COLUMNS — Override the system-selected horizontal screen size. See the Base Definitions volume of POSIX.1‐2017, Chapter 8, 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. See the EXTENDED DESCRIPTION section for more details of the initialization phase. ✨
HOME — Determine a pathname of a directory that shall be searched for an editor start-up file named .exrc; see the EXTENDED DESCRIPTION section.
LANG — Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
LC_ALL — If set to a non-empty string value, override the values of all the other internationalization variables. she's the main character, she overrides everyone. 👑
LC_COLLATE — Determine the locale for the behavior 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-byte as opposed to multi-byte characters in arguments and input files), the behavior of character classes within regular expressions, the classification of characters as uppercase or lowercase 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 Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables for valid values and results when it is unset or null.
NLSPATH — Determine the location of message catalogs for the processing of LC_MESSAGES.
PATH — Determine the search path for the shell command specified in the ex editor commands !, shell, read, and write, and the open and visual mode command !; see the description of command search and execution in Section 2.9.1.1, Command Search and Execution.
SHELL — Determine the preferred command line interpreter for use as the default value of the shell edit option.
TERM — Determine the name of the terminal type. If this variable is unset or null, an unspecified default terminal type shall be used.

okay that's part one bestie, we're literally just getting started, don't go anywhere 💜

✨ ASYNCHRONOUS EVENTS ✨

Okay so bestie, this is where the editor gets ✨dramatic✨. Here's a term that pops up in this and the following sections to describe command and asynchronous event actions:

complete write — a complete write is when you write the entire contents of the edit buffer to a file that's not a terminal device, or when the edit buffer gets saved because the user ran ex preserve. But lowkey important: writing the edit buffer to a temporary file that gets deleted when the editor exits? That does not count as a complete write. No cap.

The following actions shall be taken upon receipt of signals:

SIGINT — if the standard input is not a terminal device, ex shall not write the file or return to command or text input mode, and shall exit with a non-zero exit status.

Otherwise, if executing an open or visual text input mode command, ex in receipt of SIGINT shall behave identically to its receipt of the <ESC> character.

Otherwise:

If executing an ex text input mode command, all input lines that have been completely entered shall be resolved into the edit buffer, and any partially entered line shall be discarded.
If there is a currently executing command, it shall be aborted and a message displayed. Unless otherwise specified by the ex or vi command descriptions, it is unspecified whether any lines modified by the executing command appear modified, or as they were before being modified by the executing command, in the buffer.

If the currently executing command was a motion command, its associated command shall be discarded.

If in open or visual command mode, the terminal shall be alerted.
The editor shall then return to command mode.

SIGCONT — the screen shall be refreshed if in open or visual mode. It's giving "wake up bestie" energy. 👑
SIGHUP — if the edit buffer has been modified since the last complete write, ex shall attempt to save the edit buffer so that it can be recovered later using the -r option or the ex recover command. The editor shall not write the file or return to command or text input mode, and shall terminate with a non-zero exit status.
SIGTERM — refer to SIGHUP. Same vibe, same drama.
The action taken for all other signals is unspecified. So like… nobody knows, and that's on periodt. 💀

📬 STDOUT 📬

The standard output shall be used only for writing prompts to the user, for informational messages, and for writing lines from the file. That's it. That's the whole vibe. 💅

🚨 STDERR 🚨

The standard error shall be used only for diagnostic messages. It's the drama channel. 🚨

📁 OUTPUT FILES 📁

The output from ex shall be text files. Slay. 📁

🌈 EXTENDED DESCRIPTION 🌈

Only the ex mode of the editor is described in this section. See vi for additional editing capabilities available in ex. Bestie, don't come here looking for vi magic—go to vi for that. 🦋

When an error occurs, ex shall write a message. If the terminal supports a standout mode (such as inverse video), the message shall be written in standout mode. If the terminal does not support a standout mode, and the edit option errorbells is set, an alert action shall precede the error message. The bell will let you know. 🔔

By default, ex shall start in command mode, which shall be indicated by a : prompt; see the prompt command. Text input mode can be entered by the append, insert, or change commands; it can be exited (and command mode re-entered) by typing a <period> ('.') alone at the beginning of a line. Iconic.

🧚 Initialization in ex and vi 🧚

The following symbols are used in this and following sections to specify locations in the edit buffer:

🔥 alternate and current pathnames 🔥

Two pathnames, named current and alternate, are maintained by the editor. Any ex commands that take filenames as arguments shall set them as follows:

If a file argument is specified to the ex edit, ex, or recover commands, or if an ex tag command replaces the contents of the edit buffer.

a. If the command replaces the contents of the edit buffer, the current pathname shall be set to the file argument or the file indicated by the tag, and the alternate pathname shall be set to the previous value of the current pathname.

b. Otherwise, the alternate pathname shall be set to the file argument.

If a file argument is specified to the ex next command:

a. If the command replaces the contents of the edit buffer, the current pathname shall be set to the first file argument, and the alternate pathname shall be set to the previous value of the current pathname.

If a file argument is specified to the ex file command, the current pathname shall be set to the file argument, and the alternate pathname shall be set to the previous value of the current pathname.
If a file argument is specified to the ex read and write commands (that is, when reading or writing a file, and not to the program named by the shell edit option), or a file argument is specified to the ex xit command:

a. If the current pathname has no value, the current pathname shall be set to the file argument.

b. Otherwise, the alternate pathname shall be set to the file argument.

If the alternate pathname is set to the previous value of the current pathname when the current pathname had no previous value, then the alternate pathname shall have no value as a result.

🎀 current line 🎀

The line of the edit buffer referenced by the cursor. Each command description specifies the current line after the command has been executed, as the current line value. When the edit buffer contains no lines, the current line shall be zero; see Addressing in ex.

🌈 current column 🌈

The current display line column occupied by the cursor. (The columns shall be numbered beginning at 1.) Each command description specifies the current column after the command has been executed, as the current column value. This column is an ideal column that is remembered over the lifetime of the editor. The actual display line column upon which the cursor rests may be different from the current column; see the cursor positioning discussion in Command Descriptions in vi.

💅 set to non-<blank> 💅

A description for a current column value, meaning that the current column shall be set to the last display line column on which is displayed any part of the first non-<blank> of the line. If the line has no non-<blank> non-<newline> characters, the current column shall be set to the last display line column on which is displayed any part of the last non-<newline> character in the line. If the line is empty, the current column shall be set to column position 1.

The length of lines in the edit buffer may be limited to {LINE_MAX} bytes. In open and visual mode, the length of lines in the edit buffer may be limited to the number of characters that will fit in the display. If either limit is exceeded during editing, an error message shall be written. If either limit is exceeded by a line read in from a file, an error message shall be written and the edit session may be terminated. Yikes.

If the editor stops running due to any reason other than a user command, and the edit buffer has been modified since the last complete write, it shall be equivalent to a SIGHUP asynchronous event. If the system crashes, it shall be equivalent to a SIGHUP asynchronous event.

During initialization (before the first file is copied into the edit buffer or any user commands from the terminal are processed) the following shall occur:

If the environment variable EXINIT is set, the editor shall execute the ex commands contained in that variable.
If the EXINIT variable is not set, and all of the following are true:

a. The HOME environment variable is not null and not empty.

b. The file .exrc in the directory referred to by the HOME environment variable:

i. Exists

ii. Is owned by the same user ID as the real user ID of the process or the process has appropriate privileges

iii. Is not writable by anyone other than the owner

the editor shall execute the ex commands contained in that file.

If and only if all of the following are true:

a. The current directory is not referred to by the HOME environment variable.

b. A command in the EXINIT environment variable or a command in the .exrc file in the directory referred to by the HOME environment variable sets the editor option exrc.

c. The .exrc file in the current directory:

i. Exists

ii. Is owned by the same user ID as the real user ID of the process, or by one of a set of implementation-defined user IDs

iii. Is not writable by anyone other than the owner

the editor shall attempt to execute the ex commands contained in that file.

Lines in any .exrc file that are blank lines shall be ignored. If any .exrc file exists, but is not read for ownership or permission reasons, it shall be an error.

After the EXINIT variable and any .exrc files are processed, the first file specified by the user shall be edited, as follows:

If the user specified the -t option, the effect shall be as if the ex tag command was entered with the specified argument, with the exception that if tag processing does not result in a file to edit, the effect shall be as described in step 3. below.
Otherwise, if the user specified any command line file arguments, the effect shall be as if the ex edit command was entered with the first of those arguments as its file argument.
Otherwise, the effect shall be as if the ex edit command was entered with a nonexistent filename as its file argument. It is unspecified whether this action shall set the current pathname. In an implementation where this action does not set the current pathname, any editor command using the current pathname shall fail until an editor command sets the current pathname.

Okay bestie, so if you passed the -r flag, here's the tea: the first time you edit a file from the initial argument list — or a file you named with -t — and there's recovery info saved for it already, that info gets recovered and the editor acts like the edit buffer has already been modified. If there are multiple instances of the file you could recover, the one saved most recently wins, and you get an informational message telling you there are previous versions that can be recovered. And if there's no recovery info for a file at all? You get an informational message saying exactly that, and the edit just proceeds as usual. 💖

And if you passed -c: the first time a file that already exists — including a file that maybe doesn't exist but has recovery info available, when -r is in play — replaces or initializes the contents of the edit buffer, the current line gets set to the last line of the edit buffer, the current column gets set to non-<blank>, and then the ex commands you specified with -c get executed. In that case, the current line and current column are not set the way they are for the command associated with the replacement/initialization of the edit buffer contents. BUT (plot twist) if the -t option or a tag command is associated with this action, the -c commands run first and then the movement to the tag happens. ✨

The current argument list starts out as the filenames you gave on the command line. No filenames from you? Then the current argument list is empty. If you used -t, it's unspecified whether any filename resulting from tag processing gets prepended to the current argument list. If it does get added as a prefix, the current argument list reference gets set to that filename. If it doesn't, the current argument list reference is logically located before the first of the filenames you gave on the command line (so like, a later ex next command edits the first filename from the command line). And if -t wasn't specified at all, the current argument list reference points to the first of the filenames on the command line. 🫶

🌈 Addressing in `ex` 🌈

Addressing in ex is all about the current line and the current column, okay? The address of a line is its 1-based line number, and the address of a column is its 1-based count from the beginning of the line. Generally, the current line is the last line affected by a command, and the current line number is the address of the current line. Every command description tells you what the command does to the current line number and the current column. 👑

Addresses get constructed like this:

The character . (period) addresses the current line.
The character $ addresses the last line of the edit buffer.
The positive decimal number n addresses the *n*th line of the edit buffer.
The address 'x refers to the line marked with the mark name character 'x', which has to be a lowercase letter from the portable character set, the backquote character, or the single-quote character. It's an error if the line that was marked isn't currently present in the edit buffer, or if the mark hasn't been set. Lines get marked with the ex mark or k commands, or the vi m command.
A regular expression wrapped in <slash> characters (/) addresses the first line found by searching forwards from the line following the current line toward the end of the edit buffer, stopping at the first line for which the line — excluding the terminating <newline> — matches the regular expression. As said in Regular Expressions in ex, an address consisting of a null regular expression delimited by <slash> characters (//) addresses the next line for which the line excluding the terminating <newline> matches the last regular expression encountered. Also, that second <slash> can be omitted at the end of a command line. If the wrapscan edit option is set, the search wraps around to the beginning of the edit buffer and continues up to and including the current line, so the whole edit buffer gets searched. And inside the regular expression, the sequence \/ represents a literal <slash> instead of the RE delimiter. 🌀
A regular expression wrapped in <question-mark> characters (?) addresses the first line found by searching backwards from the line preceding the current line toward the beginning of the edit buffer, stopping at the first line for which the line — excluding the terminating <newline> — matches the regular expression. An address consisting of a null regular expression delimited by <question-mark> characters (??) addresses the previous line for which the line excluding the terminating <newline> matches the last regular expression encountered. Also, that second <question-mark> can be omitted at the end of a command line. If the wrapscan edit option is set, the search wraps around from the beginning of the edit buffer to the end of the edit buffer and continues up to and including the current line, so the whole edit buffer gets searched. And inside the regular expression, the sequence \? represents a literal <question-mark> instead of the RE delimiter. 💅
A <plus-sign> (+) or a <hyphen-minus> (-) followed by a decimal number addresses the current line plus or minus that number. A + or - not followed by a decimal number addresses the current line plus or minus 1.

Addresses can be followed by zero or more address offsets, optionally <blank>-separated. Address offsets get constructed like this:

A + or - immediately followed by a decimal number adds (subtracts) the indicated number of lines to (from) the address. A + or - not followed by a decimal number adds (subtracts) 1 to (from) the address.
A decimal number adds the indicated number of lines to the address.

It is not an error for an intermediate address value to be less than zero or greater than the last line in the edit buffer. But it is an error for the final address value to be less than zero or greater than the last line in the edit buffer. ⚠️

Commands take zero, one, or two addresses — see the descriptions of 1addr and 2addr in Command Descriptions in ex. If you hand a command that needs zero addresses more addresses than it needs, that's an error. Otherwise, if you give a command more addresses than it needs, the addresses specified first get evaluated and then discarded until the maximum number of valid addresses remain. 🗑️

Addresses get separated from each other by a <comma> (,) or a <semicolon> (;). If no address is specified before or after a <comma> or <semicolon> separator, it's as if the address of the current line was specified before or after the separator. In the case of a <semicolon> separator, the current line (.) gets set to the first address, and only then does the next address get calculated. This feature is how you determine the starting line for forwards and backwards searches (see rules 5. and 6. above). 🔥

A <percent-sign> (%) is equivalent to entering the two addresses 1,$.

Any delimiting <blank> characters between addresses, address separators, or address offsets get discarded. Periodt.

🧚 Command Line Parsing in `ex` 🧚

The following symbol is used in this section and the ones after it to describe parsing behavior:

escape — If a character is referred to as <backslash>-escaped or <control>-V-escaped, that means the character acquired or lost a special meaning by virtue of being preceded, respectively, by a <backslash> or <control>-V character. Unless otherwise specified, the escaping character gets discarded right then and shall not be considered further for any purpose.

Command-line parsing happens in the following steps. For each step, characters already evaluated get ignored — like, the phrase "leading character" means the next character that hasn't been evaluated yet. ✨

Leading <colon> characters get skipped.
Leading <blank> characters get skipped.
If the leading character is a double-quote character, the characters up to and including the next non-<backslash>-escaped <newline> get discarded, and any subsequent characters get parsed as a separate command.
Leading characters that can be interpreted as addresses get evaluated — see Addressing in ex.
Leading <blank> characters get skipped.
If the next character is a <vertical-line> character or a <newline>:
- a. If the next character is a <newline>:
 - i. If ex is in open or visual mode, the current line gets set to the last address specified, if any.
 - ii. Otherwise, if the last command was terminated by a <vertical-line> character, no action gets taken — for example, the command ||<newline> executes two implied commands, not three.
 - iii. Otherwise, step 6.b. applies.
- b. Otherwise, the implied command is the print command. The last #, p, and l flags specified to any ex command get remembered and apply to this implied command. Executing the ex number, print, or list command sets the remembered flags to #, nothing, and l, respectively, plus any other flags specified for that execution of the number, print, or list command.

If ex is not currently performing a global or v command, and no address or count is specified, the current line gets incremented by 1 before the command is executed. And if incrementing the current line would result in an address past the last line in the edit buffer, the command fails, and the increment doesn't happen. 💀

c. The <newline> or <vertical-line> character gets discarded and any subsequent characters get parsed as a separate command.

The command name is made up of the next character (if that character isn't alphabetic), or the next character and any subsequent alphabetic characters (if that character is alphabetic), with the following exceptions:

a. Commands made of any prefix of the characters in the command name delete, followed immediately by any of the characters 'l', 'p', '+', '-', or '#' — those get read as a delete command, then a <blank>, then whatever characters weren't part of that prefix of delete. And the maximum number of characters gets matched to the command name delete, bestie — like, "del" is not treated as "de" followed by the flag l. No cap.
b. Commands made of the character 'k', followed by a character that can be used as the name of a mark, are equivalent to the mark command, then a <blank>, then the character that came after the 'k'. Simple as that. ✨
c. Commands made of the character 's', followed by characters that could be read as valid options to the s command, are the equivalent of the s command with no pattern or replacement values, then a <blank>, then the characters after the 's'. 🎀

The command name gets matched against the possible command names, and a command name containing a prefix that matches what the user typed is the command that actually runs. And when the characters the user typed could be ambiguous? Here's the tea on which command actually executes:

a → append
c → change
ch → change
e → edit
m → move
ma → mark
n → next
p → print
pr → print
r → read
re → read
s → s
t → t
u → undo
un → undo
v → v
w → write

Implementation extensions with names that cause similar ambiguities shall not be checked for a match until all possible matches for commands specified by POSIX.1‐2008 have been checked. POSIX first, always. 💅

If the command is a ! command, or if it's a read command followed by zero or more <blank> characters and a !, or if it's a write command followed by one or more <blank> characters and a ! — then the rest of the command shall include all characters up to a non-\-escaped <newline>. That <newline> gets discarded, and any characters after it get parsed as a separate ex command. Slay. 🦋
Otherwise, if the command is an edit, ex, or next command, or a visual command while in open or visual mode, the next part of the command gets parsed like this:
- a. Any '!' character sitting right after the command gets skipped and becomes part of the command.
- b. Any leading <blank> characters get skipped and become part of the command.
- c. If the next character is a '+', characters up to the first non-\-escaped <newline> or non-\-escaped <blank> get skipped and become part of the command.
- d. The rest of the command is determined by the steps in paragraph 12. (iykyk, we're getting there 💖)
Otherwise, if the command is a global, open, s, or v command, the next part of the command gets parsed like this:
- a. Any leading <blank> characters get skipped and become part of the command.
- b. If the next character is not an alphanumeric, double-quote, <newline>, \, or <vertical-line> character:
 - i. That next character gets used as a command delimiter.
 - ii. If the command is a global, open, or v command, characters up to the first non-\-escaped <newline>, or the first non-\-escaped delimiter character, get skipped and become part of the command.
 - iii. If the command is an s command, characters up to the first non-\-escaped <newline>, or the second non-\-escaped delimiter character, get skipped and become part of the command.
- c. If the command is a global or v command, characters up to the first non-\-escaped <newline> get skipped and become part of the command.
- d. Otherwise, the rest of the command is determined by the steps in paragraph 12.
Otherwise:
- a. If the command was a map, unmap, abbreviate, or unabbreviate command, characters up to the first non-<control>-V-escaped <newline>, <vertical-line>, or double-quote character get skipped and become part of the command.
- b. Otherwise, characters up to the first non-\-escaped <newline>, <vertical-line>, or double-quote character get skipped and become part of the command.
- c. If the command was an append, change, or insert command, and step 12.b. ended at a <vertical-line> character, then any characters after that, up to the next non-\-escaped <newline>, get used as input text to the command. 💅
- d. If the command was ended by a double-quote character, all subsequent characters, up to the next non-\-escaped <newline>, get discarded.
- e. The terminating <newline> or <vertical-line> character gets discarded, and any characters after it get parsed as a separate ex command.

Command arguments get parsed as described by the Synopsis and Description of each individual ex command. This parsing is not <blank>-sensitive — except for the ! argument, which has to follow the command name with no <blank> characters in between, and except where it would otherwise be ambiguous. For example, count and flag arguments don't need to be <blank>-separated, because "d22p" isn't ambiguous — but file arguments to the ex next command must be separated by one or more <blank> characters. 🌸

Any <blank> in command arguments for the abbreviate, unabbreviate, map, and unmap commands can be <control>-V-escaped, and if it is, that <blank> shall not be used as an argument delimiter. Any <blank> in the command argument for any other command can be \-escaped, and if it is, that <blank> shall not be used as an argument delimiter either. Bestie, escaping is your friend. 🫶

Within command arguments for the abbreviate, unabbreviate, map, and unmap commands, any character can be <control>-V-escaped. All those escaped characters get treated literally and have no special meaning whatsoever. Within command arguments for all other ex commands that aren't regular expressions or replacement strings, any character that would otherwise have a special meaning can be \-escaped. Escaped characters get treated literally, with no special meaning as shell expansion characters or as '!', '%', and '#' expansion characters. For descriptions of command arguments that are regular expressions or replacement strings, go check out Regular Expressions in ex and Replacement Strings in ex. 📖

Non-\-escaped '%' characters appearing in file arguments to any ex command get replaced by the current pathname; unescaped '#' characters get replaced by the alternate pathname. And it is an error if '%' or '#' characters appear unescaped in an argument and their corresponding values aren't set. 😭

Non-\-escaped '!' characters in the arguments to either the ex ! command or the open and visual mode ! command, or in the arguments to the ex read command where the first non-<blank> after the command name is a '!' character, or in the arguments to the ex write command where the command name is followed by one or more <blank> characters and the first non-<blank> after the command name is a '!' character — those get replaced with the arguments to the last of those three commands, exactly as they appeared after all unescaped '%', '#', and '!' characters were replaced. And it is an error if '!' characters appear unescaped in one of these commands and there's been no previous execution of one of these commands. No vibes, just facts. 💀

If an error occurs during the parsing or execution of an ex command:

An informational message to this effect gets written. Execution of the ex command stops, and the cursor (for example, the current line and column) is not further modified.
If the ex command came from a map expansion, all characters from that map expansion get discarded — except as otherwise specified by the map command.
Otherwise, if the ex command came from the processing of an EXINIT environment variable, a .exrc file, a :source command, a -c option, or a +command specified to an ex edit, ex, next, or visual command, then no further commands from that source of commands get executed.
Otherwise, if the ex command came from the execution of a buffer or a global or v command, no further commands caused by the execution of that buffer or that global or v command get executed.
Otherwise, if the ex command wasn't terminated by a <newline>, all characters up to and including the next non-\-escaped <newline> get discarded. 🗑️

🌈 Input Editing in ex 🌈

The following symbol gets used in this section and the ones after it to specify command actions:

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 edit buffer. Periodt. ⭐

When accepting input characters from the user, whether in ex command mode or ex text input mode, ex shall enable canonical mode input processing, as defined in the System Interfaces volume of POSIX.1‐2017.

If in ex text input mode:

If the number edit option is set, ex shall prompt for input using the line number that would be assigned to the line if it's entered, in the format specified for the ex number command. 🔢
If the autoindent edit option is set, ex shall prompt for input using autoindent characters, as described by the autoindent edit option. Those autoindent characters follow the line number, if there is one. ✨

If in ex command mode:

If the prompt edit option is set, input gets prompted for using a single ':' character; otherwise, there's no prompt at all.

okay bestie, the input characters in the next few sections? they all have these exact effects on the input line. no cap. 💖

🌸 Scroll 🌸

Synopsis:

eof

go peek at the description of the stty eof character in stty, k? 🫶

If you're in ex command mode:

If the eof character is the first character entered on the line, the line shall be evaluated as if it contained two characters: a <control>‐D and a <newline>. 💅
Otherwise, the eof character shall have no special meaning. 🙈

If you're in ex text input mode:

If the cursor follows an autoindent character, the autoindent characters in the line shall be modified so that a part of the next text input character will be displayed on the first column in the line after the previous shiftwidth edit option column boundary, and the user shall be prompted again for input for the same line. ✨
Otherwise, if the cursor follows a '0', which follows an autoindent character, and the '0' was the previous text input character, the '0' and all autoindent characters in the line shall be discarded, and the user shall be prompted again for input for the same line. 🎀
Otherwise, if the cursor follows a '^', which follows an autoindent character, and the '^' was the previous text input character, the '^' and all autoindent characters in the line shall be discarded, and the user shall be prompted again for input for the same line. In addition, the autoindent level for the next input line shall be derived from the same line from which the autoindent level for the current input line was derived. 🦋
Otherwise, if there are no autoindent or text input characters in the line, the eof character shall be discarded. 💀
Otherwise, the eof character shall have no special meaning. 🙈

🌈 `<newline>` 🌈

Synopsis:

<newline>
<control>-J

If you're in ex command mode:

Cause the command line to be parsed; <control>‐J shall be mapped to the <newline> for this purpose. 👑

If you're in ex text input mode:

Terminate the current line. If there are no characters other than autoindent characters on the line, all characters on the line shall be discarded. 🫶

Prompt for text input on a new line after the current line. If the autoindent edit option is set, an appropriate number of autoindent characters shall be added as a prefix to the line as described by the ex autoindent edit option. 🌸

💅 `<backslash>` 💅

Synopsis:

<backslash>

Allow the entry of a subsequent <newline> or <control>‐J as a literal character, removing any special meaning that it may have to the editor during text input mode. The <backslash> character shall be retained and evaluated when the command line is parsed, or retained and included when the input text becomes part of the edit buffer. ✨

✨ `<control>‐V` ✨

Synopsis:

<control>-V

Allow the entry of any subsequent character as a literal character, removing any special meaning that it may have to the editor during text input mode. The <control>‐V character shall be discarded before the command line is parsed or the input text becomes part of the edit buffer. 💖

If the "literal next" functionality is performed by the underlying system, it is implementation-defined whether a character other than <control>‐V performs this function. 🧚

🎀 `<control>‐W` 🎀

Synopsis:

<control>-W

Discard the <control>‐W, and the word previous to it in the input line, including any <blank> characters following the word and preceding the <control>‐W. If the "word erase" functionality is performed by the underlying system, it is implementation-defined whether a character other than <control>‐W performs this function. 💅

👑 Command Descriptions in `ex` 👑

okay so these symbols? they're the command modifiers for ex, bestie. some can be omitted, and then the specified defaults kick in. periodt. 👑

1addr — A single line address, given in any of the forms described in Addressing in ex; the default shall be the current line ('.'), unless otherwise specified.

If the line address is zero, it shall be an error, unless otherwise specified in the following command descriptions.

If the edit buffer is empty, and the address is specified with a command other than =, append, insert, open, put, read, or visual, or the address is not zero, it shall be an error.

2addr — Two addresses specifying an inclusive range of lines. If no addresses are specified, the default for 2addr shall be the current line only (".,."), unless otherwise specified in the following command descriptions. If one address is specified, 2addr shall specify that line only, unless otherwise specified in the following command descriptions.

It shall be an error if the first address is greater than the second address.

If the edit buffer is empty, and the two addresses are specified with a command other than the !, write, wq, or xit commands, or either address is not zero, it shall be an error.

count — A positive decimal number. If count is specified, it shall be equivalent to specifying an additional address to the command, unless otherwise specified by the following command descriptions. The additional address shall be equal to the last address specified to the command (either explicitly or by default) plus count-1.

If this would result in an address greater than the last line of the edit buffer, it shall be corrected to equal the last line of the edit buffer.

flags — One or more of the characters '+', '-', '#', 'p', or 'l' (ell). The flag characters can be <blank>-separated, and in any order or combination. The characters '#', 'p', and 'l' shall cause lines to be written in the format specified by the print command with the specified flags.

The lines to be written are as follows:

All edit buffer lines written during the execution of the ex &, ~, list, number, open, print, s, visual, and z commands shall be written as specified by flags.
After the completion of an ex command with a flag as an argument, the current line shall be written as specified by flags, unless the current line was the last line written by the command.

The characters '+' and '-' cause the value of the current line after the execution of the ex command to be adjusted by the offset address as described in Addressing in ex. This adjustment shall occur before the current line is written as described in 2. above.

The default for flags shall be none.

buffer — One of a number of named areas for holding text. The named buffers are specified by the alphanumeric characters of the POSIX locale. There shall also be one "unnamed" buffer. When no buffer is specified for editor commands that use a buffer, the unnamed buffer shall be used. Commands that store text into buffers shall store the text as it was before the command took effect, and shall store text occurring earlier in the file before text occurring later in the file, regardless of how the text region was specified. Commands that store text into buffers shall store the text into the unnamed buffer as well as any specified buffer.

In ex commands, buffer names are specified as the name by itself. In open or visual mode commands the name is preceded by a double-quote ('"') character.

If the specified buffer name is an uppercase character, and the buffer contents are to be modified, the buffer shall be appended to rather than being overwritten. If the buffer is not being modified, specifying the buffer name in lowercase and uppercase shall have identical results.

There shall also be buffers named by the numbers 1 through 9. In open and visual mode, if a region of text including characters from more than a single line is being modified by the vi c or d commands, the motion character associated with the c or d commands specifies that the buffer text shall be in line mode, or the commands %, `, /, ?, (, ), N, n, {, or } are used to define a region of text for the c or d commands, the contents of buffers 1 through 8 shall be moved into the buffer named by the next numerically greater value, the contents of buffer 9 shall be discarded, and the region of text shall be copied into buffer 1. This shall be in addition to copying the text into a user-specified buffer or unnamed buffer, or both. Numeric buffers can be specified as a source buffer for open and visual mode commands; however, specifying a numeric buffer as the write target of an open or visual mode command shall have unspecified results.

bestie, unspecified results? that's giving chaos. proceed with caution. 💀

The text of each buffer shall have the characteristic of being in either line or character mode. Appending text to a non-empty buffer shall set the mode to match the characteristic of the text being appended. Appending text to a buffer shall cause the creation of at least one additional line in the buffer. All text stored into buffers by ex commands shall be in line mode. The ex commands that use buffers as the source of text specify individually how buffers of different modes are handled. Each open or visual mode command that uses buffers for any purpose specifies individually the mode of the text stored into the buffer and how buffers of different modes are handled.

file — the command text you use to derive a pathname. By default it's the current pathname (as defined earlier), and if you haven't established a current pathname yet, that's an error — except where the individual command descriptions further down specifically say otherwise. If your command text contains any of these characters: ~, {, [, *, ?, $, ", backquote, single-quote, or <backslash>, then it gets put through the whole "shell expansions" treatment described below. And if more than one pathname falls out of that while the command only wants one? Error. No cap.

Here's the shell-expansion ritual 💫: the ex utility passes two arguments to the program named by the shell edit option. The first is -c, and the second is the string echo plus the command text, all as a single argument. Whatever that command spews onto standard output and standard error replaces the command text. That's it, that's the whole vibe.

! — a character you can tack onto the end of a command name to tweak how it behaves, as spelled out in each command's own description. Except for the ex read, write, and ! commands, the ! character only works as a modifier when there are no <blank> characters sitting between it and the command name. So w! slays, w ! does not. 💅
remembered search direction — the vi commands N and n start searching forwards or backwards through the edit buffer based on a remembered search direction. It starts out unset 🫥, and it gets set by the ex global, v, s, and tag commands, plus the vi / and ? commands.

🌸 Abbreviate 🌸

Synopsis, bestie:

ab[breviate][lhs rhs]

If lhs and rhs aren't given, just write out the current list of abbreviations and call it a day.

Implementations are allowed to restrict which characters they accept in lhs or rhs — except that printable characters and <blank> characters shall not be restricted. Any extra restrictions are implementation-defined.

In both lhs and rhs, any character can be escaped with a <control>-V. When that happens, the character doesn't get used to separate lhs from rhs, and the escaping <control>-V gets discarded.

In open and visual text input mode: if a non-word character or an <ESC> character that isn't escaped by a <control>-V gets entered right after a word character, a check is made for a set of characters matching lhs, in the text input entered during this command. If a match turns up, it's as if rhs had been entered instead of lhs. Iconic behaviour honestly.

The set of characters that gets checked is defined like this:

If there are no characters inserted before the word and non-word or <ESC> characters that triggered the check, the set consists of the word character.
If the character inserted before the word and non-word or <ESC> characters that triggered the check is a word character, the set consists of the characters inserted immediately before the triggering characters that are word characters, plus the triggering word character.
If the character inserted before the word and non-word or <ESC> characters that triggered the check is not a word character, the set consists of the characters inserted before the triggering characters that are neither <blank> characters nor word characters, plus the triggering word character.

It is unspecified whether the lhs argument you typed for the ex abbreviate and unabbreviate commands gets replaced in this fashion. Either way, the effect of the command shall be as if the replacement had not occurred.

Current line: unchanged.

Current column: unchanged.

✨ Append ✨

Synopsis:

[1addr] a[ppend][!]

Enters ex text input mode; the input text lands after the specified line. If you specify line zero, the text goes at the very beginning of the edit buffer. 🎀

This command is affected by the number and autoindent edit options; sticking a ! after the command name toggles the autoindent edit option setting for the duration of this command only.

Current line: set to the last input line. If no lines were input, set to the specified line — or to the first line of the edit buffer if line zero was specified, or to zero if the edit buffer is empty.

Current column: set to non-<blank>.

🦋 Arguments 🦋

Synopsis:

ar[gs]

Writes out the current argument list, with the current argument-list entry (if there is one) nestled between [ and ] characters.

Current line: unchanged.

Current column: unchanged.

💜 Change 💜

Synopsis:

[2addr] c[hange][!][count]

Enters ex text input mode; the input text replaces the specified lines. Those specified lines get copied into the unnamed buffer, which becomes a line mode buffer.

This command is affected by the number and autoindent edit options; sticking a ! after the command name toggles the autoindent edit option setting for the duration of this command only.

Current line: set to the last input line. If no lines were input, set to the line before the first address — or to the first line of the edit buffer if there are no lines preceding the first address, or to zero if the edit buffer is empty.

Current column: set to non-<blank>.

🌈 Change Directory 🌈

Synopsis:

chd[ir][!][directory]
cd[!][directory]

Changes the current working directory to directory. Simple as that, bestie.

If no directory argument is given, and the HOME environment variable is set to a non-null and non-empty value, directory defaults to whatever HOME names. If HOME is empty or undefined, the default value of directory is implementation-defined.

If there's no ! appended to the command name, and the edit buffer has been modified since the last complete write, and the current pathname does not begin with a / — that's an error. Triple-threat condition, watch out. 😭

Current line: unchanged.

Current column: unchanged.

🍓 Copy 🍓

Synopsis:

[2addr] co[py] 1addr [flags]
[2addr] t 1addr [flags]

Copies the specified lines to after the specified destination line; line zero means the lines get placed at the very start of the edit buffer. ✨

Current line: set to the last line copied.

Current column: set to non-<blank>.

💀 Delete 💀

Synopsis:

[2addr] d[elete][buffer][count][flags]

Deletes the specified lines into a buffer (defaulting to the unnamed buffer), which becomes a line-mode buffer.

Flags can come immediately after the command name; peep Command Line Parsing in ex for the deets.

Current line: set to the line following the deleted lines — or to the last line in the edit buffer if that line is past the end of the edit buffer, or to zero if the edit buffer is empty.

Current column: set to non-<blank>.

🧚 Edit 🧚

Synopsis:

e[dit][!][+command][file]
ex[!][+command][file]

If there's no ! appended to the command name, and the edit buffer has been modified since the last complete write, it's an error.

If file is specified, replace the current contents of the edit buffer with the current contents of file, and set the current pathname to file. If file isn't specified, replace the current contents of the edit buffer with the current contents of the file named by the current pathname. If for any reason the current contents of the file can't be accessed, the edit buffer shall be empty. 💀

The +command option is <blank>-delimited; <blank> characters inside the +command can be escaped by putting a <backslash> in front of them. The +command is interpreted as an ex command immediately after the contents of the edit buffer have been replaced and the current line and column have been set.

If the edit buffer is empty:

Current line: set to 0.

Current column: set to 1.

Otherwise, if executed while in ex command mode, or if the +command argument is specified:

Current line: set to the last line of the edit buffer.

Current column: set to non-<blank>.

Otherwise, if file is omitted or results in the current pathname:

Current line: set to the first line of the edit buffer.

Current column: set to non-<blank>.

Otherwise, if file is the same as the last file edited, the line and column are set as follows; if the file was previously edited, the line and column may be set as follows:

Current line: set to the last value held when that file was last edited. If that value isn't a valid line in the new edit buffer, set to the first line of the edit buffer.

Current column: if the current line was set to the last value held when the file was last edited, set to the last value held when the file was last edited. Otherwise — or if the last value isn't a valid column in the new edit buffer — set to non-<blank>.

Otherwise:

Current line: set to the first line of the edit buffer.

Current column: set to non-<blank>.

👑 File 👑

Synopsis:

f[ile][file]

If a file argument is specified, the alternate pathname gets set to the current pathname, and the current pathname gets set to file.

Then it writes an informational message. If the file has a current pathname, that gets included in the message; otherwise the message says there's no current pathname. If the edit buffer contains lines, the current line number and the number of lines in the edit buffer get included in the message; otherwise the message says the edit buffer is empty. If the edit buffer has been modified since the last complete write, that fact gets included in the message. If the readonly edit option is set, that fact gets included in the message too. The message may contain other unspecified information. 🫶

Current line: unchanged.

Current column: unchanged.

🔥 Global 🔥

Synopsis:

[2addr] g[lobal] /pattern/ [commands]
[2addr] v /pattern/ [commands]

The optional ! character after the global command is the same as running the v command. Same energy, different name.

If pattern is empty (like //) or not specified at all, the last regular expression used in the editor command is used as the pattern. The pattern can be delimited by <slash> characters (as shown in the Synopsis), or by any non-alphanumeric or non-<blank> character other than <backslash>, <vertical-line>, <newline>, or double-quote. Versatile. 💅

If no lines are specified, the lines default to the entire file. Yeah. All of it. 😭

The global and v commands are logically two-pass operations, bestie, like a two-step dance 💃. First, mark the lines within the specified lines for which the line excluding the terminating <newline> matches (global) or does not match (v or global!) the specified pattern. Second, execute the ex commands given by commands, with the current line ('.') set to each marked line. If an error occurs during this process, or the contents of the edit buffer are replaced (for example, by the ex :edit command) an error message shall be written and no more commands resulting from the execution of this command shall be processed. 😭

Multiple ex commands can be specified by entering multiple commands on a single line using a <vertical-line> to delimit them, or one per line, by escaping each <newline> with a <backslash>. ✨

If no commands are specified:

If in ex command mode, it shall be as if the print command were specified.
Otherwise, no command shall be executed.

For the append, change, and insert commands, the input text shall be included as part of the command, and the terminating <period> can be omitted if the command ends the list of commands. The open and visual commands can be specified as one of the commands, in which case each marked line shall cause the editor to enter open or visual mode. If open or visual mode is exited using the vi Q command, the current line shall be set to the next marked line, and open or visual mode reentered, until the list of marked lines is exhausted. 🦋

The global, v, and undo commands cannot be used in commands. Marked lines may be deleted by commands executed for lines occurring earlier in the file than the marked lines. In this case, no commands shall be executed for the deleted lines. 💀

If the remembered search direction is not set, the global and v commands shall set it to forward. ➡️

The autoprint and autoindent edit options shall be inhibited for the duration of the g or v command. 🙈

Current line: If no commands executed, set to the last marked line. Otherwise, as specified for the executed ex commands.

Current column: If no commands are executed, set to non-<blank>; otherwise, as specified for the individual ex commands.

🌸 Insert 🌸

Synopsis:

[1addr] i[nsert][!]

Enter ex text input mode; the input text shall be placed before the specified line. If the line is zero or 1, the text shall be placed at the beginning of the edit buffer. 🎀

This command shall be affected by the number and autoindent edit options; following the command name with '!' shall cause the autoindent edit option setting to be toggled for the duration of this command only. 💅

Current line: Set to the last input line; if no lines were input, set to the line before the specified line, or to the first line of the edit buffer if there are no lines preceding the specified line, or zero if the edit buffer is empty.

Current column: Set to non-<blank>.

🌈 Join 🌈

Synopsis:

[2addr] j[oin][!][count][flags]

If count is specified:

If no address was specified, the join command shall behave as if 2addr were the current line and the current line plus count (.,. + count).
If one address was specified, the join command shall behave as if 2addr were the specified address and the specified address plus count (addr,addr + count).
If two addresses were specified, the join command shall behave as if an additional address, equal to the last address plus count -1 (addr1,addr2,addr2 + count -1), was specified.
If this would result in a second address greater than the last line of the edit buffer, it shall be corrected to be equal to the last line of the edit buffer. 🛠️

If no count is specified:

If no address was specified, the join command shall behave as if 2addr were the current line and the next line (.,. +1).
If one address was specified, the join command shall behave as if 2addr were the specified address and the next line (addr,addr +1).

Join the text from the specified lines together into a single line, which shall replace the specified lines. 🫶

If a '!' character is appended to the command name, the join shall be without modification of any line, independent of the current locale. No cap.

Otherwise, in the POSIX locale, set the current line to the first of the specified lines, and then, for each subsequent line, proceed as follows:

Discard leading <space> characters from the line to be joined.
If the line to be joined is now empty, delete it, and skip steps 3 through 5.
If the current line ends in a <blank>, or the first character of the line to be joined is a ')' character, join the lines without further modification.
If the last character of the current line is a '.', join the lines with two <space> characters between them.
Otherwise, join the lines with a single <space> between them.

Current line: Set to the first line specified.

Current column: Set to non-<blank>.

✨ List ✨

Synopsis:

[2addr] l[ist][count][flags]

This command shall be equivalent to the ex command:

[2addr] p[rint][count] l[flags]

See Print. 👑

💖 Map 💖

Synopsis:

map[!][lhs rhs]

If lhs and rhs are not specified:

If '!' is specified, write the current list of text input mode maps.
Otherwise, write the current list of command mode maps.
Do nothing more.

Implementations may restrict the set of characters accepted in lhs or rhs, except that printable characters and <blank> characters shall not be restricted. Additional restrictions shall be implementation-defined. In both lhs and rhs, any character can be escaped with a <control>‐V, in which case the character shall not be used to delimit lhs from rhs, and the escaping <control>‐V shall be discarded. 🎀

If the character '!' is appended to the map command name, the mapping shall be effective during open or visual text input mode rather than open or visual command mode. This allows lhs to have two different map definitions at the same time: one for command mode and one for text input mode. 🤯

For command mode mappings:

When the lhs is entered as any part of a vi command in open or visual mode (but not as part of the arguments to the command), the action shall be as if the corresponding rhs had been entered.
If any character in the command, other than the first, is escaped using a <control>‐V character, that character shall not be part of a match to an lhs.
It is unspecified whether implementations shall support map commands where the lhs is more than a single character in length, where the first character of the lhs is printable.
If lhs contains more than one character and the first character is '#', followed by a sequence of digits corresponding to a numbered function key, then when this function key is typed it shall be mapped to rhs. Characters other than digits following a '#' character also represent the function key named by the characters in the lhs following the '#' and may be mapped to rhs. It is unspecified how function keys are named or what function keys are supported.

For text input mode mappings:

When the lhs is entered as any part of text entered in open or visual text input modes, the action shall be as if the corresponding rhs had been entered.
If any character in the input text is escaped using a <control>‐V character, that character shall not be part of a match to an lhs.
It is unspecified whether the lhs text entered for subsequent map or unmap commands is replaced with the rhs text for the purposes of the screen display; regardless of whether or not the display appears as if the corresponding rhs text was entered, the effect of the command shall be as if the lhs text was entered.

If only part of the lhs is entered, it is unspecified how long the editor will wait for additional, possibly matching characters before treating the already entered characters as not matching the lhs. ⏳

The rhs characters shall themselves be subject to remapping, unless otherwise specified by the remap edit option, except that if the characters in lhs occur as prefix characters in rhs, those characters shall not be remapped. 🔁

On 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 shall achieve the same results as if it occurred immediately. 🖥️

Current line: Unchanged.

Current column: Unchanged.

🦋 Mark 🦋

Synopsis:

[1addr] ma[rk] character
[1addr] k character

Implementations shall support character values of a single lowercase letter of the POSIX locale and the backquote and single-quote characters; support of other characters is implementation-defined. 🔤

If executing the vi m command, set the specified mark to the current line and 1-based numbered character referenced by the current column, if any; otherwise, column position 1.

Otherwise, set the specified mark to the specified line and 1-based numbered first non-<blank> non-<newline> in the line, if any; otherwise, the last non-<newline> in the line, if any; otherwise, column position 1.

The mark shall remain associated with the line until the mark is reset or the line is deleted. If a deleted line is restored by a subsequent undo command, any marks previously associated with the line, which have not been reset, shall be restored as well. Any use of a mark not associated with a current line in the edit buffer shall be an error. 💀

The marks ` and ' shall be set as described previously, immediately before the following events occur in the editor:

The use of '$' as an ex address
The use of a positive decimal number as an ex address
The use of a search command as an ex address
The use of a mark reference as an ex address
The use of the following open and visual mode commands: <control>‐], %, (, ), [, ], {, }
The use of the following open and visual mode commands: ', G, H, L, M, z if the current line will change as a result of the command
The use of the open and visual mode commands: /, ?, N, `, n if the current line or column will change as a result of the command
The use of the ex mode commands: z, undo, global, v

For rules 1., 2., 3., and 4., the ` and ' marks shall not be set if the ex command is parsed as specified by rule 6.a. in Command Line Parsing in ex. ⭐

For rules 5., 6., and 7., the ` and ' marks shall not be set if the commands are used as motion commands in open and visual mode.

For rules 1., 2., 3., 4., 5., 6., 7., and 8., the ` and ' marks shall not be set if the command fails. 💀

So like, the ` and ' marks get set exactly the way we said above, every single time the contents of the edit buffer get replaced (yes, including when the initial buffer gets edited, bestie), if you're in open or visual mode — or if you're in ex mode and the edit buffer is not empty — and this happens before any commands or movements get executed on the edit buffer, and that includes commands or movements you specified with the -c or -t options or the +command argument. If you're in open or visual mode, the marks get set as if you were executing the vi m command; otherwise, it's as if you ran the ex mark command. 🌸

When you change from ex mode to open or visual mode, if the ` and ' marks aren't already set, they shall be set as described above. Slay.

Current line: Unchanged.

Current column: Unchanged.

✨ Move ✨

Synopsis:

[2addr] m[ove] 1addr [flags]

Move the specified lines so they land after the specified destination line. A destination of line zero means the lines go at the very beginning of the edit buffer, like, top of the class. It shall be an error if the destination line is inside the range of lines you're moving. No cap. 🙈

Current line: Set to the last of the moved lines.

Current column: Set to non-<blank>.

🦋 Next 🦋

Synopsis:

n[ext][!][+command][file ...]

If there's no ! tacked onto the end of the command name, and the edit buffer has been modified since the last complete write, it shall be an error — unless the file gets successfully written as specified by the autowrite option.

If one or more *file*s are specified:

Set the argument list to the specified filenames.
Set the current argument list reference to be the first entry in the argument list.
Set the current pathname to the first filename specified.

Otherwise:

It shall be an error if there are no more filenames in the argument list after the filename currently referenced.
Set the current pathname and the current argument list reference to the filename after the filename currently referenced in the argument list.

Replace the contents of the edit buffer with the contents of the file named by the current pathname. If for any reason the contents of the file cannot be accessed, the edit buffer shall be empty. (Yeah. Empty. Gutted. 😭)

This command shall be affected by the autowrite and writeany edit options.

The +command option shall be <blank>-delimited; <blank> characters can be escaped by preceding them with a <backslash> character. The +command shall be interpreted as an ex command immediately after the contents of the edit buffer have been replaced and the current line and column have been set. Periodt.

Current line: Set as described for the edit command.

Current column: Set as described for the edit command.

💅 Number 💅

Synopsis:

[2addr] nu[mber][count][flags]
[2addr] #[count][flags]

These commands shall be equivalent to the ex command:

[2addr] p[rint][count] #[flags]

See Print. iykyk 💖

🌈 Open 🌈

Synopsis:

[1addr] o[pen] /pattern/ [flags]

This command need not be supported on block-mode terminals or terminals with insufficient capabilities. And if standard input, standard output, or standard error are not terminal devices, the results are unspecified. So like, don't @ me.

Enter open mode.

The trailing delimiter can be omitted from pattern at the end of the command line. If pattern is empty (for example, //) or not specified, the last regular expression used in the editor shall be used as the pattern. The pattern can be delimited by <slash> characters (shown in the Synopsis), as well as any alphanumeric, or non-<blank> other than <backslash>, <vertical-line>, <newline>, or double-quote.

Current line: Set to the specified line.

Current column: Set to non-<blank>.

🎀 Preserve 🎀

Synopsis:

pre[serve]

Save the edit buffer in a form that can later be recovered by using the -r option or by using the ex recover command. After the file has been preserved, a mail message shall be sent to the user. This message shall be readable by invoking the mailx utility. 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. Obsessed with a utility that emails you when you're in crisis, honestly. 📧

Current line: Unchanged.

Current column: Unchanged.

💜 Print 💜

Synopsis:

[2addr] p[rint][count][flags]

Write the addressed lines. The behavior is unspecified if the number of columns on the display is less than the number of columns required to write any single character in the lines being written.

Non-printable characters, except for the <tab>, shall be written as implementation-defined multi-character sequences.

If the # flag is specified or the number edit option is set, each line shall be preceded by its line number in the following format:

"%6d  ", <line number>

If the l flag is specified or the list edit option is set:

The characters listed in the Base Definitions volume of POSIX.1‐2017, Table 5-1, Escape Sequences and Associated Actions shall be written as the corresponding escape sequence.
Non-printable characters not in the Base Definitions volume of POSIX.1‐2017, Table 5-1, Escape Sequences and Associated Actions shall be written as one three-digit octal number (with a preceding <backslash>) for each byte in the character (most significant byte first).
The end of each line shall be marked with a '$', and literal '$' characters within the line shall be written with a preceding <backslash>.

Long lines shall be folded; the length at which folding occurs is unspecified, but should be appropriate for the output terminal, considering the number of columns of the terminal. Like, it'll wrap where it wants. ✨

If a line is folded, and the l flag is not specified and the list edit option is not set, it is unspecified whether a multi-column character at the folding position is separated; it shall not be discarded. Not me worrying about that character's whole journey. 😭

Current line: Set to the last written line.

Current column: Unchanged if the current line is unchanged; otherwise, set to non-<blank>.

🍓 Put 🍓

Synopsis:

[1addr] pu[t][buffer]

Append text from the specified buffer (by default, the unnamed buffer) to the specified line; line zero specifies that the text shall be placed at the beginning of the edit buffer. Each portion of a line in the buffer shall become a new line in the edit buffer, regardless of the mode of the buffer. Fr fr.

Current line: Set to the last line entered into the edit buffer.

Current column: Set to non-<blank>.

👑 Quit 👑

Synopsis:

q[uit][!]

If no ! is appended to the command name:

If the edit buffer has been modified since the last complete write, it shall be an error.
If there are filenames in the argument list after the filename currently referenced, and the last command was not a quit, wq, xit, or ZZ (see Exit) command, it shall be an error.

Otherwise, terminate the editing session.

Bestie. If you don't add that !, this thing will fight you about unsaved work, and it is correct to do so. Add the ! only when you genuinely mean it. 💀

🌸 Read 🌸

Synopsis:

[1addr] r[ead][!][file]

If ! is not the first non-<blank> to follow the command name, a copy of the specified file shall be appended into the edit buffer after the specified line; line zero specifies that the copy shall be placed at the beginning of the edit buffer. The number of lines and bytes read shall be written. If no file is named, the current pathname shall be the default. If there is no current pathname, then file shall become the current pathname. If there is no current pathname or file operand, it shall be an error. Specifying a file that is not of type regular shall have unspecified results. 🙈

Otherwise, if file is preceded by !, the rest of the line after the ! shall have '%', '#', and '!' characters expanded as described in Command Line Parsing in ex.

The ex utility shall then pass two arguments to the program named by the shell edit option; the first shall be -c and the second shall be the expanded arguments to the read command as a single argument. The standard input of the program shall be set to the standard input of the ex program when it was invoked. The standard error and standard output of the program shall be appended into the edit buffer after the specified line. She's piping, she's appending, she's doing the most. 💅

Each line in the copied file or program output (as delimited by <newline> characters or the end of the file or output if it is not immediately preceded by a <newline>), shall be a separate line in the edit buffer. Any occurrences of <carriage-return> and <newline> pairs in the output shall be treated as single <newline> characters.

The special meaning of the ! following the read command can be overridden by escaping it with a <backslash> character.

Current line: If no lines are added to the edit buffer, unchanged. Otherwise, if in open or visual mode, set to the first line entered into the edit buffer. Otherwise, set to the last line entered into the edit buffer.

Current column: Set to non-<blank>.

🧚 Recover 🧚

Synopsis:

rec[over][!] file

If no ! is appended to the command name, and the edit buffer has been modified since the last complete write, it shall be an error.

If no file operand is specified, then the current pathname shall be used. If there is no current pathname or file operand, it shall be an error.

If no recovery information has previously been saved about file, the recover command shall behave identically to the edit command, and an informational message to this effect shall be written.

Otherwise, set the current pathname to file, and replace the current contents of the edit buffer with the recovered contents of file. If there are multiple instances of the file to be recovered, the one most recently saved shall be recovered, and an informational message that there are previous versions of the file that can be recovered shall be written. The editor shall behave as if the contents of the edit buffer have already been modified.

Current file: Set as described for the edit command.

Current column: Set as described for the edit command.

She resurrects your crashed session and then tells you there are older versions too. Main character energy, honestly. 🫶

⭐ Rewind ⭐

Synopsis:

rew[ind][!]

If no ! is appended to the command name, and the edit buffer has been modified since the last complete write, it shall be an error, unless the file is successfully written as specified by the autowrite option.

If the argument list is empty, it shall be an error.

The current argument list reference and the current pathname shall be set to the first filename in the argument list. Back to the beginning, babes. 🌈

okay so swapping out everything in your edit buffer for whatever's in the file that the current pathname points at. 💖 And bestie, if for any reason that file's contents can't be accessed? The edit buffer is just empty. Gone. Nothing. 💀

This one gets shaped by the autowrite and writeany edit options, so keep those in mind.

Current line: set the same way the edit command does it.

Current column: also set the same way the edit command does it.

✨ Set ✨

Synopsis:

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

When you pass no arguments at all, it writes out the value of the term edit option plus every option whose value has drifted from its default. And when you pass the argument all? It writes out every single option value. the whole menu, bestie. 👑

Give an option name followed by the character '?' and it writes the current value of that option. That '?' can be separated from the option name by zero or more <blank> characters — so no stress about spacing. The '?' is only really necessary for Boolean-valued options. Booleans get their values from set option to flip them on, or set nooption to flip them off; string and numeric options get assigned with set option=value. 🌸

Any <blank> characters living inside strings can be included as-is if you precede each <blank> with an escaping <backslash>. And you can set or list more than one option in a single set command — just pass multiple arguments, each separated from the next by one or more <blank> characters. ✨

See Edit Options in ex for the deets on specific options.

Current line: unchanged. 🫶

Current column: unchanged.

🐚 Shell 🐚

Synopsis:

sh[ell]

This invokes the program named in the shell edit option, handing it the single argument -i (interactive mode). Editing picks back up when that program exits. 💅

Current line: unchanged.

Current column: unchanged.

📜 Source 📜

Synopsis:

so[urce] file

Reads and executes ex commands out of file. Blank lines in that file? Ignored, bestie, they're not the vibe. 🦋

Current line: as specified for the individual ex commands.

Current column: as specified for the individual ex commands.

🔥 Substitute 🔥

Synopsis:

[2addr] s[ubstitute][/pattern/repl/[options][count][flags]]
[2addr] &[options][count][flags]]
[2addr] ~[options][count][flags]]

Replace the first instance of the pattern pattern with the string repl on each specified line. (Peep Regular Expressions in ex and Replacement Strings in ex for that whole situation.) Any non-alphabetic, non-<blank> delimiter other than <backslash>, '|', <newline>, or double-quote can stand in for '/'. And <backslash> characters can escape delimiters, <backslash> characters, and other special characters. 🎀

The trailing delimiter can be omitted from pattern or from repl when you're at the end of the command line. If both pattern and repl are unspecified or empty (think "//"), the last s command gets repeated. If only pattern is unspecified or empty, the last regular expression used in the editor becomes the pattern. If only repl is unspecified or empty, the pattern gets replaced by nothing. And if the entire replacement pattern is '%', the last replacement pattern from an s command gets used. 💫

Typing a <carriage-return> inside repl — which needs an escaping <backslash> in ex mode and an escaping <control>‐V in open or vi mode — splits the line right at that point, creating a new line in the edit buffer. The <carriage-return> itself gets discarded. 🫶

If options includes the letter 'g' (global), then all non-overlapping instances of the pattern in the line get replaced. Slay.

If options includes the letter 'c' (confirm), then before each substitution the line gets written out; the written line reflects all the previous substitutions. On the following line, <space> characters get written beneath the characters from the line that come before the pattern being replaced, and '^' characters get written beneath the characters included in the pattern being replaced. Then ex waits for a response from you. An affirmative response does the substitution; any other input does not do it. An affirmative response is a line with the affirmative response (as defined by the current locale) at the beginning of the line. That line is subject to editing just like the ex command line. 😌

If interrupted (go check the ASYNCHRONOUS EVENTS section), any modifications you already confirmed are preserved in the edit buffer after the interrupt. 🛟

If the remembered search direction isn't set, the s command sets it to forward.

In the second Synopsis, the & command repeats the previous substitution, as if & were replaced by:

s/pattern/repl/

where pattern and repl are as specified in the previous s, &, or ~ command.

In the third Synopsis, the ~ command repeats the previous substitution, as if the '~' were replaced by:

s/pattern/repl/

where pattern is the last regular expression specified to the editor, and repl comes from the previous substitution (including & and ~) command.

These commands get affected by the LC_MESSAGES environment variable. 🌈

Current line: set to the last line where a substitution actually happened, or unchanged if none did.

Current column: set to non-<blank>.

💤 Suspend 💤

Synopsis:

su[spend][!]
st[op][!]

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

These commands get affected by the autowrite and writeany edit options.

The current susp character (see stty) is equivalent to the suspend command.

🏷️ Tag 🏷️

Synopsis:

ta[g][!] tagstring

The results are unspecified if the format of a tags file isn't what the ctags utility specifies (see the ctags description). ⚠️

The tag command searches for tagstring in the tag files referred to by the tag edit option, in the order they're specified, until a reference to tagstring turns up. Files get searched from beginning to end. If no reference is found, that's an error and an error message saying so gets written. If the reference isn't found, or if an error happens while processing a file referred to in the tag edit option, it's an error, and an error message gets written at the first occurrence of that error. 💀

Otherwise, if the tags file contained a pattern, that pattern is treated as a regular expression used in the editor — like, for the purposes of the s command and all that. ✨

If tagstring lives in a file with a different name than the current pathname, the current pathname gets set to that file's name, and the edit buffer's contents get replaced with that file's contents. In this case, if no '!' is appended to the command name and the edit buffer has been modified since the last complete write, that's an error — unless the file gets successfully written as specified by the autowrite option. 🫶

This command gets affected by the autowrite, tag, taglength, and writeany edit options.

Current line: if the tags file contained a line number, it's set to that line number. If that line number is larger than the last line in the edit buffer, an error message gets written and the current line gets set as specified for the edit command.

If the tags file contained a pattern, it's set to the first occurrence of the pattern in the file. If no matching pattern is found, an error message gets written and the current line gets set as specified for the edit command.

Current column: if the tags file contained a line-number reference and that line number wasn't larger than the last line in the edit buffer, or if the tags file contained a pattern and that pattern was found, it's set to non-<blank>. Otherwise, it's set as specified for the edit command.

🚫 Unabbreviate 🚫

Synopsis:

una[bbrev] lhs

If lhs isn't an entry in the current list of abbreviations (see Abbreviate), that's an error. Otherwise, lhs gets deleted from the list of abbreviations. Bye bestie. 👋

Current line: unchanged.

Current column: unchanged.

↩️ Undo ↩️

Synopsis:

u[ndo]

Reverses the changes made by the last command that modified the contents of the edit buffer — including undo. And for this purpose, the global, v, open, and visual commands, plus commands resulting from buffer executions and mapped character expansions, all count as single commands. 🌀

If no action that can be undone preceded the undo command, that's an error. 😭

If the undo command restores lines that were marked, the mark gets restored too — unless it was reset after the lines were deleted. 🎀

Current line:

If lines are added or changed in the file, set to the first line added or changed.
Set to the line before the first line deleted, if it exists.
Set to 1 if the edit buffer is not empty.
Set to zero.

Current column: set to non-<blank>.

🗺️ Unmap 🗺️

Synopsis:

unm[ap][!] lhs

If '!' is appended to the command name, and if lhs isn't an entry in the list of text input mode map definitions, that's an error. Otherwise, lhs gets deleted from the list of text input mode map definitions. 💅

If no '!' is appended to the command name, and if lhs isn't an entry in the list of command mode map definitions, that's an error. Otherwise, lhs gets deleted from the list of command mode map definitions.

Current line: unchanged.

Current column: unchanged.

👑 Version 👑

Synopsis:

ve[rsion]

Writes a message containing version information for the editor. The format of that message is unspecified. ✨

Current line: unchanged.

Current column: unchanged.

🦋 Visual 🦋

Synopsis:

[1addr] vi[sual][type][count][flags]

If ex is currently in open or visual mode, the Synopsis and behavior of the visual command are the same as the edit command, as specified by Edit.

Otherwise, this command need not be supported on block-mode terminals or terminals with insufficient capabilities. And if standard input, standard output, or standard error aren't terminal devices, the results are unspecified. ⚠️

If count is specified, the value of the window edit option gets set to count (as described in window). If the '^' type character was also specified, the window edit option gets set before being used by the type character. 🌸

Enters visual mode. If type isn't specified, it's as if a type of '+' had been specified. The type causes the following effects:

+ — put the start of the line you named right at the tippy top of the display. 💅
- — put the end of that line at the bottom of the display. ✨
. — put the start of the line smack in the middle of the display. 🎯
^ — okay so if the line you named is less than or equal to the value of the window edit option, set the line to 1. Otherwise, decrement the line by the value of the window edit option minus 1. Then place the start of this line as close to the bottom of the displayed lines as possible, while still showing the window edit option number of lines. 🫶

Current line: set to the line you specified, bestie.

Current column: set to non-<blank>. periodt.

💾 Write

Synopsis, here for you:

[2addr] w[rite][!][>>][file]
[2addr] w[rite][!][file]
[2addr] wq[!][>>][file]

If no lines are specified, the lines default to the entire file. yes, the whole thing. 🍓

The wq command is equivalent to a write command followed by a quit command; wq! is equivalent to write! followed by quit. In both cases, if the write command fails, the quit shall not be attempted. no cap, it just stops there. 💀

If the command name is not followed by one or more <blank> characters, or file is not preceded by a ! character, the write shall be to a file.

If the >> argument is specified, and the file already exists, the lines shall be appended to the file instead of replacing its contents. If the >> argument is specified, and the file does not already exist, it is unspecified whether the write shall proceed as if the >> argument had not been specified, or if the write shall fail. (iykyk — unspecified means don't count on it being one way. 🙈)
If the readonly edit option is set (see readonly), the write shall fail. 🔒
If file is specified, and is not the current pathname, and the file exists, the write shall fail.
If file is not specified, the current pathname shall be used. If there is no current pathname, the write command shall fail. 😭
If the current pathname is used, and the current pathname has been changed by the file or read commands, and the file exists, the write shall fail. If the write is successful, subsequent writes shall not fail for this reason (unless the current pathname is changed again).
If the whole edit buffer is not being written, and the file to be written exists, the write shall fail.

For rules 1., 2., 3., and 5., the write can be forced by appending the character ! to the command name. 💅

For rules 2., 3., and 5., the write can be forced by setting the writeany edit option. 🔥

Additional, implementation-defined tests may cause the write to fail. (mystery behavior, we love her ✨)

If the edit buffer is empty, a file without any contents shall be written.

An informational message shall be written noting the number of lines and bytes written. 📝

Otherwise, if the command is followed by one or more <blank> characters, and the file is preceded by !, the rest of the line after the ! shall have %, #, and ! characters expanded as described in Command Line Parsing in ex. 🌸

The ex utility shall then pass two arguments to the program named by the shell edit option; the first shall be -c and the second shall be the expanded arguments to the write command as a single argument. The specified lines shall be written to the standard input of the command. The standard error and standard output of the program, if any, shall be written as described for the print command. If the last character in that output is not a <newline>, a <newline> shall be written at the end of the output. 💖

The special meaning of the ! following the write command can be overridden by escaping it with a <backslash> character.

Current line: unchanged.

Current column: unchanged.

🚪 Write and Exit

Synopsis:

[2addr] x[it][!][file]

If the edit buffer has not been modified since the last complete write, xit shall be equivalent to the quit command, or if a ! is appended to the command name, to quit!. 👑

Otherwise, xit shall be equivalent to the wq command, or if a ! is appended to the command name, to wq!.

Current line: unchanged.

Current column: unchanged.

📋 Yank

Synopsis:

[2addr] ya[nk][buffer][count]

Copy the specified lines to the specified buffer (by default, the unnamed buffer), which shall become a line-mode buffer. so iconic. 🎀

Current line: unchanged.

Current column: unchanged.

🪟 Adjust Window

Synopsis:

[1addr] z[!][type ...][count][flags]

If no line is specified, the current line shall be the default; if type is omitted as well, the current line value shall first be incremented by 1. If incrementing the current line would cause it to be greater than the last line in the edit buffer, it shall be an error. 😭

If there are <blank> characters between the type argument and the preceding z command name or optional ! character, it shall be an error.

If count is specified, the value of the window edit option shall be set to count (as described in window). If count is omitted, it shall default to 2 times the value of the scroll edit option, or if ! was specified, the number of lines in the display minus 1.

If type is omitted, then count lines starting with the specified line shall be written. Otherwise, count lines starting with the line specified by the type argument shall be written.

The type argument shall change the lines to be written. The possible values of type are as follows:

- — the specified line shall be decremented by the following value:

(((number of '-' characters) x count) -1)

If the calculation would result in a number less than 1, it shall be an error. Write lines from the edit buffer, starting at the new value of line, until count lines or the last line in the edit buffer has been written.

+ — the specified line shall be incremented by the following value:

(((number of '+' characters) -1) x count) +1

If the calculation would result in a number greater than the last line in the edit buffer, it shall be an error. Write lines from the edit buffer, starting at the new value of line, until count lines or the last line in the edit buffer has been written.

=, . — if more than a single . or = is specified, it shall be an error. The following steps shall be taken:
1. If count is zero, nothing shall be written.
2. Write as many of the N lines before the current line in the edit buffer as exist. If count or ! was specified, N shall be:

(count -1) /2

Otherwise, N shall be:

(count -3) /2

If N is a number less than 3, no lines shall be written.

If = was specified as the type character, write a line consisting of the smaller of the number of columns in the display divided by two, or 40 - characters.
Write the current line.
Repeat step 3.
Write as many of the N lines after the current line in the edit buffer as exist. N shall be defined as in step 2. If N is a number less than 3, no lines shall be written. If count is less than 3, no lines shall be written.

^ — the specified line shall be decremented by the following value:

(((number of '^' characters) +1) x count) -1

Current line: set to the last line written, unless the type is =, in which case, set to the specified line.

Current column: set to non-<blank>. 💅

🏃 Escape

Synopsis:

! command
[addr]! command

The contents of the line after the ! shall have %, #, and ! characters expanded as described in Command Line Parsing in ex. If the expansion causes the text of the line to change, it shall be redisplayed, preceded by a single ! character. ✨

The ex utility shall execute the program named by the shell edit option. It shall pass two arguments to the program; the first shall be -c, and the second shall be the expanded arguments to the ! command as a single argument.

If no lines are specified, the standard input, standard output, and standard error of the program shall be set to the standard input, standard output, and standard error of the ex program when it was invoked. In addition, a warning message shall be written if the edit buffer has been modified since the last complete write, and the warn edit option is set. ⚠️

If lines are specified, they shall be passed to the program as standard input, and the standard output and standard error of the program shall replace those lines in the edit buffer. Each line in the program output (as delimited by <newline> characters or the end of the output if it is not immediately preceded by a <newline>), shall be a separate line in the edit buffer. Any occurrences of <carriage-return> and <newline> pairs in the output shall be treated as single <newline> characters. The specified lines shall be copied into the unnamed buffer before they are replaced, and the unnamed buffer shall become a line-mode buffer. 🦋

If in ex mode, a single ! character shall be written when the program completes.

This command shall be affected by the shell and warn edit options. If no lines are specified, this command shall be affected by the autowrite and writeany edit options. If lines are specified, this command shall be affected by the autoprint edit option.

Current line:

If no lines are specified, unchanged.
Otherwise, set to the last line read in, if any lines are read in.
Otherwise, set to the line before the first line of the lines specified, if that line exists.
Otherwise, set to the first line of the edit buffer if the edit buffer is not empty.
Otherwise, set to zero.

Current column: if no lines are specified, unchanged. Otherwise, set to non-<blank>.

⬅️ Shift Left

Synopsis:

[2addr] <[< ...][count][flags]

Shift the specified lines to the start of the line; the number of column positions to be shifted shall be the number of command characters times the value of the shiftwidth edit option. Only leading <blank> characters shall be deleted or changed into other <blank> characters in shifting; other characters shall not be affected. 🎀

Lines to be shifted shall be copied into the unnamed buffer, which shall become a line-mode buffer.

This command shall be affected by the autoprint edit option. 🌸

Current line: set to the last line in the lines specified.

Current column: set to non-<blank>.

🎀 Shift Right 🎀

Synopsis:

[2addr] >[> ...][count][flags]

Okay so this one shoves your lines away from the start of the line — a rightward scoot, no cap 💅. The number of column positions to be shifted shall be the number of command characters times the value of the shiftwidth edit option. So two > characters = 2 × shiftwidth. Math is math, bestie.

The shift shall be accomplished by adding <blank> characters as a prefix to the line, or by changing leading <blank> characters into other <blank> characters. Empty lines shall not be changed — they're literally perfect as they are.

Lines to be shifted shall be copied into the unnamed buffer, which shall become a line-mode buffer.

This command shall be affected by the autoprint edit option.

Current line: set to the last line in the lines specified.

Current column: set to non-<blank>.

✨ `<control>-D` ✨

Synopsis:

<control>-D

Write the next n lines, where n is the minimum of the values of the scroll edit option and the number of lines after the current line in the edit buffer. If the current line is the last line of the edit buffer, it shall be an error. 💀

Current line: set to the last line written.

Current column: set to non-<blank>.

🌸 Write Line Number 🌸

Synopsis:

[1addr] = [flags]

If line is not specified, it shall default to the last line in the edit buffer. Then it writes the line number of the specified line. That's it. That's the whole thing. ✨

Current line: unchanged.

Current column: unchanged.

👑 Execute 👑

Synopsis:

[2addr] @ buffer
[2addr] * buffer

If no buffer is specified, or it's specified as '@' or '*', the last buffer executed shall be used. If no previous buffer has been executed, it shall be an error.

For each line specified by the addresses, set the current line ('.') to the specified line, and execute the contents of the named buffer (as they were at the time the @ command was executed) as ex commands. For each line of a line-mode buffer, and all but the last line of a character-mode buffer, the ex command parser shall behave as if the line was terminated by a <newline>.

⚠️ If an error occurs during this process, or a line specified by the addresses does not exist when the current line would be set to it, or more than a single line was specified by the addresses, and the contents of the edit buffer are replaced (for example, by the ex :edit command), an error message shall be written, and no more commands resulting from the execution of this command shall be processed.

Current line: as specified for the individual ex commands.

Current column: as specified for the individual ex commands.

🌈 Regular Expressions in `ex` 🌈

The ex utility shall support regular expressions that are a superset of the basic regular expressions described in the Base Definitions volume of POSIX.1‐2017, Section 9.3, Basic Regular Expressions. A null regular expression ("//") shall be equivalent to the last regular expression encountered. Yes bestie, it remembers. 👑

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. The <backslash> shall be discarded.

Now the plot twist 🫠: when the editor option magic is not set, the only characters with special meanings shall be '^' at the beginning of a pattern, '$' at the end of a pattern, and <backslash>. The characters '.', '*', '[', and '~' shall be treated as ordinary characters unless preceded by a <backslash>; when preceded by a <backslash> they shall regain their special meaning — or, in the case of <backslash>, be handled as a single <backslash>. And <backslash> characters used to escape other characters shall be discarded.

💖 Replacement Strings in `ex` 💖

The character '&' ('\&' if the editor option magic is not set) in the replacement string shall stand for the text matched by the pattern to be replaced. The character '~' ('\~' if magic is not set) shall be replaced by the replacement part of the previous substitute command. The sequence '\n', where n is an integer, shall be replaced by the text matched by the corresponding back-reference expression. If the corresponding back-reference expression does not match, then the characters '\n' shall be replaced by the empty string.

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') shall cause the character that follows to be converted to lowercase (uppercase). The string '\L' ('\U') shall cause all characters subsequent to it to be converted to lowercase (uppercase) as they are inserted by the substitution, until the string '\e' or '\E', or the end of the replacement string, is encountered. Case glow-up: unlocked. 💅

Otherwise, any character following a <backslash> shall be treated as that literal character, and the escaping <backslash> shall be discarded.

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.

🎀 Edit Options in `ex` 🎀

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

Options are Boolean unless otherwise specified.

⭐ `autoindent`, `ai` ⭐

[Default unset]

If autoindent is set, each line in input mode shall 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 another line, as follows:

If in open or visual mode and the text input is part of a line-oriented command (see the EXTENDED DESCRIPTION in vi), align to the first column.
Otherwise, if in open or visual mode, indentation for each line shall be set as follows:
1. If a line was previously inserted as part of this command, it shall be set to the indentation of the last inserted line by default, or as otherwise specified for the <control>‐D character in Input Mode Commands in vi.
2. Otherwise, it shall be set to the indentation of the previous current line, if any; otherwise, to the first column.
For the ex a, i, and c commands, indentation for each line shall be set as follows:
1. If a line was previously inserted as part of this command, it shall be set to the indentation of the last inserted line by default, or as otherwise specified for the eof character in Scroll.
2. Otherwise, if the command is the ex a command, it shall be set to the line appended after, if any; otherwise to the first column.
3. Otherwise, if the command is the ex i command, it shall be set to the line inserted before, if any; otherwise to the first column.
4. Otherwise, if the command is the ex c command, it shall be set to the indentation of the line replaced.

💅 `autoprint`, `ap` 💅

[Default set]

If autoprint is set, the current line shall be written after each ex command that modifies the contents of the current edit buffer, and after each tag command for which the tag search pattern was found or tag line number was valid — unless:

The command was executed while in open or visual mode.
The command was executed as part of a global or v command or @ buffer execution.
The command was the form of the read command that reads a file into the edit buffer.
The command was the append, change, or insert command.
The command was not terminated by a <newline>.
The current line shall be written by a flag specified to the command; for example, delete # shall write the current line as specified for the flag modifier to the delete command, and not as specified by the autoprint edit option.

🌸 `autowrite`, `aw` 🌸

[Default unset]

If autowrite is set, and the edit buffer has been modified since it was last completely written to any file, the contents of the edit buffer shall be written as if the ex write command had been specified without arguments, before each command affected by the autowrite edit option is executed. Appending the character '!' to the command name of any of the ex commands except '!' shall prevent the write. If the write fails, it shall be an error and the command shall not be executed. 😭

🦋 `beautify`, `bf` 🦋

[Default unset]

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

🎀 `directory`, `dir` 🎀

[Default implementation-defined]

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 shall quit. 💀

⭐ `edcompatible`, `ed` ⭐

[Default unset]

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

🔔 `errorbells`, `eb` 🔔

[Default unset]

If the editor is in ex mode, and the terminal does not support a standout mode (such as inverse video), and errorbells is set, error messages shall be preceded by alerting the terminal. Beep beep, bestie. 🔔

🏠 `exrc` 🏠

[Default unset]

If exrc is set, ex shall access any .exrc file in the current directory, as described in Initialization in ex and vi. If exrc is not set, ex shall ignore any .exrc file in the current directory during initialization, unless the current directory is that named by the HOME environment variable. 👀

🌈 `ignorecase`, `ic` 🌈

[Default unset]

If ignorecase is set, characters that have uppercase and lowercase representations shall have those representations considered as equivalent for purposes of regular expression comparison.

The ignorecase edit option shall affect all remembered regular expressions; for example, unsetting the ignorecase edit option shall cause a subsequent vi n command to search for the last basic regular expression in a case-sensitive fashion. 🔍

✨ `list` ✨

[Default unset]

👯 `list`

If list is set, edit buffer lines written while you're in ex command mode get written exactly like the print command with the l flag on. And in open or visual mode, every edit buffer line gets displayed the way the ex print command with the l flag says. Also, in open or visual text input mode, if the cursor isn't sitting on any character in the line, it parks itself on the '$' that marks the end of the line. 💅

✨ `magic`

[Default set]

If magic is set, it changes how characters get interpreted inside regular expressions and substitution replacement strings (peep Regular Expressions in ex and Replacement Strings in ex, bestie).

💬 `mesg`

[Default set]

If mesg is set, other people are allowed to use the write or talk commands to write to your terminal while you're in open or visual mode. BUT — and this is the plot twist — the shell-level command mesg n takes precedence over literally any setting of the ex mesg option. Meaning: if mesg y was issued before the editor even started (or in a shell escape), like:

:!mesg y

then the mesg option in ex shall suppress incoming messages, but the mesg option can't enable incoming messages if mesg n was issued. It's giving "you can turn it off but you cannot turn it on" 😭

🔢 `number`, `nu`

[Default unset]

If number is set, edit buffer lines written while in ex command mode get written with line numbers, formatted exactly like the print command with the # flag specified. In ex text input mode, each line gets a line number in front of it — the number it's gonna have in the file. 💖

In open or visual mode, each edit buffer line gets displayed with a preceding line number too, same format as the ex print command with the # flag. That line number is not part of the line when it comes to evaluating the current column — so column position 1 is the first column position after the format the print command specified. No cap. 🫶

📝 `paragraphs`, `para`

[Default in the POSIX locale IPLPPPQPP LIpplpipbp]

The paragraphs edit option defines extra paragraph boundaries for the open and visual mode commands. You can set it to a character string made of zero or more character pairs. Setting it to an odd number of characters is an error, periodt.

💬 `prompt`

[Default set]

If prompt is set, ex command mode input gets prompted with a <colon> (':'). When it's unset, no prompt gets written. Simple as that. ✨

🔒 `readonly`

[Default see text]

If the readonly edit option is set, read-only mode is enabled (see Write). The readonly edit option gets initialized to set if either of these is true:

The command-line option -R was specified.
Performing actions equivalent to the access() function called with these arguments says the file lacks write permission:
1. The current pathname is used as the path argument.
2. The constant W_OK is used as the amode argument.

The readonly edit option may also get initialized to set for other, implementation-defined reasons. But it shall not be initialized to unset just because the user or process has some special privileges. And it gets reinitialized every single time the contents of the edit buffer are replaced (like by an edit or next command) — unless the user explicitly set it, in which case it stays set until the user explicitly unsets it. Once unset? It goes right back to being reinitialized every time the edit buffer contents get replaced. 💀

🖥️ `redraw`

[Default unset]

The editor simulates an intelligent terminal on a dumb terminal. (Since this is probably gonna blast a huge amount of output at your terminal, it's only really useful at high transmission speeds.) 😭

🗺️ `remap`

[Default set]

If remap is set, map translation is allowed to work with maps that are defined in terms of other maps — translation keeps going until it hits a final product. If it's unset, only a one-step translation happens. 🔥

📢 `report`

[Default 5]

The value of this report edit option says how many lines being added, copied, deleted, or modified in the edit buffer will trigger an informational message to you. These conditions cause an informational message, and the message contains the number of lines added, copied, deleted, or modified — but otherwise it's unspecified:

An ex or vi editor command, other than open, undo, or visual, that modifies at least the value of the report edit option number of lines, and which isn't part of an ex global or v command, or ex or vi buffer execution, causes an informational message to be written.
An ex yank or vi y or Y command that copies at least the value of the report edit option plus 1 number of lines, and which isn't part of an ex global or v command, or ex or vi buffer execution, causes an informational message to be written.
An ex global, v, open, undo, or visual command, or ex or vi buffer execution, that adds or deletes a total of at least the value of the report edit option number of lines, and which isn't part of an ex global or v command, or ex or vi buffer execution, causes an informational message to be written. (So like, if 3 lines were added and 8 lines deleted during an ex visual command, 5 would be the number compared against the report edit option after the command finished.) 🧮

📜 `scroll`, `scr`

[Default (number of lines in the display -1)/2]

The value of the scroll edit option determines how many lines get scrolled by the ex <control>-D and z commands. For the vi <control>-D and <control>-U commands, it's the initial number of lines to scroll when no previous <control>-D or <control>-U command has been executed. 💫

📑 `sections`

[Default in the POSIX locale NHSHH HUnhsh]

The sections edit option defines extra section boundaries for the open and visual mode commands. You can set it to a character string of zero or more character pairs. Setting it to an odd number of characters is an error. (Same energy as paragraphs, iykyk. 🎀)

🐚 `shell`, `sh`

[Default from the environment variable SHELL]

The value of this option is a string. The default gets taken from the SHELL environment variable. And if the SHELL environment variable is null or empty? Then the sh (see sh) utility is the default. Slay. 💜

↔️ `shiftwidth`, `sw`

[Default 8]

The value of this option gives the width, in columns, of an indentation level used during autoindentation and by the shift commands (< and >). ✨

🧲 `showmatch`, `sm`

[Default unset]

Heads up bestie: the functionality described for the showmatch edit option doesn't need to be supported on block-mode terminals or terminals with insufficient capabilities.

If showmatch is set, then in open or visual mode, when you type a ')' or '}', and the matching '(' or '{' is currently visible on the display, that matching '(' or '{' gets flagged by moving the cursor to its location for an unspecified amount of time. 👀

🏷️ `showmode`

[Default unset]

If showmode is set, then in open or visual mode, the current mode the editor is in gets displayed on the last line of the display. Command mode and text input mode get differentiated; other unspecified modes and implementation-defined info may also be displayed. Main character energy tbh. 👑

🐌 `slowopen`

[Default unset]

If slowopen is set during open and visual text input modes, the editor shall not update portions of the display other than those display line columns that show the characters you typed (see Input Mode Commands in vi). Slow and steady. 🐢

📏 `tabstop`, `ts`

[Default 8]

The value of this edit option specifies the column boundary used by a <tab> in the display (see autoprint, ap and Input Mode Commands in vi). 🌈

🏷️ `taglength`, `tl`

[Default zero]

The value of this edit option specifies the maximum number of characters considered significant in the user-specified tag name and in the tag name from the tags file. If the value is zero, then all characters in both tag names are significant. Zero = no filter, we love that for us. 💅

🗂️ `tags`

[Default see text]

The value of this edit option is a string of <blank>-delimited pathnames of files used by the tag command. The default value is unspecified. 🤷♀️

🖥️ `term`

[Default from the environment variable TERM]

The value of this edit option is a string. The default gets taken from the TERM variable in the environment. If the TERM environment variable is empty or null, the default is unspecified. The editor uses the value of this edit option to figure out what type of display device you're on.

⚠️ The results are unspecified if you change the value of the term edit option after editor initialization. So like, don't do that. 😭

🤐 `terse`

[Default unset]

If terse is set, error messages may be less verbose. But other than that caveat, error messages are unspecified. Also, not all error messages need to change for different settings of this option. Lowkey mysterious of it. 🙈

🚨 `warn`

[Default set]

If warn is set, and the contents of the edit buffer have been modified since they were last completely written, the editor writes a warning message before certain ! commands (see Escape). It's looking out for you fr fr. 🫶

🪟 `window`

[Default see text]

A value used in open and visual mode, by the <control>-B and <control>-F commands, and — in visual mode — to specify the number of lines displayed when the screen gets repainted. ✨

If the -w command-line option is not specified, the default value gets set to the value of the LINES environment variable. If the LINES environment variable is empty or null, the default is the number of lines in the display minus 1.

Setting the window edit option to zero, or to a value greater than the number of lines in the display minus 1 (whether you did it explicitly, or it came from the -w option, or from the LINES environment variable), causes the window edit option to be set to the number of lines in the display minus 1. 💅

The baud rate of the terminal line may change the default in an implementation-defined manner. 📡

📐 `wrapmargin`, `wm`

[Default 0]

If the value of this edit option is zero, it has no effect.

If you're not in the POSIX locale, the effect of this edit option is implementation-defined.

Otherwise, it specifies a number of columns from the ending margin of the terminal.

During open and visual text input modes, for each character for which any part of the character is displayed in a column that is less than wrapmargin columns from the ending margin of the display line, the editor shall behave as follows: 🌸

If the character triggering this event is a <blank>, it — plus all the <blank> characters sitting immediately before it on the current line, that got entered while the current text input command was running — gets yeeted. 💨 And the editor then behaves like you'd typed a single <newline> instead. Extra bonus: if the very next character you enter is a <space>, that one gets discarded too.
Otherwise, if there are one or more <blank> characters on the current line immediately preceding the last group of inserted non-<blank> characters entered during the current text input command, those <blank> characters get replaced as if the user had entered a single <newline> instead. swap. periodt.

If the autoindent edit option is set, and the events described in 1. or 2. get performed, any <blank> characters at or after the cursor in the current line get discarded. gone. poof. 🫧

The ending margin gets determined by the system, or overridden by the user, exactly as described for COLUMNS in the ENVIRONMENT VARIABLES section and in the Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables.

✨ wrapscan, ws ✨

[Default set]

If wrapscan is set, searches (the ex / or ? addresses, or open and visual mode /, ?, N, and n commands) wrap around the beginning or end of the edit buffer; when it's unset, searches stop at the beginning or end of the edit buffer. like, no looping around the block, you just hit the wall and that's it. 🧱

💫 writeany, wa 💫

[Default unset]

If writeany is set, some of the checks performed when executing the ex write commands get inhibited, as described in editor option autowrite.

🎀 EXIT STATUS 🎀

The following exit values shall be returned:

0 — Successful completion. we love to see it. ✨
>0 — An error occurred. 😭

🫠 CONSEQUENCES OF ERRORS 🫠

When any error is encountered and the standard input is not a terminal device file, ex shall not write the file or return to command or text input mode, and shall terminate with a non-zero exit status. it's giving "we're done here". 💀

Otherwise, when an unrecoverable error is encountered, it shall be equivalent to a SIGHUP asynchronous event.

Otherwise, when an error is encountered, the editor shall behave as specified in Command Line Parsing in ex.

The following sections are informative. (translation: they're the lore, not the law 💅)

🌈 APPLICATION USAGE 🌈

If a SIGSEGV signal is received while ex is saving a file, the file might not be successfully saved. bestie, that file is on its own. 🙈

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. one (1) file only, no sharing. 🚫

📋 EXAMPLES 📋

None.

literally none. the section is empty. iconic behaviour honestly. 💀

🧠 RATIONALE 🧠

The ex/vi specification is based on the historical practice found in the 4 BSD and System V implementations of ex and vi.

A restricted editor (both the historical red utility and modifications to ex) were considered and rejected for inclusion. Neither option provided the level of security that users might expect. 🚩

It is recognized that ex visual mode and related features would be difficult, if not impossible, to implement satisfactorily on a block-mode terminal, or a terminal without any form of cursor addressing; thus, it is not a mandatory requirement that such features should work on all terminals. It is the intention, however, that an ex implementation should provide the full set of capabilities on all terminals capable of supporting them. so like, not required, but pls. 🥺

🌸 Options 🌸

The -c replacement for +command was inspired by the -e option of sed. Historically, all such commands (see edit and next as well) were executed from the last line of the edit buffer. This meant, for example, that "+/pattern" would fail unless the wrapscan option was set. POSIX.1‐2008 requires conformance to historical practice. The +command option is no longer specified by POSIX.1‐2008 but may be present in some implementations. Historically, some implementations restricted the ex commands that could be listed as part of the command line arguments. For consistency, POSIX.1‐2008 does not permit these restrictions.

In historical implementations of the editor, the -R option (and the readonly edit option) only prevented overwriting of files; appending to files was still permitted, mapping loosely into the csh noclobber variable. Some implementations, however, have not followed this semantic, and readonly does not permit appending either. POSIX.1‐2008 follows the latter practice, believing that it is a more obvious and intuitive meaning of readonly. ngl, "readonly means readonly" is a pretty solid take. 💅

The -s option suppresses all interactive user feedback and is useful for editing scripts in batch jobs. The list of specific effects is historical practice. The terminal type "incapable of supporting open and visual modes" has historically been named "dumb". (yes, actually. that's the real name. 🫠)

The -t option was required because the ctags utility appears in POSIX.1‐2008 and the option is available in all historical implementations of ex.

Historically, the ex and vi utilities accepted a -x option, which did encryption based on the algorithm found in the historical crypt utility. The -x option for encryption, and the associated crypt utility, were omitted because the algorithm used was not specifiable and the export control laws of some nations make it difficult to export cryptographic technology. In addition, it did not historically provide the level of security that users might expect. 💀💀

🦋 Standard Input 🦋

An end-of-file condition is not equivalent to an end-of-file character. A common end-of-file character, <control>‐D, is historically an ex command.

There was no maximum line length in historical implementations of ex. Specifically, as it was parsed in chunks, the addresses had a different maximum length than the filenames. Further, the maximum line buffer size was declared as BUFSIZ, which was different lengths on different systems. This version selected the value of {LINE_MAX} to impose a reasonable restriction on portable usage of ex and to aid test suite writers in their development of realistic tests that exercise this limit.

🎀 Input Files 🎀

It was an explicit decision by the standard developers that a <newline> be added to any file lacking one. It was believed that this feature of ex and vi was relied on by users in order to make text files lacking a trailing <newline> more portable. It is recognized that this will require a user-specified option or extension for implementations that permit ex and vi to edit files of type other than text if such files are not otherwise identified by the system. It was agreed that the ability to edit files of arbitrary type can be useful, but it was not considered necessary to mandate that an ex or vi implementation be required to handle files other than text files.

The paragraph in the INPUT FILES section, "By default, ...", is intended to close a long-standing security problem in ex and vi; that of the "modeline" or "modelines" edit option. This feature allows any line in the first or last five lines of the file containing the strings "ex:" or "vi:" (and, apparently, "ei:" or "vx:") to be a line containing editor commands, and ex interprets all the text up to the next ':' or <newline> as a command. Consider the consequences, for example, of an unsuspecting user using ex or vi as the editor when replying to a mail message in which a line such as:

ex:! rm -rf :

appeared in the signature lines. 😭 The standard developers believed strongly that an editor should not by default interpret any lines of a file.

Vendors are strongly urged to delete this feature from their implementations of ex and vi. like, pls. for the love of everything. 🚨

💜 Asynchronous Events 💜

The intention of the phrase "complete write" is that the entire edit buffer be written to stable storage. The note regarding temporary files is intended for implementations that use temporary files to back edit buffers unnamed by the user.

Historically, SIGQUIT was ignored by ex, but was the equivalent of the Q command in visual mode; that is, it exited visual mode and entered ex mode. POSIX.1‐2008 permits, but does not require, this behavior. Historically, SIGINT was often used by vi users to terminate text input mode (<control>‐C is often easier to enter than <ESC>). Some implementations of vi alerted the terminal on this event, and some did not. POSIX.1‐2008 requires that SIGINT behave identically to <ESC>, and that the terminal not be alerted.

Historically, suspending the ex editor during text input mode was similar to SIGINT, as completed lines were retained, but any partial line discarded, and the editor returned to command mode. POSIX.1‐2008 is silent on this issue; implementations are encouraged to follow historical practice, where possible.

Historically, the vi editor did not treat SIGTSTP as an asynchronous event, and it was therefore impossible to suspend the editor in visual text input mode. There are two major reasons for this. The first is that SIGTSTP is a broadcast signal on UNIX systems, and the chain of events where the shell execs an application that then execs vi usually caused confusion for the terminal state if SIGTSTP was delivered to the process group in the default manner. The second was that most implementations of the UNIX curses package did not handle SIGTSTP safely, and the receipt of SIGTSTP at the wrong time would cause them to crash. POSIX.1‐2008 is silent on this issue; implementations are encouraged to treat suspension as an asynchronous event if possible.

Historically, modifications to the edit buffer made before SIGINT interrupted an operation were retained; that is, anywhere from zero to all of the lines to be modified might have been modified by the time the SIGINT arrived. These changes were not discarded by the arrival of SIGINT. POSIX.1‐2008 permits this behavior, noting that the undo command is required to be able to undo these partially completed commands. chaos but make it undoable. 🌀

The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and SIGTERM is unspecified because some implementations attempt to save the edit buffer in a useful state when other signals are received.

⭐ Standard Error ⭐

For ex/vi, diagnostic messages are those messages reported as a result of a failed attempt to invoke ex or vi, such as invalid options or insufficient resources, or an abnormal termination condition. Diagnostic messages should not be confused with the error messages generated by inappropriate or illegal user commands. two totally different vibes, do not mix them up bestie. 💅

👑 Initialization in ex and vi 👑

If an ex command (other than cd, chdir, or source) has a filename argument, one or both of the alternate and current pathnames will be set. Informally, they are set as follows:

If the ex command is one of those that replaces the whole contents of the edit buffer, and it goes through, then the current pathname gets set to the filename argument — and for next, that's the first filename argument, bestie, don't get it twisted 💅 — while the alternate pathname gets set to the previous current pathname, if there even was one.
When we're talking about the file read/write flavors of the read and write commands: if there's no current pathname at all, then the current pathname gets set to the filename argument. Easy.
Every other case? The alternate pathname gets set to the filename argument. That's the whole rule, periodt ✨

Okay so concrete vibes, because examples are literally everything: :edit foo and :recover foo, when they succeed, set the current pathname, and if there was a previous current pathname hanging around, they set the alternate pathname too. Meanwhile :write, !command, and :edit set neither the current nor the alternate pathnames — they're giving nothing and they're proud of it 🙈. Now if :edit foo were to fail for some reason, then the alternate pathname would get set instead. And the read and write commands set the alternate pathname to their file argument, unless the current pathname isn't set, in which case they set the current pathname to their file arguments. Oh and fun fact: the alternate pathname was not historically set by the :source command. POSIX.1‐2008 requires conformance to historical practice here. Any implementation adding commands that take filenames as arguments is encouraged to set the alternate pathname as described right here 👑

Historically, ex and vi read the .exrc file in the $HOME directory twice if the editor was executed in the $HOME directory. POSIX.1‐2008 prohibits this behavior. Not today, glitch 🚫

Historically, the 4 BSD ex and vi read the $HOME and local .exrc files if they were owned by the real ID of the user, or the sourceany option was set, regardless of any other considerations. This was a security problem 😭 because it's totally possible to put normal UNIX system commands inside a .exrc file. POSIX.1‐2008 does not specify the sourceany option, and historical implementations are encouraged to delete it. Bye bestie 👋

The .exrc files must be owned by the real ID of the user, and not writable by anyone other than the owner. The appropriate privileges exception is intended to permit users to acquire special privileges but still keep using the .exrc files in their home directories 🏠

System V Release 3.2 and later vi implementations added the [no]exrc option. The behavior is that local .exrc files are read-only if the exrc option is set. The default for the exrc option was off, so by default, local .exrc files were not read. The problem this was meant to solve? System V permitted users to give away files, so there is no possible ownership or writeability test to ensure the file is safe 💀 This is still a security problem on systems where users can give away files, but there's nothing additional that POSIX.1‐2008 can do about it. The implementation-defined exception is intended to permit groups to have local .exrc files that are shared by users, by creating pseudo-users to own the shared files.

POSIX.1‐2008 does not mention system-wide ex and vi start-up files. While they exist in several implementations of ex and vi, they are not present in any implementations considered historical practice by POSIX.1‐2008. Implementations that do have such files should use them only if they are owned by the real user ID or an appropriate user (for example, root on UNIX systems) and if they are not writable by any user other than their owner. System-wide start-up files should be read before the EXINIT variable, $HOME/.exrc, or local .exrc files are evaluated. Order matters, bestie 🎀

Historically, any ex command could be entered in the EXINIT variable or the .exrc file, although ones requiring that the edit buffer already contain lines of text generally caused historical implementations of the editor to drop core 💀 POSIX.1‐2008 requires that any ex command be permitted in the EXINIT variable and .exrc files, for simplicity of specification and consistency, although many of them will obviously fail under many circumstances. It's giving "we allow it, we just can't promise it'll work" ✨

The initialization of the contents of the edit buffer uses the phrase "the effect shall be" with regard to various ex commands. The intent of this phrase is that edit buffer contents loaded during the initialization phase not be lost; that is, loading the edit buffer should fail if the .exrc file read in the contents of a file and did not subsequently write the edit buffer. An additional intent of this phrase is to specify that the initial current line and column is set as specified for the individual ex commands. Very demure, very mindful 📝

Historically, the -t option behaved as if the tag search were a +command; that is, it was executed from the last line of the file specified by the tag. This resulted in the search failing if the pattern was a forward search pattern and the wrapscan edit option was not set. POSIX.1‐2008 does not permit this behavior, requiring that the search for the tag pattern be performed on the entire file, and, if not found, that the current line be set to a more reasonable location in the file. We love a glow-up 🔥

Historically, the empty edit buffer presented for editing when a file was not specified by the user was unnamed. This is permitted by POSIX.1‐2008; however, implementations are encouraged to provide users a temporary filename for this buffer because it permits them the use of ex commands that use the current pathname during temporary edit sessions. Naming your things is self-care 💖

Historically, the file specified using the -t option was not part of the current argument list. This practice is permitted by POSIX.1‐2008; however, implementations are encouraged to include its name in the current argument list for consistency. Consistency is the moment 🦋

Historically, the -c command was generally not executed until a file that already exists was edited. POSIX.1‐2008 requires conformance to this historical practice. Commands that could cause the -c command to be executed include the ex commands edit, next, recover, rewind, and tag, and the vi commands <control>‐^ and <control>‐]. Historically, reading a file into an edit buffer did not cause the -c command to be executed (even though it might set the current pathname), with the exception that it did cause the -c command to be executed if: the editor was in ex mode, the edit buffer had no current pathname, the edit buffer was empty, and no read commands had yet been attempted. For consistency and simplicity of specification, POSIX.1‐2008 does not permit this behavior. So many asterisks, so little time 😭

Historically, the -r option was the same as a normal edit session if there was no recovery information available for the file. This allowed users to enter:

vi -r *.c

and recover whatever files were recoverable. In some implementations, recovery was attempted only on the first file named, and the file was not entered into the argument list; in others, recovery was attempted for each file named. In addition, some historical implementations ignored -r if -t was specified or did not support command line file arguments with the -t option. For consistency and simplicity of specification, POSIX.1‐2008 disallows these special cases, and requires that recovery be attempted the first time each file is edited. Chaotic behavior → ✨clarity✨

Historically, vi initialized the ` and ' marks, but ex did not. This meant that if the first command in ex mode was visual or if an ex command was executed first (for example, vi +10 file), vi was entered without the marks being initialized. Because the standard developers believed the marks to be generally useful, and for consistency and simplicity of specification, POSIX.1‐2008 requires that they always be initialized if in open or visual mode, or if in ex mode and the edit buffer is not empty. Not initializing it in ex mode if the edit buffer is empty is historical practice; however, it has always been possible to set (and use) marks in empty edit buffers in open and visual mode edit sessions. Marks said "I'm always invited now" 💅

🌸 Addressing 🌸

Historically, ex and vi accepted the additional addressing forms '\/' and '\?'. They were equivalent to "//" and "??", respectively. They are not required by POSIX.1‐2008, mostly because nobody can remember whether they ever did anything different historically 😭💀

Historically, ex and vi permitted an address of zero for several commands, and permitted the % address in empty files for others. For consistency, POSIX.1‐2008 requires support for the former in the few commands where it makes sense, and disallows it otherwise. In addition, because POSIX.1‐2008 requires that % be logically equivalent to "1,$", it is also supported where it makes sense and disallowed otherwise.

Historically, the % address could not be followed by further addresses. For consistency and simplicity of specification, POSIX.1‐2008 requires that additional addresses be supported. Let % breathe 🦋

All of the following 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.
3 ---- 2 — Line one (note the intermediate negative address 👀).
1 2 3 — Line six.

Any number of addresses can be provided to commands taking addresses; for example, "1,2,3,4,5p" prints lines 4 and 5, because two is the greatest valid number of addresses accepted by the print command. This, in combination with the <semicolon> delimiter, permits users to create commands based on ordered patterns in the file. For example, the command 3;/foo/;+2print will display the first line after line 3 that contains the pattern foo, plus the next two lines. Note that the address 3; must be evaluated before being discarded because the search origin for the /foo/ command depends on this. Lowkey galaxy-brain behavior 🧠✨

Historically, values could be added to addresses by including them after one or more <blank> characters; for example, 3 - 5p wrote the seventh line of the file, and /foo/ 5 was the same as /foo/+5. However, only absolute values could be added; for example, 5 /foo/ was an error. POSIX.1‐2008 requires conformance to historical practice. Address offsets are separately specified from addresses because they could historically be provided to visual mode search commands.

Historically, any missing addresses defaulted to the current line. This was true for leading and trailing <comma>-delimited addresses, and for trailing <semicolon>-delimited addresses. For consistency, POSIX.1‐2008 requires it for leading <semicolon> addresses as well. Default behavior, but make it uniform 🎀

Historically, ex and vi accepted the '^' character as both an address and as a flag offset for commands. In both cases it was identical to the '-' character. POSIX.1‐2008 does not require or prohibit this behavior. Schrödinger's caret, bestie 🙈

okay so lowkey the whole vibe of this section is "the standard said 'do it like the old days, bestie, but consistent'." Let me walk you through it 💖

Historically, those glow-up extras for basic regular expressions could be used in addressing — think '~', '\<', and '\>'. POSIX.1‐2008 says: conformance to historical practice, periodt. Meaning regular expression usage has to be consistent, and those regex enhancements have to be supported everywhere regular expressions get used. No picking and choosing, babe.

🌸 Command Line Parsing in ex 🌸

Historical ex command parsing was even more complex than what's described here — like, genuinely chaotic. POSIX.1‐2008 requires only the subset of command parsing that the standard developers believed was documented and that users could reasonably be expected to use in a portable fashion, and that was historically consistent between implementations. (The discarded functionality is, and I quote, obscure, at best.) Historical implementations will need changes to comply with POSIX.1‐2008 — but users aren't expected to notice any of them, bestie, you're safe 🫶.

Most of the complexity in ex parsing is there to handle three special termination cases:

The !, global, v, and the filter versions of the read and write commands are delimited by <newline> characters (they can contain <vertical-line> characters that are usually shell pipes).
The ex, edit, next, and visual in open and visual mode commands all take ex commands, optionally containing <vertical-line> characters, as their first arguments.
The s command takes a regular expression as its first argument, and uses the delimiting characters to delimit the command.

Historically, <vertical-line> characters in the +command argument of the ex, edit, next, vi, and visual commands, and in the pattern and replacement parts of the s command, did not delimit the command. And in the filter cases for read and write, plus the !, global, and v commands, they didn't delimit the command at all. For example, these commands are all valid:

:edit +25 | s/abc/ABC/ file.c
:s/ | /PIPE/
:read !spell % | columnate
:global/pattern/p | l
:s/a/b/ | s/c/d | set

Historically, empty or <blank> filled lines in .exrc files and sourced files (as well as EXINIT variables and ex command scripts) were treated as default commands — that is, print commands. POSIX.1‐2008 specifically requires that they be ignored when encountered in .exrc and sourced files, to eliminate a common source of new-user error. We love a bug fix for the girlies 🙈

Historically, ex commands with multiple adjacent (or <blank>-separated) vertical lines were handled oddly when executed from ex mode. For example, the command ||| <carriage-return>, when the cursor was on line 1, displayed lines 2, 3, and 5 of the file 💀. On top of that, the command | would only display the line after the next line, instead of the next two lines. The former worked more logically when executed from vi mode, and displayed lines 2, 3, and 4. POSIX.1‐2008 requires the vi behavior — that is, a single default command and line number increment for each command separator, and trailing <newline> characters after <vertical-line> separators are discarded. iconic behavior, honestly.

Historically, ex permitted a single extra <colon> as a leading command character; for example, :g/pattern/:p was a valid command. POSIX.1‐2008 generalizes this to require that any number of leading <colon> characters be stripped. slay.

Historically, any prefix of the delete command could be followed — without intervening <blank> characters — by a flag character, because in the command d p, p is interpreted as the buffer p. POSIX.1‐2008 requires conformance to historical practice. no cap.

Historically, the k command could be followed by the mark name without intervening <blank> characters. POSIX.1‐2008 requires conformance to historical practice.

Historically, the s command could be immediately followed by flag and option characters; for example, s/e/E/|s|sgc3p was a valid command. However, flag characters could not stand alone; for example, the commands sp and s l would fail, while the command sgp and s gl would succeed. (Obviously, the '#' flag character was used as a delimiter character if it followed the command.) Another issue: option characters had to precede flag characters even when the command was fully specified; for example, the command s/e/E/pg would fail, while the command s/e/E/gp would succeed. POSIX.1‐2008 requires conformance to historical practice. It's giving order matters, bestie.

Historically, the first command name that had a prefix matching the input from the user was the executed command; for example, ve, ver, and vers all executed the version command. Commands were in a specific order, however, so that a matched append, not abbreviate. POSIX.1‐2008 requires conformance to historical practice. The restriction on command search order for implementations with extensions is to avoid the addition of commands such that the historical prefixes would fail to work portably.

Historical implementations of ex and vi did not correctly handle multiple ex commands, separated by <vertical-line> characters, that entered or exited visual mode or the editor. Because implementations of vi exist that do not exhibit this failure mode, POSIX.1‐2008 does not permit it. periodt.

The requirement that alphabetic command names consist of all following alphabetic characters up to the next non-alphabetic character means that alphabetic command names must be separated from their arguments by one or more non-alphabetic characters — normally a <blank> or '!' character — except as specified for the exceptions, the delete, k, and s commands. 💅

Historically, the repeated execution of the ex default print commands (<control>‐D, eof, <newline>, <carriage-return>) erased any prompting character and displayed the next lines without scrolling the terminal — that is, immediately below any previously displayed lines. This provided a cleaner presentation of the lines in the file for the user. POSIX.1‐2008 does not require this behavior because it may be impossible in some situations; however, implementations are strongly encouraged to provide this semantic if possible. 🎀

Historically, it was possible to change files in the middle of a command, and have the rest of the command executed in the new file. For example:

:edit +25 file.c | s/abc/ABC/ | 1

was a valid command, and the substitution was attempted in the newly edited file. POSIX.1‐2008 requires conformance to historical practice. The following commands are examples that exercise the ex parser:

echo 'foo | bar' > file1; echo 'foo/bar' > file2;
vi
:edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\//SLASH/ | wq

Historically, there was no protection in editor implementations to avoid ex global, v, @, or * commands changing edit buffers during execution of their associated commands. Because this would almost invariably result in catastrophic failure of the editor, and implementations exist that do exhibit these problems, POSIX.1‐2008 requires that changing the edit buffer during a global or v command, or during a @ or * command for which there will be more than a single execution, be an error. 💀 Implementations supporting multiple edit buffers simultaneously are strongly encouraged to apply the same semantics to switching between buffers as well. Like, please, bestie, protect us.

The ex command quoting required by POSIX.1‐2008 is a superset of the quoting in historical implementations of the editor. For example, it was not historically possible to escape a <blank> in a filename; for example, :edit foo\\\ bar would report that too many filenames had been entered for the edit command, and there was no method of escaping a <blank> in the first argument of an edit, ex, next, or visual command at all. POSIX.1‐2008 extends historical practice, requiring that quoting behavior be made consistent across all ex commands — except for the map, unmap, abbreviate, and unabbreviate commands, which historically used <control>‐V instead of <backslash> characters for quoting. For those four commands, POSIX.1‐2008 requires conformance to historical practice.

Backslash quoting in ex is non-intuitive. <backslash>-escapes are ignored unless they escape a special character; for example, when performing file argument expansion, the string "\\%" is equivalent to '\%', not "\<current pathname>". This can be confusing for users because <backslash> is usually one of the characters that causes shell expansion to be performed, and therefore shell quoting rules must be taken into consideration. Generally, quoting characters are only considered if they escape a special character, and a quoting character must be provided for each layer of parsing for which the character is special. As another example, only a single <backslash> is necessary for the '\l' sequence in substitute replacement patterns, because the character 'l' is not special to any parsing layer above it. iykyk 🧚

<control>‐V quoting in ex is slightly different from backslash quoting. In the four commands where <control>‐V quoting applies (abbreviate, unabbreviate, map, and unmap), any character may be escaped by a <control>‐V — whether it would have a special meaning or not. POSIX.1‐2008 requires conformance to historical practice.

Historical implementations of the editor did not require delimiters within character classes to be escaped; for example, the command :s/[/]// on the string "xxx/yyy" would delete the '/' from the string. POSIX.1‐2008 disallows this historical practice, for consistency and because it places a large burden on implementations by requiring that knowledge of regular expressions be built into the editor parser.

Historically, quoting <newline> characters in ex commands was handled inconsistently. In most cases, the <newline> character always terminated the command, regardless of any preceding escape character, because <backslash> characters did not escape <newline> characters for most ex commands. However, some ex commands (for example, s, map, and abbreviation) permitted <newline> characters to be escaped — although in the case of map and abbreviation, <control>‐V characters escaped them instead of <backslash> characters. This was true not only in the command line, but also in .exrc and sourced files. For example, the command:

map = foo<control-V><newline>bar

Okay so like, it would succeed, but ngl it was sometimes a whole struggle to get the <control>‐V and the inserted <newline> to actually pass through to the ex parser. 😩 For consistency and simplicity of specification, POSIX.1‐2008 requires that it be possible to escape <newline> characters in ex commands at all times, using <backslash> characters for most ex commands, and using <control>‐V characters for the map and abbreviation commands. For example, the command print<newline>list is required to be parsed as the single command print<newline>list. While this differs from historical practice, the POSIX.1‐2008 developers believed it unlikely that any script or user depended on the historical behavior. 💁‍♀️

Historically, an error in a command specified using the -c option did not cause the rest of the -c commands to be discarded. POSIX.1‐2008 disallows this for consistency with mapped keys, the @, global, source, and v commands, the EXINIT environment variable, and the .exrc files. 🚫

✨ Input Editing in ex ✨

One of the common uses of the historical ex editor is over slow network connections. Editors that run in canonical mode can require far less traffic to and from, and far less processing on, the host machine, as well as more easily supporting block-mode terminals. For these reasons, POSIX.1‐2008 requires that ex be implemented using canonical mode input processing, as was done historically. 🐢💨

POSIX.1‐2008 does not require the historical 4 BSD input editing characters word erase'' or literal next''. For this reason, it is unspecified how they are handled by ex, although they must have the required effect. Implementations that resolve them after the line has been ended using a <newline> or <control>‐M character, and implementations that rely on the underlying system terminal support for this processing, are both conforming. Implementations are strongly urged to use the underlying system functionality, if at all possible, for compatibility with other system text input interfaces. 🖥️

Historically, when the eof character was used to decrement the autoindent level, the cursor moved to display the new end of the autoindent characters, but did not move the cursor to a new line, nor did it erase the <control>‐D character from the line. POSIX.1‐2008 does not specify that the cursor remain on the same line or that the rest of the line is erased; however, implementations are strongly encouraged to provide the best possible user interface; that is, the cursor should remain on the same line, and any <control>‐D character on the line should be erased. ✨

POSIX.1‐2008 does not require the historical 4 BSD input editing character ``reprint'', traditionally <control>‐R, which redisplayed the current input from the user. For this reason, and because the functionality cannot be implemented after the line has been terminated by the user, POSIX.1‐2008 makes no requirements about this functionality. Implementations are strongly urged to make this historical functionality available, if possible. 🔄

Historically, <control>‐Q did not perform a literal next function in ex, as it did in vi. POSIX.1‐2008 requires conformance to historical practice to avoid breaking historical ex scripts and .exrc files. 📜

✨ eof ✨

Whether the eof character immediately modifies the autoindent characters in the prompt is left unspecified so that implementations can conform in the presence of systems that do not support this functionality. Implementations are encouraged to modify the line and redisplay it immediately, if possible. 💫

The specification of the handling of the eof character differs from historical practice only in that eof characters are not discarded if they follow normal characters in the text input. Historically, they were always discarded. 🗑️

✨ Command Descriptions in ex ✨

Historically, several commands (for example, global, v, visual, s, write, wq, yank, !, <, >, &, and ~) were executable in empty files (that is, the default address(es) were 0), or permitted explicit addresses of 0 (for example, 0 was a valid address, or 0,0 was a valid range). Addresses of 0, or command execution in an empty file, make sense only for commands that add new text to the edit buffer or write commands (because users may wish to write empty files). POSIX.1‐2008 requires this behavior for such commands and disallows it otherwise, for consistency and simplicity of specification. 📝

A count to an ex command has been historically corrected to be no greater than the last line in a file; for example, in a five-line file, the command 1,6print would fail, but the command 1print300 would succeed. POSIX.1‐2008 requires conformance to historical practice. 🔢

Historically, the use of flags in ex commands could be obscure. General historical practice was as described by POSIX.1‐2008, but there were some special cases. For instance, the list, number, and print commands ignored trailing address offsets; for example, 3p +++# would display line 3, and 3 would be the current line after the execution of the command. The open and visual commands ignored both the trailing offsets and the trailing flags. Also, flags specified to the open and visual commands interacted badly with the list edit option, and setting and then unsetting it during the open/visual session would cause vi to stop displaying lines in the specified format. For consistency and simplicity of specification, POSIX.1‐2008 does not permit any of these exceptions to the general rule. 🚫

POSIX.1‐2008 uses the word copy in several places when discussing buffers. This is not intended to imply implementation. 📋

Historically, ex users could not specify numeric buffers because of the ambiguity this would cause; for example, in the command 3 delete 2, it is unclear whether 2 is a buffer name or a count. POSIX.1‐2008 requires conformance to historical practice by default, but does not preclude extensions. 🔢

Historically, the contents of the unnamed buffer were frequently discarded after commands that did not explicitly affect it; for example, when using the edit command to switch files. For consistency and simplicity of specification, POSIX.1‐2008 does not permit this behavior. 🗑️

The ex utility did not historically have access to the numeric buffers, and, furthermore, deleting lines in ex did not modify their contents. For example, if, after doing a delete in vi, the user switched to ex, did another delete, and then switched back to vi, the contents of the numeric buffers would not have changed. POSIX.1‐2008 requires conformance to historical practice. Numeric buffers are described in the ex utility in order to confine the description of buffers to a single location in POSIX.1‐2008. 🔄

The metacharacters that trigger shell expansion in file arguments match historical practice, as does the method for doing shell expansion. Implementations wishing to provide users with the flexibility to alter the set of metacharacters are encouraged to provide a shellmeta string edit option. 🐚

Historically, ex commands executed from vi refreshed the screen when it did not strictly need to do so; for example, :!date > /dev/null does not require a screen refresh because the output of the UNIX date command requires only a single line of the screen. POSIX.1‐2008 requires that the screen be refreshed if it has been overwritten, but makes no requirements as to how an implementation should make that determination. Implementations may prompt and refresh the screen regardless. 🖥️

✨ Abbreviate ✨

Historical practice was that characters that were entered as part of an abbreviation replacement were subject to map expansions, the showmatch edit option, further abbreviation expansions, and so on; that is, they were logically pushed onto the terminal input queue, and were not a simple replacement. POSIX.1‐2008 requires conformance to historical practice. Historical practice was that whenever a non-word character (that had not been escaped by a <control>‐V) was entered after a word character, vi would check for abbreviations. The check was based on the type of the character entered before the word character of the word/non-word pair that triggered the check. The word character of the word/non-word pair that triggered the check and all characters entered before the trigger pair that were of that type were included in the check, with the exception of <blank> characters, which always delimited the abbreviation. 🔍

This means that, for the abbreviation to work, the lhs must end with a word character, there can be no transitions from word to non-word characters (or vice versa) other than between the last and next-to-last characters in the lhs, and there can be no <blank> characters in the lhs. In addition, because of the historical quoting rules, it was impossible to enter a literal <control>‐V in the lhs. POSIX.1‐2008 requires conformance to historical practice. Historical implementations did not inform users when abbreviations that could never be used were entered; implementations are strongly encouraged to do so. 💬

For example, the following abbreviations will work:

:ab (p  REPLACE
:ab p   REPLACE
:ab ((p REPLACE

The following abbreviations will not work:

:ab (   REPLACE
:ab (pp REPLACE

Historical practice is that words on the vi colon command line were subject to abbreviation expansion, including the arguments to the abbrev (and more interestingly) the unabbrev command. Because there are implementations that do not do abbreviation expansion for the first argument to those commands, this is permitted, but not required, by POSIX.1‐2008. However, the following sequence:

:ab foo bar
:ab foo baz

resulted in the addition of an abbreviation of "baz" for the string "bar" in historical ex/vi, and the sequence:

:ab foo1 bar
:ab foo2 bar
:unabbreviate foo2

deleted the abbreviation "foo1", not "foo2". These behaviors are not permitted by POSIX.1‐2008 because they clearly violate the expectations of the user. 😤

It was historical practice that <control>‐V, not <backslash>, characters be interpreted as escaping subsequent characters in the abbreviate command. POSIX.1‐2008 requires conformance to historical practice; however, it should be noted that an abbreviation containing a <blank> will never work. 🚫

✨ Append ✨

Historically, any text following a <vertical-line> command separator after an append, change, or insert command became part of the insert text. For example, in the command:

:g/pattern/append|stuff1

a line containing the text "stuff1" would be appended to each line matching pattern. It was also historically valid to enter:

:append|stuff1
stuff2
.

…and the text on the ex command line would get appended right along with the text you inserted after it. Okay so here's the tea: there was an historical bug where you had to type two terminating lines (two . lines, bestie, TWO) to get out of text input mode in that situation. POSIX.1-2008 says yeah, match historical practice, but it flat-out disallows that whole "needing multiple terminating lines" nonsense. 💅

🌈 Change 🌈

Peep the RATIONALE for the append command for the deets on this one. Historical practice for where the cursor lands after the change command when you input no text is exactly what POSIX.1-2008 describes. However — one System V implementation is known to have been modified so the cursor sits on the first address specified, and not on the line before the first address. POSIX.1-2008 disallows that modification, for consistency. no cap. 🚫

Historically, the change command did not support buffer arguments, even though some implementations allow you to specify an optional buffer. This behavior is neither required nor disallowed by POSIX.1-2008. 🙃

🗂️ Change Directory 🗂️

A common extension in ex implementations is using the elements of a cdpath edit option as prefix directories for path arguments to chdir that are relative pathnames and that don't have . or ".." as their first component. Elements in the cdpath edit option are <colon>-separated. The initial value of the cdpath edit option is the value of the shell CDPATH environment variable. This feature was NOT included in POSIX.1-2008 because it doesn't exist in any of the implementations considered historical practice. it's giving ✨exclusive✨

📋 Copy 📋

Historical implementations of ex let you copy to lines inside of the specified range — for real, :2,5copy3 was a valid command. POSIX.1-2008 requires conformance to historical practice. 🫶

:2,5copy3

🗑️ Delete 🗑️

POSIX.1-2008 requires support for the historical parsing of a delete command followed by flags, with no intervening <blank> characters. Like, for example:

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

1delep  As for 1dp.

1d      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.

✏️ Edit ✏️

Historically, any ex command could be entered as a +command argument to the edit command, although some of them (for example, insert and append) were known to confuse historical implementations. For consistency and simplicity of specification, POSIX.1-2008 requires that any command be supported as an argument to the edit command. 💪

Historically, the command argument was executed with the current line set to the last line of the file, regardless of whether the edit command was executed from visual mode or not. POSIX.1-2008 requires conformance to historical practice.

Historically, the +command specified to the edit and next commands was delimited by the first <blank>, and there was no way to quote them. For consistency, POSIX.1-2008 requires that the usual ex backslash quoting be provided. 🎀

Historically, specifying the +command argument to the edit command required a filename to be specified as well — for example, :edit +100 would always fail. For consistency and simplicity of specification, POSIX.1-2008 does not permit this usage to fail for that reason. slay.

Historically, only the cursor position of the last file edited was remembered by the editor. POSIX.1-2008 requires that this be supported; however, implementations are permitted to remember and restore the cursor position for any file previously edited. 👑

📁 File 📁

Historical versions of the ex editor file command displayed a current line and number of lines in the edit buffer of 0 when the file was empty, while the vi <control>-G command displayed a current line and number of lines in the edit buffer of 1 in the same situation. POSIX.1-2008 does not permit this discrepancy — instead it requires that a message be displayed indicating that the file is empty. consistency queen 💅

🌍 Global 🌍

The two-pass operation of the global and v commands is not intended to imply implementation, only the required result of the operation. iykyk.

The current line and column are set as specified for the individual ex commands. This requirement is cumulative — that is, the current line and column must track across all the commands executed by the global or v commands. tracking, bestie 🦋

➕ Insert ➕

See the RATIONALE for the append command. (yes, again, go read it 🙈)

Historically, insert could not be used with an address of zero — that is, not when the edit buffer was empty. POSIX.1-2008 requires that this command behave consistently with the append command. ✨

🔗 Join 🔗

The action of the join command in relation to the special characters is only defined for the POSIX locale because the correct amount of white space after a period varies — in Japanese none is required, in French only a single space, and so on. 🌸

📜 List 📜

The historical output of the list command was potentially ambiguous. The standard developers believed correcting this to be more important than adhering to historical practice, and POSIX.1-2008 requires unambiguous output. periodt. 💅

🗺️ Map 🗺️

Historically, command mode maps only applied to command names — for example, if the character 'x' was mapped to 'y', the command fx searched for the 'x' character, not the 'y' character. POSIX.1-2008 requires this behavior. Historically, entering <control>-V as the first character of a vi command was an error. Several implementations have extended the semantics of vi such that <control>-V means that the subsequent command character is not mapped. This is permitted, but not required, by POSIX.1-2008. Regardless, using <control>-V to escape the second or later character in a sequence of characters that might match a map command, or any character in text input mode, is historical practice, and stops the entered keys from matching a map. POSIX.1-2008 requires conformance to historical practice.

Historical implementations permitted digits to be used as a map command lhs, but then ignored the map. POSIX.1-2008 requires that the mapped digits not be ignored. 😤

The historical implementation of the map command did not permit map commands that were more than a single character in length if the first character was printable. This behavior is permitted, but not required, by POSIX.1-2008.

Historically, mapped characters were remapped unless the remap edit option was not set, or the prefix of the mapped characters matched the mapping characters — for example, in the map:

:map ab abcd

the characters "ab" were used as is and were not remapped, but the characters "cd" were mapped if appropriate. This can cause infinite loops in the vi mapping mechanisms. POSIX.1-2008 requires conformance to historical practice, and that such loops be interruptible. 😭

Text input maps had the same problems with expanding the lhs for the ex map! and unmap! command as did the ex abbreviate and unabbreviate commands. See the RATIONALE for the ex abbreviate command. POSIX.1-2008 requires similar modification of some historical practice for the map and unmap commands, as described for the abbreviate and unabbreviate commands.

Historically, maps that were subsets of other maps behaved differently depending on the order in which they were defined. For example:

:map! ab     short
:map! abc    long

would always translate the characters "ab" to "short", regardless of how fast the characters "abc" were entered. If the entry order was reversed:

:map! abc    long
:map! ab     short

the characters "ab" would cause the editor to pause, waiting for the completing 'c' character, and the characters might never be mapped to "short". For consistency and simplicity of specification, POSIX.1-2008 requires that the shortest match be used at all times. 🙌

The length of time the editor spends waiting for the characters to complete the lhs is unspecified because the timing capabilities of systems are often inexact and variable, and it may depend on other factors such as the speed of the connection. The time should be long enough for the user to be able to complete the sequence, but not long enough for the user to have to wait. Some implementations of vi have added a keytime option, which permits users to set the number of 0,1 seconds the editor waits for the completing characters. Because mapped terminal function and cursor keys tend to start with an <ESC> character, and <ESC> is the key ending vi text input mode, maps starting with <ESC> characters are generally exempted from this timeout period, or, at least, timed out differently. ⏳

📍 Mark 📍

Historically, users were able to set the previous context marks explicitly. In addition, the ex commands '' and '` and the vi commands '', , ' , and ` `` all referred to the same mark. In addition, the previous context marks were not set if the command, with which the address setting the mark was associated, failed. POSIX.1-2008 requires conformance to historical practice. Historically, if marked lines were deleted, the mark was also deleted, but would reappear if the change was undone. POSIX.1-2008 requires conformance to historical practice. 🦋

The description of the special events that set the ` and ' marks matches historical practice. For example, historically the command /a/,/b/ did not set the ` and ' marks, but the command /a/,/b/delete did. 👑

⏭️ Next ⏭️

Historically, any ex command could be entered as a +command argument to the next command, although some (for example, insert and append) were known to confuse historical implementations. POSIX.1-2008 requires that any command be permitted and that it behave as specified. The next command can accept more than one file, so usage such as:

next `ls [abc] `

is valid; it need not be valid for the edit or read commands, for example, because they expect only one filename. 💅

Historically, the next command behaved differently from the :rewind command in that it ignored the force flag if the autowrite flag was set. For consistency, POSIX.1-2008 does not permit this behavior.

Historically, the next command positioned the cursor as if the file had never been edited before, regardless. POSIX.1-2008 does not permit this behavior, for consistency with the edit command.

Implementations wanting to provide a counterpart to the next command that edited the previous file have used the command prev[ious], which takes no file argument. POSIX.1-2008 does not require this command. 🙈

🚪 Open 🚪

Historically, the open command would fail if the open edit option was not set. POSIX.1-2008 does not mention the open edit option and does not require this behavior. Some historical implementations do not permit entering open mode from open or visual mode, only from ex mode. For consistency, POSIX.1-2008 does not permit this behavior. ✨

Historically, entering open mode from the command line — that's vi +open — gave you anomalous behaviors 💀 like the ex file and set commands and the vi command <control>-G just… not working. For consistency, POSIX.1-2008 does not permit this behavior, bestie.

Also historically, the open command only let you use '/' as the search pattern delimiter. For consistency, POSIX.1-2008 requires that the search delimiters used by the s, global, and v commands be accepted as well. We love consistency 🫶.

✨ Preserve ✨

The preserve command does not historically cause the file to be considered unmodified for the purposes of future commands that may exit the editor. POSIX.1-2008 requires conformance to historical practice, periodt.

Historical documentation claimed mail was not sent to the user when preserve was executed — but historical implementations did send mail in this case 🙈. POSIX.1-2008 requires conformance to the historical implementations. The docs were out here lying, the code was telling the truth.

🎀 Print 🎀

The writing of NUL by the print command is not specified as a special case because the standard developers did not want to require ex to support NUL characters. Historically, characters were displayed using the ARPA standard mappings, which are as follows:

Printable characters are left alone.
Control characters less than \177 are represented as '^' followed by the character offset from the '@' character in the ASCII map; for example, \007 is represented as '^G'.
\177 is represented as '^' followed by '?'.

The display of characters having their eighth bit set was less standard. Existing implementations use hex (0x00), octal (\000), and a meta-bit display. (That last one displayed bytes that had their eighth bit set as the two characters "M-" followed by the seven-bit display as described above.) The meta-bit one probably has the best claim to historical practice because it was used for the -v option of 4 BSD and 4 BSD-derived versions of the cat utility since 1980. 👑

No specific display format is required by POSIX.1-2008.

Explicit dependence on the ASCII character set has been avoided where possible — hence the use of the phrase an "implementation-defined multi-character sequence" for the display of non-printable characters, in preference to the historical usage of, like, "^I" for the <tab>. Implementations are encouraged to conform to historical practice in the absence of any strong reason to diverge.

Historically, all ex commands beginning with the letter 'p' could be entered using capitalized versions of the commands; for example, P[rint], Pre[serve], and Pu[t] were all valid command names. POSIX.1-2008 permits, but does not require, this historical practice because capital forms of the commands are used by some implementations for other purposes.

🦋 Put 🦋

Historically, an ex put command, executed from open or visual mode, was the same as the open or visual mode P command if the buffer was named and was cut in character mode, and the same as the p command if the buffer was named and cut in line mode. If the unnamed buffer was the source of the text, the entire line from which the text was taken was usually put, and the buffer was handled as if in line mode — but it was possible to get extremely anomalous behavior 😭. On top of that, using the Q command to switch into ex mode and then doing a put often resulted in errors too, like appending text that was unrelated to the (supposed) contents of the buffer. For consistency and simplicity of specification, POSIX.1-2008 does not permit these behaviors. All ex put commands are required to operate in line mode, and the contents of the buffers are not altered by changing the mode of the editor. Clean. Simple. Iconic.

🌸 Read 🌸

Historically, an ex read command executed from open or visual mode, executed in an empty file, left an empty line as the first line of the file. For consistency and simplicity of specification, POSIX.1-2008 does not permit this behavior. And historically, a read in open or visual mode from a program left the cursor at the last line read in, not the first. For consistency, POSIX.1-2008 does not permit this behavior either.

Historical implementations of ex were unable to undo read commands that read from the output of a program. For consistency, POSIX.1-2008 does not permit this behavior.

Historically, the ex and vi message after a successful read or write command specified characters, not bytes. POSIX.1-2008 requires that the number of bytes be displayed, not the number of characters, because it may be difficult in multi-byte implementations to determine the number of characters read. Implementations are encouraged to clarify the message displayed to the user.

Historically, reads were not permitted on files other than type regular, except that FIFO files could be read (probably only because they did not exist when ex and vi were originally written 💀). Because the historical ex evaluated read! and read ! equivalently, there can be no optional way to force the read. POSIX.1-2008 permits, but does not require, this behavior.

🧚 Recover 🧚

Some historical implementations of the editor let users recover the edit buffer contents from a previous edit session, and then exit without saving those contents (or explicitly discarding them). The intent of POSIX.1-2008 in requiring that the edit buffer be treated as already modified is to prevent this user error. It's giving protective bestie energy, honestly.

💜 Rewind 💜

Historical implementations supported the rewind command when the user was editing the first file in the list — that is, the file that the rewind command would edit. POSIX.1-2008 requires conformance to historical practice.

🍓 Substitute 🍓

Historically, ex accepted an r option to the s command. The effect of the r option was to use the last regular expression used in any command as the pattern, the same as the ~ command. The r option is not required by POSIX.1-2008. And historically, the c and g options were toggled — for example, the command :s/abc/def/ was the same as s/abc/def/ccccgggg. For simplicity of specification, POSIX.1-2008 does not permit this behavior.

The tilde command is often used to replace the last search RE. For example, in the sequence:

s/red/blue/
/green
~

the ~ command is equivalent to:

s/green/blue/

Historically, ex accepted all of the following forms:

s/abc/def/
s/abc/def
s/abc/
s/abc

POSIX.1-2008 requires conformance to this historical practice.

The s command presumes that the '^' character only occupies a single column in the display. Much of the ex and vi specification presumes that the <space> only occupies a single column in the display. There are no known character sets for which this is not true. We love a low-stakes assumption ✨.

Historically, the final column position for the substitute commands was based on previous column movements; a search for a pattern followed by a substitution would leave the column position unchanged, while a 0 command followed by a substitution would change the column position to the first non-<blank>. For consistency and simplicity of specification, POSIX.1-2008 requires that the final column position always be set to the first non-<blank>.

🌈 Set 🌈

Historical implementations redisplayed all of the options for each occurrence of the all keyword. POSIX.1-2008 permits, but does not require, this behavior.

👑 Tag 👑

No requirement is made as to where ex and vi shall look for the file referenced by the tag entry. Historical practice has been to look for the path found in the tags file, based on the current directory. A useful extension found in some implementations is to look based on the directory containing the tags file that held the entry, as well. No requirement is made as to which reference for the tag in the tags file is used. This is deliberate, in order to permit extensions such as multiple entries in a tags file for a tag.

Because users often specify many different tags files, some of which need not be relevant or exist at any particular time, POSIX.1-2008 requires that error messages about problem tags files be displayed only if the requested tag is not found, and then, only once for each time that the tag edit option is changed.

The requirement that the current edit buffer be unmodified is only necessary if the file indicated by the tag entry is not the same as the current file (as defined by the current pathname). Historically, the file would be reloaded if the filename had changed, as well as if the filename was different from the current pathname. For consistency and simplicity of specification, POSIX.1-2008 does not permit this behavior, requiring that the name be the only factor in the decision.

Historically, vi only searched for tags in the current file from the current cursor to the end of the file, and therefore, if the wrapscan option was not set, tags occurring before the current cursor were not found. POSIX.1-2008 considers this a bug, and implementations are required to search for the first occurrence in the file, regardless. 💅

🙈 Undo 🙈

The undo description deliberately uses the word modified. The undo command is not intended to undo commands that replace the contents of the edit buffer, such as edit, next, tag, or recover.

Cursor positioning after the undo command was inconsistent in the historical vi, sometimes attempting to restore the original cursor position (global, undo, and v commands), and sometimes, in the presence of maps, placing the cursor on the last line added or changed instead of the first. POSIX.1-2008 requires a simplified behavior for consistency and simplicity of specification.

⭐ Version ⭐

The version command cannot be exactly specified since there is no widely-accepted definition of what the version information should contain. Implementations are encouraged to do something reasonably intelligent.

💖 Write 💖

Historically, the ex and vi message after a successful read or write command specified characters, not bytes. POSIX.1-2008 requires that the number of bytes be displayed, not the number of characters because it may be difficult in multi-byte implementations to determine the number of characters written. Implementations are encouraged to clarify the message displayed to the user.

Implementation-defined tests are permitted so that implementations can make additional checks; for example, for locks or file modification times.

Historically, attempting to append to a nonexistent file caused an error. It has been left unspecified in POSIX.1-2008 to permit implementations to let the write succeed, so that the append semantics are similar to those of the historical csh.

Historical vi let you write out empty edit buffers, bestie. The way it got around dealing with "empty" files was to literally always have a line in the edit buffer no matter what, so it wrote them out as files containing a single, empty line. POSIX.1‐2008 does not permit this behavior. 💀

Historically, ex restored standard output and standard error back to whatever they were when ex was invoked, before writes to programs even happened. That could mess with your terminal config AND be a whole security issue for some terminals. POSIX.1‐2008 does not permit this, and instead requires that the program output get captured and displayed as if by the ex print command. ✨

Adjust Window 🪟

Historically, the line count was set to the value of the scroll option if the type character was end-of-file. But ngl this feature was broken on most historical implementations ages ago, and it's not documented anywhere. So POSIX.1‐2008 is resolutely silent. 🤐

Historically, the z command was <blank>-sensitive, and z + and z - did different things than z+ and z- because the type couldn't be told apart from a flag. (The commands z . and z = were historically invalid.) POSIX.1‐2008 requires conformance to this historical practice.

Historically, the z command was <blank>-sensitive in another way too: the count couldn't be <blank>-delimited, so like, the commands z= 5 and z- 5 were also invalid. But since the count isn't ambiguous with respect to either the type character or the flags, this is not permitted by POSIX.1‐2008. 🙅‍♀️

Escape 🏃‍♀️

Historically, ex filter commands only read the standard output of the commands, letting standard error show up on the terminal like normal. The vi utility though? It read both standard output and standard error. POSIX.1‐2008 requires the latter behavior for both ex and vi, for consistency's sake. periodt. 💅

Shift Left and Shift Right ⬅️➡️

Historically, you could add shift characters to crank up the effect of the command; for example, <<< outdented (or >>> indented) the lines 3 levels of indentation instead of the default 1. POSIX.1‐2008 requires conformance to historical practice. slay. 🔥

`<control>`‐D 🎛️

Historically, the <control>‐D command erased the prompt, giving the user an unbroken presentation of lines from the edit buffer. This is not required by POSIX.1‐2008; implementations are encouraged to provide it if possible tho. Historically, the <control>‐D command took a count and then ignored it. POSIX.1‐2008 does not permit this behavior. 🙈

Write Line Number 🔢

Historically, the ex = command, when run in ex mode in an empty edit buffer, reported 0, and from open or visual mode, reported 1. For consistency and simplicity of specification, POSIX.1‐2008 does not permit this behavior.

Execute ⚡

Historically, ex did not correctly handle the inclusion of text input commands (that is, append, insert, and change) in executed buffers. POSIX.1‐2008 does not permit this exclusion, for consistency.

Historically, the logical contents of the buffer being executed did not change if the buffer itself were modified by the commands being executed; that is, buffer execution didn't support self-modifying code. POSIX.1‐2008 requires conformance to historical practice.

Historically, the @ command took a range of lines, and the @ buffer was executed once per line, with the current line ('.') set to each specified line. POSIX.1‐2008 requires conformance to historical practice.

Some historical implementations did not notice if errors happened during buffer execution. And this, combined with being able to specify a range of lines for the ex @ command, made it trivial to cause them to drop core. POSIX.1‐2008 requires that implementations stop buffer execution if any error occurs, if the specified line doesn't exist, or if the contents of the edit buffer itself are replaced (for example, the buffer executes the ex :edit command). no cap, that's the fix. 🫶

Regular Expressions in ex 🔍

Historical practice is that the characters in the replacement part of the last s command—that is, those matched by entering a '~' in the regular expression—were not further expanded by the regular expression engine. So if the characters contained the string "a.," they would match 'a' followed by ".," and not 'a' followed by any character. POSIX.1‐2008 requires conformance to historical practice. 💖

Edit Options in ex 🎀

The following paragraphs describe the historical behavior of some edit options that were not, for whatever reason, included in POSIX.1‐2008. Implementations are strongly encouraged to only use these names if the functionality described here is fully supported.

extended — the extended edit option has been used in some implementations of vi to provide extended regular expressions instead of basic regular expressions. This option was omitted from POSIX.1‐2008 because it is not widespread historical practice. 🌸
flash — the flash edit option historically caused the screen to flash instead of beeping on error. This option was omitted from POSIX.1‐2008 because it is not found in some historical implementations.
hardtabs — the hardtabs edit option historically defined the number of columns between hardware tab settings. This option was omitted from POSIX.1‐2008 because it was believed to no longer be generally useful. 🦋
modeline — the modeline (sometimes named modelines) edit option historically caused ex or vi to read the five first and last lines of the file for editor commands. This option is a security problem, and vendors are strongly encouraged to delete it from historical implementations. 😭
open — the open edit option historically disallowed the ex open and visual commands. This edit option was omitted because these commands are required by POSIX.1‐2008.
optimize — the optimize edit option historically expedited text throughput by setting the terminal to not do automatic <carriage-return> characters when printing more than one logical line of output. This option was omitted from POSIX.1‐2008 because it was intended for terminals without addressable cursors, which are rarely, if ever, still used. 💀
ruler — the ruler edit option has been used in some implementations of vi to present a current row/column ruler for the user. This option was omitted from POSIX.1‐2008 because it is not widespread historical practice.
sourceany — the sourceany edit option historically caused ex or vi to source start-up files that were owned by users other than the user running the editor. This option is a security problem, and vendors are strongly encouraged to remove it from their implementations. 🚨
timeout — the timeout edit option historically enabled the (now standard) feature of only waiting for a short period before returning keys that could be part of a macro. This feature was omitted from POSIX.1‐2008 because its behavior is now standard, it is not widely useful, and it was rarely documented.
verbose — the verbose edit option has been used in some implementations of vi to cause vi to output error messages for common errors; for example, attempting to move the cursor past the beginning or end of the line instead of only alerting the screen. (The historical vi only alerted the terminal and presented no message for such errors. The historical editor option terse did not select when to present error messages, it only made existing error messages more or less verbose.) This option was omitted from POSIX.1‐2008 because it is not widespread historical practice; however, implementors are encouraged to use it if they wish to provide error messages for naive users. 🫶
wraplen — the wraplen edit option has been used in some implementations of vi to specify an automatic margin measured from the left margin instead of from the right margin. This is useful when multiple screen sizes are being used to edit a single file. This option was omitted from POSIX.1‐2008 because it is not widespread historical practice; however, implementors are encouraged to use it if they add this functionality. ✨

autoindent, ai 🧚

Historically, the command 0a did not do any autoindentation, regardless of the current indentation of line 1. POSIX.1‐2008 requires that any indentation present in line 1 be used.

autoprint, ap 🖨️

Historically, the autoprint edit option was not completely consistent or based solely on modifications to the edit buffer. The exceptions were the read command (when reading from a file, but not from a filter), the append, change, insert, global, and v commands, all of which were not affected by autoprint, and the tag command, which was affected by autoprint. POSIX.1‐2008 requires conformance to historical practice.

Historically, the autoprint option only applied to the last of multiple commands entered using <vertical-line> delimiters; for example, delete <newline> was affected by autoprint, but delete|version <newline> was not. POSIX.1‐2008 requires conformance to historical practice. 💅

autowrite, aw ✍️

Appending the '!' character to the ex next command to avoid performing an automatic write was not supported in historical implementations. POSIX.1‐2008 requires that the behavior match the other ex commands, for consistency. 💖

ignorecase, ic 🔠

Historical implementations of case-insensitive matching (the ignorecase edit option) led to counter-intuitive situations when uppercase characters were used in range expressions. Historically, the process was as follows:

Take a line of text from the edit buffer.
Convert uppercase to lowercase in text line.
Convert uppercase to lowercase in regular expressions, except in character class specifications.
Match regular expressions against text.

This would mean that, with ignorecase in effect, the text:

The cat sat on the mat

would be matched by

/^the/

but not by:

/^[A-Z]he/

For consistency with other commands implementing regular expressions, POSIX.1‐2008 does not permit this behavior. 😭

paragraphs, para — okay so back in the day the ISO POSIX‐2:1993 standard was like "eh, we'll leave the default paragraphs and sections edit options implementation-defined," and their reasoning was that those options were historically built for the UNIX system troff text formatter, and a "portable user" might be out here using the {, }, [[, ]], (, and ) commands in open or visual mode and have the cursor just… stop in the weirdest places 😭. POSIX.1‐2008 said nope, we're specifying their values in the POSIX locale, because the whole grouping thing is so unusual (they literally only work when grouped into two characters at a time) that they can't be used for general-purpose movement anyway, periodt.

readonly — implementations are encouraged to give the user the best possible info about the read-only status of the file, with one lil exception: they should not consider the current special privileges of the process. It's basically a safety net for you, bestie 💖, because you have to force the overwrite of read-only files, even when you're running with extra privileges. The readonly edit option spec mostly matches historical practice, with one difference: historical implementations didn't notice that the user had set the readonly edit option in cases where the file was already marked read-only for some reason, and would therefore reinitialize the readonly edit option the next time the contents of the edit buffer were replaced. POSIX.1‐2008 says absolutely not to that behavior 🚫.

report — the rule that lines copied to a buffer act differently from deleted lines? That's historical practice, fr fr. Like, if the report edit option is set to 3, deleting 3 lines will cause a report to be written, but 4 lines must be copied before a report is written. The requirement that the ex global, v, open, undo, and visual commands present reports based on the total number of lines added or deleted during the command execution, and that commands executed by the global and v commands not present reports, is also historical practice. POSIX.1‐2008 extends historical practice by requiring that buffer execution be treated similarly. Why? Two-fold, bestie:

Historically, only the report by the last command executed from the buffer would be seen by the user, since each new report would overwrite the last one 🙈.
The standard developers believed buffer execution had more in common with global and v commands than it did with other ex commands, and should behave similarly — for consistency and simplicity of specification ✨.

showmatch, sm — the length of time the cursor spends on the matching character is unspecified, because the timing capabilities of systems are often inexact and variable (systems are flaky, we know 💀). The time should be long enough for the user to notice, but not long enough for the user to become annoyed. Some implementations of vi have added a matchtime option that lets users set the number of 0,1 second intervals the cursor pauses on the matching character.

showmode — the showmode option has been used in some historical implementations of ex and vi to display the current editing mode when in open or visual mode. The editing modes have generally included "command" and "input", and sometimes other modes such as "replace" and "change". The string was usually displayed on the bottom line of the screen at the far right-hand corner. On top of that, a preceding '*' character often denoted whether the contents of the edit buffer had been modified. That latter display has sometimes been part of the showmode option, and sometimes based on another option. This option was not available in the 4 BSD historical implementation of vi, but it was viewed as generally useful — especially for novice users — and it is required by POSIX.1‐2008 👑.

The smd shorthand for the showmode option was not present in all historical implementations of the editor. POSIX.1‐2008 requires it, for consistency.

Not all historical implementations of the editor displayed a mode string for command mode, differentiating command mode from text input mode by the absence of a mode string. POSIX.1‐2008 permits this behavior for consistency with historical practice, but implementations are encouraged to provide a display string for both modes 🫶.

slowopen — historically, the slowopen option was automatically set if the terminal baud rate was less than 1200 baud, or if the baud rate was 1200 baud and the redraw option was not set. The slowopen option had two effects:

First, when inserting characters in the middle of a line, characters after the cursor would not be pushed ahead, but would appear to be overwritten.
Second, when creating a new line of text, lines after the current line would not be scrolled down, but would appear to be overwritten.

In both cases, ending text input mode would cause the screen to be refreshed to match the actual contents of the edit buffer. And finally, terminals that were sufficiently intelligent caused the editor to ignore the slowopen option entirely. POSIX.1‐2008 permits most historical behavior, extending historical practice to require slowopen behaviors if the edit option is set by the user.

tags — the default path for tags files is left unspecified, since implementations may have their own tags implementations that don't correspond to the historical ones. The default tags option value should probably at least include the file ./tags 🌸.

term — historical implementations of ex and vi ignored changes to the term edit option after the initial terminal information was loaded. POSIX.1‐2008 permits that; however, implementations are encouraged to let the user modify their terminal type at any time ✨.

terse — historically, the terse edit option optionally provided a shorter, less descriptive error message, for some error messages. POSIX.1‐2008 permits this, but does not require it. Historically, most common visual mode errors (for example, trying to move the cursor past the end of a line) did not result in an error message, but simply alerted the terminal. Implementations wishing to provide messages for novice users are urged to do so based on the edit option verbose, and not terse — noted 📝.

window — in historical implementations, the default for the window edit option was based on the baud rate, like this:

If the baud rate was less than 1200, the edit option w300 set the window value; for example, the line:

set w300=12

would set the window option to 12 if the baud rate was less than 1200.

If the baud rate was equal to 1200, the edit option w1200 set the window value.
If the baud rate was greater than 1200, the edit option w9600 set the window value.

The w300, w1200, and w9600 options do not appear in POSIX.1‐2008 because of their dependence on specific baud rates 💀.

In historical implementations, the size of the window displayed by various commands was related to, but not necessarily the same as, the window edit option. For example, the size of the window was set by the ex command visual 10, but it did not change the value of the window edit option. However, changing the value of the window edit option did change the number of lines that were displayed when the screen was repainted. POSIX.1‐2008 does not permit this behavior, in the interests of consistency and simplicity of specification, and requires that all commands that change the number of lines that are displayed do it by setting the value of the window edit option. Consistency slay 💅.

wrapmargin, wm — historically, the wrapmargin option did not affect maps inserting characters that also had associated counts; for example:

:map K 5aABC DEF

Unfortunately, there are widely used maps that depend on this behavior 😭. For consistency and simplicity of specification, POSIX.1‐2008 does not permit this behavior.

Historically, wrapmargin was calculated using the column display width of all characters on the screen. For example, an implementation using "^I" to represent <tab> characters when the list edit option was set, where '^' and 'I' each took up a single column on the screen, would calculate the wrapmargin based on a value of 2 for each <tab>. The number edit option similarly changed the effective length of the line as well. POSIX.1‐2008 requires conformance to historical practice.

Earlier versions of this standard allowed for implementations with bytes other than eight bits, but this has been modified in this version 🦋.

🔮 FUTURE DIRECTIONS 🔮

None. That's it. Nothing. The future is empty, bestie 💀✨.

👀 SEE ALSO 👀

Section 2.9.1.1, Command Search and Execution
ctags
ed
sed
sh
stty
vi

The Base Definitions volume of POSIX.1‐2017:

Table 5-1, Escape Sequences and Associated Actions
Chapter 8, Environment Variables
Section 9.3, Basic Regular Expressions
Section 12.2, Utility Syntax Guidelines

The System Interfaces volume of POSIX.1‐2017:

access()

📜 COPYRIGHT 📜

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

and that's a wrap on the whole entire page, bestie 🎀✨ you made it to the very end, which is genuinely iconic behavior 👑

this one's an IEEE/The Open Group situation, dated 2017, and it lives under the name EX(1POSIX) — go forth and ex responsibly, mwah 💖🦋🌸

📦 where this page comes from

debian bookworm: manpages-posix 2017a-2 · Other
debian trixie: manpages-posix 2017a-2 · Other
ubuntu jammy: manpages-posix 2017a-2 · Other
ubuntu noble: manpages-posix 2017a-2 · Other
ubuntu resolute: manpages-posix 2017a-2build1 · Other
ubuntu stonking: manpages-posix 2017a-2.1 · Other
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms

EX(1POSIX)

💖 ex(1POSIX) — POSIX Programmer's Manual 💖

🌸 PROLOG 🌸

✨ NAME ✨

🦋 SYNOPSIS 🦋

💜 DESCRIPTION 💜

💅 OPTIONS 💅

🌈 OPERANDS 🌈

🍓 STDIN 🍓

🧚 INPUT FILES 🧚

💖 ENVIRONMENT VARIABLES 💖

✨ ASYNCHRONOUS EVENTS ✨

📬 STDOUT 📬

🚨 STDERR 🚨

📁 OUTPUT FILES 📁

🌈 EXTENDED DESCRIPTION 🌈

🧚 Initialization in ex and vi 🧚

🔥 alternate and current pathnames 🔥

🎀 current line 🎀

🌈 current column 🌈

💅 set to non-<blank> 💅

🌈 Addressing in ex 🌈

🧚 Command Line Parsing in ex 🧚

🌈 Input Editing in ex 🌈

🌸 Scroll 🌸

🌈 <newline> 🌈

💅 <backslash> 💅

✨ <control>‐V ✨

🎀 <control>‐W 🎀

👑 Command Descriptions in ex 👑

🌸 Abbreviate 🌸

✨ Append ✨

🦋 Arguments 🦋

💜 Change 💜

🌈 Change Directory 🌈

🍓 Copy 🍓

💀 Delete 💀

🧚 Edit 🧚

👑 File 👑

🔥 Global 🔥

🌸 Insert 🌸

🌈 Join 🌈

✨ List ✨

💖 Map 💖

🦋 Mark 🦋

✨ Move ✨

🦋 Next 🦋

💅 Number 💅

🌈 Open 🌈

🎀 Preserve 🎀

💜 Print 💜

🍓 Put 🍓

👑 Quit 👑

🌸 Read 🌸

🧚 Recover 🧚

⭐ Rewind ⭐

✨ Set ✨

🐚 Shell 🐚

📜 Source 📜

🔥 Substitute 🔥

💤 Suspend 💤

🏷️ Tag 🏷️

🚫 Unabbreviate 🚫

↩️ Undo ↩️

🗺️ Unmap 🗺️

👑 Version 👑

🦋 Visual 🦋

💾 Write

🚪 Write and Exit

📋 Yank

🪟 Adjust Window

🏃 Escape

⬅️ Shift Left

🎀 Shift Right 🎀

✨ <control>-D ✨

🌸 Write Line Number 🌸

👑 Execute 👑

🌈 Regular Expressions in ex 🌈

💖 Replacement Strings in ex 💖

🎀 Edit Options in ex 🎀

🌈 Addressing in `ex` 🌈

🧚 Command Line Parsing in `ex` 🧚

🌈 `<newline>` 🌈

💅 `<backslash>` 💅

✨ `<control>‐V` ✨

🎀 `<control>‐W` 🎀

👑 Command Descriptions in `ex` 👑

✨ `<control>-D` ✨

🌈 Regular Expressions in `ex` 🌈

💖 Replacement Strings in `ex` 💖

🎀 Edit Options in `ex` 🎀

⭐ `autoindent`, `ai` ⭐

💅 `autoprint`, `ap` 💅

🌸 `autowrite`, `aw` 🌸

🦋 `beautify`, `bf` 🦋

🎀 `directory`, `dir` 🎀

⭐ `edcompatible`, `ed` ⭐

🔔 `errorbells`, `eb` 🔔

🏠 `exrc` 🏠

🌈 `ignorecase`, `ic` 🌈

✨ `list` ✨

👯 `list`

✨ `magic`

💬 `mesg`

🔢 `number`, `nu`

📝 `paragraphs`, `para`

💬 `prompt`

🔒 `readonly`

🖥️ `redraw`

🗺️ `remap`

📢 `report`

📜 `scroll`, `scr`

📑 `sections`

🐚 `shell`, `sh`

↔️ `shiftwidth`, `sw`

🧲 `showmatch`, `sm`

🏷️ `showmode`

🐌 `slowopen`

📏 `tabstop`, `ts`

🏷️ `taglength`, `tl`

🗂️ `tags`

🖥️ `term`

🤐 `terse`

🚨 `warn`

🪟 `window`

📐 `wrapmargin`, `wm`