diff options
Diffstat (limited to 'man-pages-posix-2013/man1p/ex.1p')
| -rw-r--r-- | man-pages-posix-2013/man1p/ex.1p | 9025 |
1 files changed, 9025 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man1p/ex.1p b/man-pages-posix-2013/man1p/ex.1p new file mode 100644 index 0000000..a3be3e9 --- /dev/null +++ b/man-pages-posix-2013/man1p/ex.1p @@ -0,0 +1,9025 @@ +'\" et +.TH EX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ex +\(em text editor +.SH SYNOPSIS +.LP +.nf +ex \fB[\fR\(mirR\fB] [\fR\(mis|\(miv\fB] [\fR\(mic \fIcommand\fB] [\fR\(mit \fItagstring\fB] [\fR\(miw \fIsize\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR ex +utility is a line-oriented text editor. There are two other modes of +the editor\(emopen and visual\(emin which screen-oriented editing is +available. This is described more fully by the +.IR ex +.BR open +and +.BR visual +commands and in +.IR "\fIvi\fR\^". +.P +If an operand is +.BR '\(mi' , +the results are unspecified. +.P +This section uses the term +.IR "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. +.P +Certain terminals do not have all the capabilities necessary to support +the complete +.IR ex +definition, such as the full-screen editing commands (\c +.IR "visual mode" +or +.IR "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\(hy2008 or +report an error describing the terminal-related deficiency. +.SH OPTIONS +The +.IR ex +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' , +and that +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\ \fIcommand\fR" 10 +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 +.BR \(mic +option. In such implementations, the specified commands shall be +executed in the order specified on the command line. +.IP "\fB\(mir\fP" 10 +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 +.IR ex +.BR preserve +command. +.RS 10 +.P +A +.IR 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 +.BR preserve +command) that will be recovered is unspecified. +.P +If no +.IR file +operands are given and the +.BR \(mit +option is not specified, all other options, the +.IR EXINIT +variable, and any +.BR .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. +.RE +.IP "\fB\(miR\fP" 10 +Set +.BR readonly +edit option. +.IP "\fB\(mis\fP" 10 +Prepare +.IR ex +for batch use by taking the following actions: +.RS 10 +.IP " *" 4 +Suppress writing prompts and informational (but not diagnostic) +messages. +.IP " *" 4 +Ignore the value of +.IR TERM +and any implementation default terminal type and assume the terminal is +a type incapable of supporting open or visual modes; see the +.BR visual +command and the description of +.IR "\fIvi\fR\^". +.IP " *" 4 +Suppress the use of the +.IR EXINIT +environment variable and the reading of any +.BR .exrc +file; see the EXTENDED DESCRIPTION section. +.IP " *" 4 +Suppress autoindentation, ignoring the value of the +.BR autoindent +edit option. +.RE +.IP "\fB\(mit\ \fItagstring\fR" 10 +Edit the file containing the specified +.IR tagstring ; +see +.IR "\fIctags\fR\^". +The tags feature represented by +.BR \(mit +.IR tagstring +and the +.BR tag +command is optional. It shall be provided on any system that also +provides a conforming implementation of +.IR ctags ; +otherwise, the use of +.BR \(mit +produces undefined results. On any system, it shall be an error to +specify more than a single +.BR \(mit +option. +.IP "\fB\(miv\fP" 10 +Begin in visual mode (see +.IR "\fIvi\fR\^"). +.IP "\fB\(miw\ \fIsize\fR" 10 +Set the value of the +.IR window +editor option to +.IR size . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be edited. +.SH 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}. +.P +If the standard input is not a terminal device, it shall be as if the +.BR \(mis +option had been specified. +.P +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. +.SH "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}\(mi1 +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 +.IR ex +implementations. +.P +The +.BR .exrc +files and source files shall be text files consisting of +.IR ex +commands; see the EXTENDED DESCRIPTION section. +.P +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. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ex : +.IP "\fICOLUMNS\fP" 10 +Override the system-selected horizontal screen size. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fIEXINIT\fP" 10 +Determine a list of +.IR ex +commands that are executed on editor start-up. See the EXTENDED +DESCRIPTION section for more details of the initialization phase. +.IP "\fIHOME\fP" 10 +Determine a pathname of a directory that shall be searched for an +editor start-up file named +.BR .exrc ; +see the EXTENDED DESCRIPTION section. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +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. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILINES\fP" 10 +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\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path for the shell command specified in the +.IR ex +editor commands +.BR ! , +.BR shell , +.BR read , +and +.BR write , +and the open and visual mode command +.BR ! ; +see the description of command search and execution in +.IR "Section 2.9.1.1" ", " "Command Search and Execution". +.IP "\fISHELL\fP" 10 +Determine the preferred command line interpreter for use as the default +value of the +.BR shell +edit option. +.IP "\fITERM\fP" 10 +Determine the name of the terminal type. If this variable is unset or +null, an unspecified default terminal type shall be used. +.SH "ASYNCHRONOUS EVENTS" +The following term is used in this and following sections to specify +command and asynchronous event actions: +.IP "\fIcomplete\ write\fP" 10 +.br +A complete write is a write of the entire contents of the edit buffer +to a file of a type other than a terminal device, or the saving of the +edit buffer caused by the user executing the +.IR ex +.BR preserve +command. Writing the contents of the edit buffer to a temporary file +that will be removed when the editor exits shall not be considered a +complete write. +.P +The following actions shall be taken upon receipt of signals: +.IP SIGINT 10 +If the standard input is not a terminal device, +.IR ex +shall not write the file or return to command or text input mode, and +shall exit with a non-zero exit status. +.RS 10 +.P +Otherwise, if executing an open or visual text input mode command, +.IR ex +in receipt of SIGINT shall behave identically to its receipt of the +<ESC> +character. +.P +Otherwise: +.IP " 1." 4 +If executing an +.IR 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. +.IP " 2." 4 +If there is a currently executing command, it shall be aborted and a +message displayed. Unless otherwise specified by the +.IR ex +or +.IR 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. +.RS 4 +.P +If the currently executing command was a motion command, its associated +command shall be discarded. +.RE +.IP " 3." 4 +If in open or visual command mode, the terminal shall be alerted. +.IP " 4." 4 +The editor shall then return to command mode. +.RE +.IP SIGCONT 10 +The screen shall be refreshed if in open or visual mode. +.IP SIGHUP 10 +If the edit buffer has been modified since the last complete write, +.IR ex +shall attempt to save the edit buffer so that it can be recovered later +using the +.BR \(mir +option or the +.IR ex +.BR 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. +.IP SIGTERM 10 +Refer to SIGHUP. +.P +The action taken for all other signals is unspecified. +.SH STDOUT +The standard output shall be used only for writing prompts to the user, +for informational messages, and for writing lines from the file. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output from +.IR ex +shall be text files. +.SH "EXTENDED DESCRIPTION" +Only the +.IR ex +mode of the editor is described in this section. See +.IR "\fIvi\fR\^" +for additional editing capabilities available in +.IR ex . +.P +When an error occurs, +.IR 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 +.BR errorbells +is set, an alert action shall precede the error message. +.P +By default, +.IR ex +shall start in command mode, which shall be indicated by a +.BR : +prompt; see the +.BR prompt +command. Text input mode can be entered by the +.BR append , +.BR insert , +or +.BR change +commands; it can be exited (and command mode re-entered) by typing a +<period> +(\c +.BR '.' ) +alone at the beginning of a line. +.SS "Initialization in ex and vi" +.P +The following symbols are used in this and following sections to +specify locations in the edit buffer: +.IP "\fIalternate\ and\ current\ pathnames\fP" 6 +.br +Two pathnames, named +.IR current +and +.IR alternate , +are maintained by the editor. Any +.IR ex +commands that take filenames as arguments shall set them as follows: +.RS 6 +.IP " 1." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR edit , +.BR ex , +or +.BR recover +commands, or if an +.IR ex +.BR tag +command replaces the contents of the edit buffer. +.RS 4 +.IP " a." 4 +If the command replaces the contents of the edit buffer, the current +pathname shall be set to the +.IR file +argument or the file indicated by the tag, and the alternate pathname +shall be set to the previous value of the current pathname. +.IP " b." 4 +Otherwise, the alternate pathname shall be set to the +.IR file +argument. +.RE +.IP " 2." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR next +command: +.RS 4 +.IP " a." 4 +If the command replaces the contents of the edit buffer, the current +pathname shall be set to the first +.IR file +argument, and the alternate pathname shall be set to the previous +value of the current pathname. +.RE +.IP " 3." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR file +command, the current pathname shall be set to the +.IR file +argument, and the alternate pathname shall be set to the previous +value of the current pathname. +.IP " 4." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR read +and +.BR write +commands (that is, when reading or writing a file, and not to the +program named by the +.BR shell +edit option), or a +.IR file +argument is specified to the +.IR ex +.BR xit +command: +.RS 4 +.IP " a." 4 +If the current pathname has no value, the current pathname shall be +set to the +.IR file +argument. +.IP " b." 4 +Otherwise, the alternate pathname shall be set to the +.IR file +argument. +.RE +.P +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. +.RE +.IP "\fIcurrent\ line\fP" 6 +.br +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 +.IR "current line value" . +When the edit buffer contains no lines, the current line shall be zero; +see +.IR "Addressing in ex". +.IP "\fIcurrent\ column\fP" 6 +.br +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 +.IR "current column" +value. This column is an +.IR 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 +.IR "Command Descriptions in vi". +.IP "\fIset\ to\ non-<blank>\fP" 6 +.br +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-\c +<blank> +of the line. If the line has no non-\c +<blank> +non-\c +<newline> +characters, the current column shall be set to the last display line +column on which is displayed any part of the last non-\c +<newline> +character in the line. If the line is empty, the current column shall +be set to column position 1. +.P +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. +.P +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. +.P +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: +.IP " 1." 4 +If the environment variable +.IR EXINIT +is set, the editor shall execute the +.IR ex +commands contained in that variable. +.IP " 2." 4 +If the +.IR EXINIT +variable is not set, and all of the following are true: +.RS 4 +.IP " a." 4 +The +.IR HOME +environment variable is not null and not empty. +.IP " b." 4 +The file +.BR .exrc +in the directory referred to by the +.IR HOME +environment variable: +.RS 4 +.IP " i." 5 +Exists +.IP ii. 5 +Is owned by the same user ID as the real user ID of the process or the +process has appropriate privileges +.IP iii. 5 +Is not writable by anyone other than the owner +.RE +.P +the editor shall execute the +.IR ex +commands contained in that file. +.RE +.IP " 3." 4 +If and only if all of the following are true: +.RS 4 +.IP " a." 4 +The current directory is not referred to by the +.IR HOME +environment variable. +.IP " b." 4 +A command in the +.IR EXINIT +environment variable or a command in the +.BR .exrc +file in the directory referred to by the +.IR HOME +environment variable sets the editor option +.BR exrc . +.IP " c." 4 +The +.BR .exrc +file in the current directory: +.RS 4 +.IP " i." 5 +Exists +.IP ii. 5 +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 +.IP iii. 5 +Is not writable by anyone other than the owner +.RE +.P +the editor shall attempt to execute the +.IR ex +commands contained in that file. +.RE +.P +Lines in any +.BR .exrc +file that are blank lines shall be ignored. If any +.BR .exrc +file exists, but is not read for ownership or permission reasons, it +shall be an error. +.P +After the +.IR EXINIT +variable and any +.BR .exrc +files are processed, the first file specified by the user shall be +edited, as follows: +.IP " 1." 4 +If the user specified the +.BR \(mit +option, the effect shall be as if the +.IR ex +.BR 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. +.IP " 2." 4 +Otherwise, if the user specified any command line +.IR file +arguments, the effect shall be as if the +.IR ex +.BR edit +command was entered with the first of those arguments as its +.IR file +argument. +.IP " 3." 4 +Otherwise, the effect shall be as if the +.IR ex +.BR edit +command was entered with a nonexistent filename as its +.IR 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. +.P +If the +.BR \(mir +option was specified, the first time a file in the initial argument +list or a file specified by the +.BR \(mit +option is edited, if recovery information has previously been saved +about it, that information shall be recovered and the editor shall +behave as if the contents of the edit buffer have already been +modified. 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. If no recovery information about a file is +available, an informational message to this effect shall be written, +and the edit shall proceed as usual. +.P +If the +.BR \(mic +option was specified, the first time a file that already exists +(including a file that might not exist but for which recovery +information is available, when the +.BR \(mir +option is specified) replaces or initializes the contents of the edit +buffer, the current line shall be set to the last line of the edit +buffer, the current column shall be set to non-\c +<blank>, +and the +.IR ex +commands specified with the +.BR \(mic +option shall be executed. In this case, the current line and current +column shall not be set as described for the command associated with +the replacement or initialization of the edit buffer contents. However, +if the +.BR \(mit +option or a +.BR tag +command is associated with this action, the +.BR \(mic +option commands shall be executed and then the movement to the tag +shall be performed. +.P +The current argument list shall initially be set to the filenames +specified by the user on the command line. If no filenames are +specified by the user, the current argument list shall be empty. If the +.BR \(mit +option was specified, it is unspecified whether any filename resulting +from tag processing shall be prepended to the current argument list. In +the case where the filename is added as a prefix to the current +argument list, the current argument list reference shall be set to that +filename. In the case where the filename is not added as a prefix to +the current argument list, the current argument list reference shall +logically be located before the first of the filenames specified on +the command line (for example, a subsequent +.IR ex +.BR next +command shall edit the first filename from the command line). If the +.BR \(mit +option was not specified, the current argument list reference shall be +to the first of the filenames on the command line. +.SS "Addressing in ex" +.P +Addressing in +.IR ex +relates to the current line and the current column; the address of a +line is its 1-based line number, 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. The current line number is the +address of the current line. In each command description, the effect of +the command on the current line number and the current column is +described. +.P +Addresses are constructed as follows: +.IP " 1." 4 +The character +.BR '.' +(period) shall address the current line. +.IP " 2." 4 +The character +.BR '$' +shall address the last line of the edit buffer. +.IP " 3." 4 +The positive decimal number +.IR n +shall address the +.IR n th +line of the edit buffer. +.IP " 4." 4 +The address +.BR \(dq'x\(dq +refers to the line marked with the mark name character +.BR 'x' , +which shall be a lowercase letter from the portable character set, +the backquote character, or the single-quote character. It shall be an +error if the line that was marked is not currently present in the edit +buffer or the mark has not been set. Lines can be marked with the +.IR ex +.BR mark +or +.BR k +commands, or the +.IR vi +.BR m +command. +.IP " 5." 4 +A regular expression enclosed by +<slash> +characters (\c +.BR '/' ) +shall address the first line found by searching forwards from the line +following the current line toward the end of the edit buffer and +stopping at the first line for which the line excluding the terminating +<newline> +matches the regular expression. As stated in +.IR "Regular Expressions in ex", +an address consisting of a null regular expression delimited by +<slash> +characters (\c +.BR \(dq//\(dq ) +shall address the next line for which the line excluding the +terminating +<newline> +matches the last regular expression encountered. In addition, the second +<slash> +can be omitted at the end of a command line. If the +.BR wrapscan +edit option is set, the search shall wrap around to the beginning of +the edit buffer and continue up to and including the current line, so +that the entire edit buffer is searched. Within the regular expression, +the sequence +.BR \(dq\e/\(dq +shall represent a literal +<slash> +instead of the regular expression delimiter. +.IP " 6." 4 +A regular expression enclosed in +<question-mark> +characters (\c +.BR '?' ) +shall address the first line found by searching backwards from the line +preceding the current line toward the beginning of the edit buffer and +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 (\c +.BR \(dq??\(dq ) +shall address the previous line for which the line excluding the +terminating +<newline> +matches the last regular expression encountered. In addition, the second +<question-mark> +can be omitted at the end of a command line. If the +.BR wrapscan +edit option is set, the search shall wrap around from the beginning of +the edit buffer to the end of the edit buffer and continue up to and +including the current line, so that the entire edit buffer is +searched. Within the regular expression, the sequence +.BR \(dq\e?\(dq +shall represent a literal +<question-mark> +instead of the RE delimiter. +.IP " 7." 4 +A +<plus-sign> +(\c +.BR '\(pl' ) +or a minus-sign (\c +.BR '\(mi' ) +followed by a decimal number shall address the current line plus or +minus the number. A +.BR '\(pl' +or +.BR '\(mi' +not followed by a decimal number shall address the current line plus or +minus 1. +.P +Addresses can be followed by zero or more address offsets, optionally +<blank>-separated. +Address offsets are constructed as follows: +.IP " 1." 4 +A +.BR '\(pl' +or +.BR '\(mi' +immediately followed by a decimal number shall add (subtract) the +indicated number of lines to (from) the address. A +.BR '\(pl' +or +.BR '\(mi' +not followed by a decimal number shall add (subtract) 1 to (from) the +address. +.IP " 2." 4 +A decimal number shall add the indicated number of lines to the +address. +.P +It shall not be an error for an intermediate address value to be less +than zero or greater than the last line in the edit buffer. It shall be +an error for the final address value to be less than zero or greater +than the last line in the edit buffer. +.P +Commands take zero, one, or two addresses; see the descriptions of +.IR 1addr +and +.IR 2addr +in +.IR "Command Descriptions in ex". +If more than the required number of addresses are provided to a command +that requires zero addresses, it shall be an error. Otherwise, if more +than the required number of addresses are provided to a command, the +addresses specified first shall be evaluated and then discarded until +the maximum number of valid addresses remain. +.P +Addresses shall be separated from each other by a +<comma> +(\c +.BR ',' ) +or a +<semicolon> +(\c +.BR ';' ). +If no address is specified before or after a +<comma> +or +<semicolon> +separator, it shall be 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 (\c +.BR '.' ) +shall be set to the first address, and only then will the next address +be calculated. This feature can be used to determine the starting line +for forwards and backwards searches (see rules 5. and 6.). +.P +A +<percent-sign> +(\c +.BR '%' ) +shall be equivalent to entering the two addresses +.BR \(dq1,$\(dq . +.P +Any delimiting +<blank> +characters between addresses, address separators, or address offsets +shall be discarded. +.SS "Command Line Parsing in ex" +.P +The following symbol is used in this and following sections to describe +parsing behavior: +.IP "\fIescape\fP" 10 +If a character is referred to as ``\c +<backslash>-escaped'' +or ``\c +<control>\(hyV-escaped'', +it shall mean that the character acquired or lost a special +meaning by virtue of being preceded, respectively, by a +<backslash> +or +<control>\(hyV +character. Unless otherwise specified, the escaping character shall be +discarded at that time and shall not be further considered for any +purpose. +.P +Command-line parsing shall be done in the following steps. For each +step, characters already evaluated shall be ignored; that is, the +phrase ``leading character'' refers to the next character that has not +yet been evaluated. +.IP " 1." 4 +Leading +<colon> +characters shall be skipped. +.IP " 2." 4 +Leading +<blank> +characters shall be skipped. +.IP " 3." 4 +If the leading character is a double-quote character, the characters up +to and including the next non-\c +<backslash>-escaped +<newline> +shall be discarded, and any subsequent characters shall be parsed as a +separate command. +.IP " 4." 4 +Leading characters that can be interpreted as addresses shall be +evaluated; see +.IR "Addressing in ex". +.IP " 5." 4 +Leading +<blank> +characters shall be skipped. +.IP " 6." 4 +If the next character is a +<vertical-line> +character or a +<newline>: +.RS 4 +.IP " a." 4 +If the next character is a +<newline>: +.RS 4 +.IP " i." 5 +If +.IR ex +is in open or visual mode, the current line shall be set to the last +address specified, if any. +.IP ii. 5 +Otherwise, if the last command was terminated by a +<vertical-line> +character, no action shall be taken; for example, the command +.BR \(dq||<newline>\(dq +shall execute two implied commands, not three. +.IP iii. 5 +Otherwise, step 6.b. shall apply. +.RE +.IP " b." 4 +Otherwise, the implied command shall be the +.BR print +command. The last +.BR # , +.BR p , +and +.BR l +flags specified to any +.IR ex +command shall be remembered and shall apply to this implied command. +Executing the +.IR ex +.BR number , +.BR print , +or +.BR list +command shall set the remembered flags to +.BR # , +nothing, and +.BR l , +respectively, plus any other flags specified for that execution of the +.BR number , +.BR print , +or +.BR list +command. +.RS 4 +.P +If +.IR ex +is not currently performing a +.BR global +or +.BR v +command, and no address or count is specified, the current line shall +be incremented by 1 before the command is executed. If incrementing the +current line would result in an address past the last line in the edit +buffer, the command shall fail, and the increment shall not happen. +.RE +.IP " c." 4 +The +<newline> +or +<vertical-line> +character shall be discarded and any subsequent characters shall be +parsed as a separate command. +.RE +.IP " 7." 4 +The command name shall be comprised of the next character (if the +character is not alphabetic), or the next character and any subsequent +alphabetic characters (if the character is alphabetic), with the +following exceptions: +.RS 4 +.IP " a." 4 +Commands that consist of any prefix of the characters in the command +name +.BR delete , +followed immediately by any of the characters +.BR 'l' , +.BR 'p' , +.BR '\(pl' , +.BR '\(mi' , +or +.BR '#' +shall be interpreted as a +.BR delete +command, followed by a +<blank>, +followed by the characters that were not part of the prefix of the +.BR delete +command. The maximum number of characters shall be matched to the +command name +.BR delete ; +for example, +.BR \(dqdel\(dq +shall not be treated as +.BR \(dqde\(dq +followed by the flag +.BR l . +.IP " b." 4 +Commands that consist of the character +.BR 'k' , +followed by a character that can be used as the name of a mark, shall +be equivalent to the mark command followed by a +<blank>, +followed by the character that followed the +.BR 'k' . +.IP " c." 4 +Commands that consist of the character +.BR 's' , +followed by characters that could be interpreted as valid options to +the +.BR s +command, shall be the equivalent of the +.BR s +command, without any pattern or replacement values, followed by a +<blank>, +followed by the characters after the +.BR 's' . +.RE +.IP " 8." 4 +The command name shall be matched against the possible command names, +and a command name that contains a prefix matching the characters +specified by the user shall be the executed command. In the case of +commands where the characters specified by the user could be ambiguous, +the executed command shall be as follows: +.TS +center tab(!) box; +lB | lB || lB | lB || lB | lB. +a!append!n!next!t!t +c!change!p!print!u!undo +ch!change!pr!print!un!undo +e!edit!r!read!v!v +m!move!re!read!w!write +ma!mark!s!s +.TE +.RS 4 +.P +Implementation extensions with names causing similar ambiguities shall +not be checked for a match until all possible matches for commands +specified by POSIX.1\(hy2008 have been checked. +.RE +.IP " 9." 4 +If the command is a +.BR ! +command, or if the command is a +.BR read +command followed by zero or more +<blank> +characters and a +.BR ! , +or if the command is a +.BR write +command followed by one or more +<blank> +characters and a +.BR ! , +the rest of the command shall include all characters up to a non-\c +<backslash>-escaped +<newline>. +The +<newline> +shall be discarded and any subsequent characters shall be parsed as a +separate +.IR ex +command. +.IP 10. 4 +Otherwise, if the command is an +.BR edit , +.BR ex , +or +.BR next +command, or a +.BR visual +command while in open or visual mode, the next part of the command +shall be parsed as follows: +.RS 4 +.IP " a." 4 +Any +.BR '!' +character immediately following the command shall be skipped and be +part of the command. +.IP " b." 4 +Any leading +<blank> +characters shall be skipped and be part of the command. +.IP " c." 4 +If the next character is a +.BR '\(pl' , +characters up to the first non-\c +<backslash>-escaped +<newline> +or non-\c +<backslash>-escaped +<blank> +shall be skipped and be part of the command. +.IP " d." 4 +The rest of the command shall be determined by the steps specified in +paragraph 12. +.RE +.IP 11. 4 +Otherwise, if the command is a +.BR global , +.BR open , +.BR s , +or +.BR v +command, the next part of the command shall be parsed as follows: +.RS 4 +.IP " a." 4 +Any leading +<blank> +characters shall be skipped and be part of the command. +.IP " b." 4 +If the next character is not an alphanumeric, double-quote, +<newline>, +<backslash>, +or +<vertical-line> +character: +.RS 4 +.IP " i." 5 +The next character shall be used as a command delimiter. +.IP ii. 5 +If the command is a +.BR global , +.BR open , +or +.BR v +command, characters up to the first non-\c +<backslash>-escaped +<newline>, +or first non-\c +<backslash>-escaped +delimiter character, shall be skipped and be part of the command. +.IP iii. 5 +If the command is an +.BR s +command, characters up to the first non-\c +<backslash>-escaped +<newline>, +or second non-\c +<backslash>-escaped +delimiter character, shall be skipped and be part of the command. +.RE +.IP " c." 4 +If the command is a +.BR global +or +.BR v +command, characters up to the first non-\c +<backslash>-escaped +<newline> +shall be skipped and be part of the command. +.IP " d." 4 +Otherwise, the rest of the command shall be determined by the steps +specified in paragraph 12. +.RE +.IP 12. 4 +Otherwise: +.RS 4 +.IP " a." 4 +If the command was a +.BR map , +.BR unmap , +.BR abbreviate , +or +.BR unabbreviate +command, characters up to the first non-\c +<control>\(hyV-escaped +<newline>, +<vertical-line>, +or double-quote character shall be skipped and be part of the command. +.IP " b." 4 +Otherwise, characters up to the first non-\c +<backslash>-escaped +<newline>, +<vertical-line>, +or double-quote character shall be skipped and be part of the command. +.IP " c." 4 +If the command was an +.BR append , +.BR change , +or +.BR insert +command, and the step 12.b. ended at a +<vertical-line> +character, any subsequent characters, up to the next non-\c +<backslash>-escaped +<newline> +shall be used as input text to the command. +.IP " d." 4 +If the command was ended by a double-quote character, all subsequent +characters, up to the next non-\c +<backslash>-escaped +<newline>, +shall be discarded. +.IP " e." 4 +The terminating +<newline> +or +<vertical-line> +character shall be discarded and any subsequent characters shall be +parsed as a separate +.IR ex +command. +.RE +.P +Command arguments shall be parsed as described by the Synopsis and +Description of each individual +.IR ex +command. This parsing shall not be +<blank>-sensitive, +except for the +.BR ! +argument, which must follow the command name without intervening +<blank> +characters, and where it would otherwise be ambiguous. For example, +.IR count +and +.IR flag +arguments need not be +<blank>-separated +because +.BR \(dqd22p\(dq +is not ambiguous, but +.IR file +arguments to the +.IR ex +.BR next +command must be separated by one or more +<blank> +characters. Any +<blank> +in command arguments for the +.BR abbreviate , +.BR unabbreviate , +.BR map , +and +.BR unmap +commands can be +<control>\(hyV-escaped, +in which case the +<blank> +shall not be used as an argument delimiter. Any +<blank> +in the command argument for any other command can be +<backslash>-escaped, +in which case that +<blank> +shall not be used as an argument delimiter. +.P +Within command arguments for the +.BR abbreviate , +.BR unabbreviate , +.BR map , +and +.BR unmap +commands, any character can be +<control>\(hyV-escaped. +All such escaped characters shall be treated literally and shall have +no special meaning. Within command arguments for all other +.IR ex +commands that are not regular expressions or replacement strings, any +character that would otherwise have a special meaning can be +<backslash>-escaped. +Escaped characters shall be treated literally, without special meaning +as shell expansion characters or +.BR '!' , +.BR '%' , +and +.BR '#' +expansion characters. See +.IR "Regular Expressions in ex" +and +.IR "Replacement Strings in ex" +for descriptions of command arguments that are regular expressions or +replacement strings. +.P +Non-\c +<backslash>-escaped +.BR '%' +characters appearing in +.IR file +arguments to any +.IR ex +command shall be replaced by the current pathname; unescaped +.BR '#' +characters shall be replaced by the alternate pathname. It shall be an +error if +.BR '%' +or +.BR '#' +characters appear unescaped in an argument and their corresponding +values are not set. +.P +Non-\c +<backslash>-escaped +.BR '!' +characters in the arguments to either the +.IR ex +.BR ! +command or the open and visual mode +.BR ! +command, or in the arguments to the +.IR ex +.BR read +command, where the first non-\c +<blank> +after the command name is a +.BR '!' +character, or in the arguments to the +.IR ex +.BR write +command where the command name is followed by one or more +<blank> +characters and the first non-\c +<blank> +after the command name is a +.BR '!' +character, shall be replaced with the arguments to the last of those +three commands as they appeared after all unescaped +.BR '%' , +.BR '#' , +and +.BR '!' +characters were replaced. It shall be an error if +.BR '!' +characters appear unescaped in one of these commands and there has been +no previous execution of one of these commands. +.P +If an error occurs during the parsing or execution of an +.IR ex +command: +.IP " *" 4 +An informational message to this effect shall be written. Execution of +the +.IR ex +command shall stop, and the cursor (for example, the current line and +column) shall not be further modified. +.IP " *" 4 +If the +.IR ex +command resulted from a map expansion, all characters from that map +expansion shall be discarded, except as otherwise specified by the +.BR map +command. +.IP " *" 4 +Otherwise, if the +.IR ex +command resulted from the processing of an +.IR EXINIT +environment variable, a +.BR .exrc +file, a +.BR :source +command, a +.BR \(mic +option, or a +.BR + \c +.IR command +specified to an +.IR ex +.BR edit , +.BR ex , +.BR next , +or +.BR visual +command, no further commands from the source of the commands shall be +executed. +.IP " *" 4 +Otherwise, if the +.IR ex +command resulted from the execution of a buffer or a +.BR global +or +.BR v +command, no further commands caused by the execution of the buffer or +the +.BR global +or +.BR v +command shall be executed. +.IP " *" 4 +Otherwise, if the +.IR ex +command was not terminated by a +<newline>, +all characters up to and including the next non-\c +<backslash>-escaped +<newline> +shall be discarded. +.SS "Input Editing in ex" +.P +The following symbol is used in this and the following sections to +specify command actions: +.IP "\fIword\fP" 10 +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. +.P +When accepting input characters from the user, in either +.IR ex +command mode or +.IR ex +text input mode, +.IR ex +shall enable canonical mode input processing, as defined in the System Interfaces volume of POSIX.1\(hy2008. +.br +.P +If in +.IR ex +text input mode: +.IP " 1." 4 +If the +.BR number +edit option is set, +.IR ex +shall prompt for input using the line number that would be assigned to +the line if it is entered, in the format specified for the +.IR ex +.BR number +command. +.IP " 2." 4 +If the +.BR autoindent +edit option is set, +.IR ex +shall prompt for input using +.BR autoindent +characters, as described by the +.BR autoindent +edit option. +.BR autoindent +characters shall follow the line number, if any. +.P +If in +.IR ex +command mode: +.IP " 1." 4 +If the +.BR prompt +edit option is set, input shall be prompted for using a single +.BR ':' +character; otherwise, there shall be no prompt. +.P +The input characters in the following sections shall have the following +effects on the input line. +.SS "Scroll" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +eof +.fi \fR +.P +.RE +.RE +.P +See the description of the +.IR stty +.IR eof +character in +.IR "\fIstty\fR\^". +.P +If in +.IR ex +command mode: +.sp +.RS +If the +.IR eof +character is the first character entered on the line, the line shall be +evaluated as if it contained two characters: a +<control>\(hyD +and a +<newline>. +.P +Otherwise, the +.IR eof +character shall have no special meaning. +.RE +.br +.P +If in +.IR ex +text input mode: +.sp +.RS +If the cursor follows an +.BR autoindent +character, the +.BR 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 +.BR shiftwidth +edit option column boundary, and the user shall be prompted again for +input for the same line. +.P +Otherwise, if the cursor follows a +.BR '0' , +which follows an +.BR autoindent +character, and the +.BR '0' +was the previous text input character, the +.BR '0' +and all +.BR autoindent +characters in the line shall be discarded, and the user shall be +prompted again for input for the same line. +.P +Otherwise, if the cursor follows a +.BR '^' , +which follows an +.BR autoindent +character, and the +.BR '^' +was the previous text input character, the +.BR '^' +and all +.BR autoindent +characters in the line shall be discarded, and the user shall be +prompted again for input for the same line. In addition, the +.BR autoindent +level for the next input line shall be derived from the same line from +which the +.BR autoindent +level for the current input line was derived. +.P +Otherwise, if there are no +.BR autoindent +or text input characters in the line, the +.IR eof +character shall be discarded. +.P +Otherwise, the +.IR eof +character shall have no special meaning. +.RE +.SS "<newline>" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +<newline> +.br +<control>-J +.fi \fR +.P +.RE +.RE +.P +If in +.IR ex +command mode: +.sp +.RS +Cause the command line to be parsed; +<control>\(hyJ +shall be mapped to the +<newline> +for this purpose. +.RE +.br +.P +If in +.IR ex +text input mode: +.sp +.RS +Terminate the current line. If there are no characters other than +.BR autoindent +characters on the line, all characters on the line shall be discarded. +.P +Prompt for text input on a new line after the current line. If the +.BR autoindent +edit option is set, an appropriate number of +.BR autoindent +characters shall be added as a prefix to the line as described by the +.IR ex +.BR autoindent +edit option. +.RE +.SS "<backslash>" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +<backslash> +.fi \fR +.P +.RE +.RE +.P +Allow the entry of a subsequent +<newline> +or +<control>\(hyJ +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. +.SS "<control>\(hyV" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +<control>-V +.fi \fR +.P +.RE +.RE +.P +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>\(hyV +character shall be discarded before the command line is parsed or the +input text becomes part of the edit buffer. +.P +If the ``literal next'' functionality is performed by the underlying +system, it is implementation-defined whether a character other than +<control>\(hyV +performs this function. +.SS "<control>\(hyW" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +<control>-W +.fi \fR +.P +.RE +.RE +.P +Discard the +<control>\(hyW, +and the word previous to it in the input line, including any +<blank> +characters following the word and preceding the +<control>\(hyW. +If the ``word erase'' functionality is performed by the underlying +system, it is implementation-defined whether a character other than +<control>\(hyW +performs this function. +.SS "Command Descriptions in ex" +.P +The following symbols are used in this section to represent command +modifiers. Some of these modifiers can be omitted, in which case the +specified defaults shall be used. +.IP "\fI1addr\fR" 10 +A single line address, given in any of the forms described in +.IR "Addressing in ex"; +the default shall be the current line (\c +.BR '.' ), +unless otherwise specified. +.RS 10 +.P +If the line address is zero, it shall be an error, unless otherwise +specified in the following command descriptions. +.P +If the edit buffer is empty, and the address is specified with a +command other than +.BR = , +.BR append , +.BR insert , +.BR open , +.BR put , +.BR read , +or +.BR visual , +or the address is not zero, it shall be an error. +.RE +.IP "\fI2addr\fP" 10 +Two addresses specifying an inclusive range of lines. If no addresses +are specified, the default for +.IR 2addr +shall be the current line only (\c +.BR \(dq.,.\(dq ), +unless otherwise specified in the following command descriptions. If +one address is specified, +.IR 2addr +shall specify that line only, unless otherwise specified in the +following command descriptions. +.RS 10 +.P +It shall be an error if the first address is greater than the second +address. +.P +If the edit buffer is empty, and the two addresses are specified with a +command other than the +.BR ! , +.BR write , +.BR wq , +or +.BR xit +commands, or either address is not zero, it shall be an error. +.RE +.IP "\fIcount\fP" 10 +A positive decimal number. If +.IR 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 +.IR count \(mi1. +.RS 10 +.P +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. +.RE +.IP "\fIflags\fP" 10 +One or more of the characters +.BR '\(pl' , +.BR '\(mi' , +.BR '#' , +.BR 'p' , +or +.BR 'l' +(ell). The flag characters can be +<blank>-separated, +and in any order or combination. The characters +.BR '#' , +.BR 'p' , +and +.BR 'l' +shall cause lines to be written in the format specified by the +.BR print +command with the specified +.IR flags . +.RS 10 +.P +The lines to be written are as follows: +.IP " 1." 4 +All edit buffer lines written during the execution of the +.IR ex +.BR & , +.BR ~ , +.BR list , +.BR number , +.BR open , +.BR print , +.BR s , +.BR visual , +and +.BR z +commands shall be written as specified by +.IR flags . +.IP " 2." 4 +After the completion of an +.IR ex +command with a flag as an argument, the current line shall be written +as specified by +.IR flags , +unless the current line was the last line written by the command. +.P +The characters +.BR '\(pl' +and +.BR '\(mi' +cause the value of the current line after the execution of the +.IR ex +command to be adjusted by the offset address as described in +.IR "Addressing in ex". +This adjustment shall occur before the current line is written as +described in 2. above. +.P +The default for +.IR flags +shall be none. +.RE +.IP "\fIbuffer\fP" 10 +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. +.RS 10 +.P +In +.IR 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 (\c +.BR '\&"' ) +character. +.P +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. +.P +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 +.IR vi +.BR c +or +.BR d +commands, the motion character associated with the +.BR c +or +.BR d +commands specifies that the buffer text shall be in line mode, or the +commands +.BR % , +.BR ` , +.BR / , +.BR ? , +.BR ( , +.BR ) , +.BR N , +.BR n , +.BR { , +or +.BR } +are used to define a region of text for the +.BR c +or +.BR 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. +.P +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 +.IR ex +commands shall be in line mode. The +.IR 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. +.RE +.IP "\fIfile\fP" 10 +Command text used to derive a pathname. The default shall be the +current pathname, as defined previously, in which case, if no current +pathname has yet been established it shall be an error, except where +specifically noted in the individual command descriptions that follow. +If the command text contains any of the characters +.BR '~' , +.BR '{' , +.BR '[' , +.BR '*' , +.BR '?' , +.BR '$' , +.BR '\&"' , +backquote, single-quote, and +<backslash>, +it shall be subjected to the process of ``shell expansions'', as +described below; if more than a single pathname results and the +command expects only one, it shall be an error. +.RS 10 +.P +The process of shell expansions in the editor shall be done as +follows. The +.IR ex +utility shall pass two arguments to the program named by the shell edit +option; the first shall be +.BR \(mic , +and the second shall be the string +.BR \(dqecho\(dq +and the command text as a single argument. The standard output and +standard error of that command shall replace the command text. +.RE +.IP "\fB!\fP" 10 +A character that can be appended to the command name to modify its +operation, as detailed in the individual command descriptions. With the +exception of the +.IR ex +.BR read , +.BR write , +and +.BR ! +commands, the +.BR '!' +character shall only act as a modifier if there are no +<blank> +characters between it and the command name. +.IP "\fIremembered\ search\ direction\fP" 10 +.br +The +.IR vi +commands +.BR N +and +.BR n +begin searching in a forwards or backwards direction in the edit buffer +based on a remembered search direction, which is initially unset, and +is set by the +.IR ex +.BR global , +.BR v , +.BR s , +and +.BR tag +commands, and the +.IR vi +.BR / +and +.BR ? +commands. +.SS "Abbreviate" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ab\fB[\fIbreviate\fB][\fIlhs rhs\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR lhs +and +.IR rhs +are not specified, write the current list of abbreviations and do +nothing more. +.P +Implementations may restrict the set of characters accepted in +.IR lhs +or +.IR rhs , +except that printable characters and +<blank> +characters shall not be restricted. Additional restrictions shall be +implementation-defined. +.P +In both +.IR lhs +and +.IR rhs , +any character may be escaped with a +<control>\(hyV, +in which case the character shall not be used to delimit +.IR lhs +from +.IR rhs , +and the escaping +<control>\(hyV +shall be discarded. +.P +In open and visual text input mode, if a non-word or +<ESC> +character that is not escaped by a +<control>\(hyV +character is entered after a word character, a check shall be made for +a set of characters matching +.IR lhs , +in the text input entered during this command. If it is found, the +effect shall be as if +.IR rhs +was entered instead of +.IR lhs . +.P +The set of characters that are checked is defined as follows: +.IP " 1." 4 +If there are no characters inserted before the word and non-word or +<ESC> +characters that triggered the check, the set of characters shall +consist of the word character. +.IP " 2." 4 +If the character inserted before the word and non-word or +<ESC> +characters that triggered the check is a word character, the set of +characters shall consist of the characters inserted immediately before +the triggering characters that are word characters, plus the triggering +word character. +.IP " 3." 4 +If the character inserted before the word and non-word or +<ESC> +characters that triggered the check is not a word character, the set of +characters shall consist of the characters that were inserted before +the triggering characters that are neither +<blank> +characters nor word characters, plus the triggering word character. +.P +It is unspecified whether the +.IR lhs +argument entered for the +.IR ex +.BR abbreviate +and +.BR unabbreviate +commands is replaced in this fashion. Regardless of whether or not the +replacement occurs, the effect of the command shall be as if the +replacement had not occurred. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Append" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRa\fB[\fRppend\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Enter +.IR ex +text input mode; the input text shall be placed after the specified +line. If line zero is specified, the text shall be placed at the +beginning of the edit buffer. +.P +This command shall be affected by the +.BR number +and +.BR autoindent +edit options; following the command name with +.BR '!' +shall cause the +.BR autoindent +edit option setting to be toggled for the duration of this command +only. +.P +.IR "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 a line of +zero was specified, or zero if the edit buffer is empty. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Arguments" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ar\fB[\fIgs\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the current argument list, with the current argument-list entry, +if any, between +.BR '[' +and +.BR ']' +characters. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Change" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRc\fB[\fRhange\fB][\fR!\fB][\fIcount\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Enter +.IR ex +text input mode; the input text shall replace the specified lines. The +specified lines shall be copied into the unnamed buffer, which shall +become a line mode buffer. +.P +This command shall be affected by the +.BR number +and +.BR autoindent +edit options; following the command name with +.BR '!' +shall cause the +.BR autoindent +edit option setting to be toggled for the duration of this command +only. +.P +.IR "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. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Change Directory" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +chd\fB[\fRir\fB][\fR!\fB][\fIdirectory\fB]\fR +cd\fB[\fR!\fB][\fIdirectory\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Change the current working directory to +.IR directory . +.P +If no +.IR directory +argument is specified, and the +.IR HOME +environment variable is set to a non-null and non-empty value, +.IR directory +shall default to the value named in the +.IR HOME +environment variable. If the +.IR HOME +environment variable is empty or is undefined, the default value of +.IR directory +is implementation-defined. +.P +If no +.BR '!' +is 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 +.BR '/' , +it shall be an error. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Copy" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRco\fB[\fRpy\fB] \fI1addr \fB[\fIflags\fB] +[\fI2addr\fB] \fRt \fI1addr \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Copy the specified lines after the specified destination line; line +zero specifies that the lines shall be placed at the beginning of the +edit buffer. +.P +.IR "Current line" : +Set to the last line copied. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Delete" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRd\fB[\fRelete\fB][\fIbuffer\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Delete the specified lines into a buffer (defaulting to the unnamed +buffer), which shall become a line-mode buffer. +.P +Flags can immediately follow the command name; see +.IR "Command Line Parsing in ex". +.P +.IR "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. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Edit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +e\fB[\fRdit\fB][\fR!\fB][\fR+\fIcommand\fB][\fIfile\fB]\fR +ex\fB[\fR!\fB][\fR+\fIcommand\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error. +.P +If +.IR file +is specified, replace the current contents of the edit buffer with the +current contents of +.IR file , +and set the current pathname to +.IR file . +If +.IR file +is not 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 cannot be accessed, the +edit buffer shall be empty. +.P +The +.BR + \c +.IR command +option shall be +<blank>-delimited; +<blank> +characters within the +.BR + \c +.IR command +can be escaped by preceding them with a +<backslash> +character. The +.BR + \c +.IR command +shall be interpreted as an +.IR ex +command immediately after the contents of the edit buffer have been +replaced and the current line and column have been set. +.P +If the edit buffer is empty: +.P +.IR "Current line" : +Set to 0. +.P +.IR "Current column" : +Set to 1. +.P +Otherwise, if executed while in +.IR ex +command mode or if the +.BR + \c +.IR command +argument is specified: +.P +.IR "Current line" : +Set to the last line of the edit buffer. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.P +Otherwise, if +.IR file +is omitted or results in the current pathname: +.P +.IR "Current line" : +Set to the first line of the edit buffer. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.P +Otherwise, if +.IR file +is the same as the last file edited, the line and column shall be set +as follows; if the file was previously edited, the line and column may +be set as follows: +.P +.IR "Current line" : +Set to the last value held when that file was last edited. If this +value is not a valid line in the new edit buffer, set to the first line +of the edit buffer. +.P +.IR "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 is not a valid column in the new edit +buffer, set to non-\c +<blank>. +.br +.P +Otherwise: +.P +.IR "Current line" : +Set to the first line of the edit buffer. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +f\fB[\fRile\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If a +.IR file +argument is specified, the alternate pathname shall be set to the +current pathname, and the current pathname shall be set to +.IR file . +.P +Write an informational message. If the file has a current pathname, it +shall be included in this message; otherwise, the message shall +indicate that there is no current pathname. If the edit buffer +contains lines, the current line number and the number of lines in the +edit buffer shall be included in this message; otherwise, the message +shall indicate that the edit buffer is empty. If the edit buffer has +been modified since the last complete write, this fact shall be +included in this message. If the +.BR readonly +edit option is set, this fact shall be included in this message. The +message may contain other unspecified information. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Global" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRg\fB[\fRlobal\fB] \fR/\fIpattern\fR/ \fB[\fIcommands\fB] +[\fI2addr\fB] \fRv /\fIpattern\fR/ \fB[\fIcommands\fB]\fR +.fi \fR +.P +.RE +.RE +.P +The optional +.BR '!' +character after the +.BR global +command shall be the same as executing the +.BR v +command. +.P +If +.IR pattern +is empty (for example, +.BR \(dq//\(dq ) +or not specified, the last regular expression used in the editor +command shall be used as the +.IR pattern . +The +.IR pattern +can be delimited by +<slash> +characters (shown in the Synopsis), as well as any non-alphanumeric +or non-\c +<blank> +other than +<backslash>, +<vertical-line>, +<newline>, +or double-quote. +.P +If no lines are specified, the lines shall default to the entire file. +.P +The +.BR global +and +.BR v +commands are logically two-pass operations. First, mark the lines +within the specified lines for which the line excluding the terminating +<newline> +matches (\c +.BR global ) +or does not match (\c +.BR v +or +.BR global! ) +the specified pattern. Second, execute the +.IR ex +commands given by +.IR commands , +with the current line (\c +.BR '.' ) +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 +.IR ex +.BR :edit +command) an error message shall be written and no more commands +resulting from the execution of this command shall be processed. +.P +Multiple +.IR 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>. +.P +If no commands are specified: +.IP " 1." 4 +If in +.IR ex +command mode, it shall be as if the +.BR print +command were specified. +.IP " 2." 4 +Otherwise, no command shall be executed. +.P +For the +.BR append , +.BR change , +and +.BR 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 +.BR open +and +.BR 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 +.IR vi +.BR 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. +.P +The +.BR global , +.BR v , +and +.BR undo +commands cannot be used in +.IR 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. +.P +If the remembered search direction is not set, the +.BR global +and +.BR v +commands shall set it to forward. +.P +The +.BR autoprint +and +.BR autoindent +edit options shall be inhibited for the duration of the +.BR g +or +.BR v +command. +.P +.IR "Current line" : +If no commands executed, set to the last marked line. Otherwise, as +specified for the executed +.IR ex +commands. +.P +.IR "Current column" : +If no commands are executed, set to non-\c +<blank>; +otherwise, as specified for the individual +.IR ex +commands. +.SS "Insert" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRi\fB[\fRnsert\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Enter +.IR 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. +.P +This command shall be affected by the +.BR number +and +.BR autoindent +edit options; following the command name with +.BR '!' +shall cause the +.BR autoindent +edit option setting to be toggled for the duration of this command +only. +.P +.IR "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. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Join" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRj\fB[\fRoin\fB][\fR!\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR count +is specified: +.sp +.RS +If no address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the current line and the current line plus +.IR count +(.\|,\|. + +.IR count ). +.P +If one address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the specified address and the specified address plus +.IR count +(\c +.IR addr ,\c +.IR addr ++ +.IR count ). +.P +If two addresses were specified, the +.BR join +command shall behave as if an additional address, equal to the last +address plus +.IR count +\(mi1 (\c +.IR addr1 ,\c +.IR addr2 ,\c +.IR addr2 ++ +.IR count +\(mi1), was specified. +.P +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. +.RE +.P +If no +.IR count +is specified: +.sp +.RS +If no address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the current line and the next line (.\|,\|. +1). +.P +If one address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the specified address and the next line (\c +.IR addr ,\c +.IR addr ++1). +.RE +.P +Join the text from the specified lines together into a single line, +which shall replace the specified lines. +.P +If a +.BR '!' +character is appended to the command name, the +.BR join +shall be without modification of any line, independent of the current +locale. +.P +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: +.IP " 1." 4 +Discard leading +<space> +characters from the line to be joined. +.IP " 2." 4 +If the line to be joined is now empty, delete it, and skip steps 3 +through 5. +.IP " 3." 4 +If the current line ends in a +<blank>, +or the first character of the line to be joined is a +.BR ')' +character, join the lines without further modification. +.IP " 4." 4 +If the last character of the current line is a +.BR '.' , +join the lines with two +<space> +characters between them. +.IP " 5." 4 +Otherwise, join the lines with a single +<space> +between them. +.P +.IR "Current line" : +Set to the first line specified. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "List" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRl\fB[\fRist\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +command: +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB] \fRl\fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.P +See +.IR "Print". +.SS "Map" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +map\fB[\fR!\fB][\fIlhs rhs\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR lhs +and +.IR rhs +are not specified: +.IP " 1." 4 +If +.BR '!' +is specified, write the current list of text input mode maps. +.IP " 2." 4 +Otherwise, write the current list of command mode maps. +.IP " 3." 4 +Do nothing more. +.P +Implementations may restrict the set of characters accepted in +.IR lhs +or +.IR rhs , +except that printable characters and +<blank> +characters shall not be restricted. Additional restrictions shall be +implementation-defined. In both +.IR lhs +and +.IR rhs , +any character can be escaped with a +<control>\(hyV, +in which case the character shall not be used to delimit +.IR lhs +from +.IR rhs , +and the escaping +<control>\(hyV +shall be discarded. +.P +If the character +.BR '!' +is appended to the +.BR map +command name, the mapping shall be effective during open or visual text +input mode rather than +.BR open +or +.BR visual +command mode. This allows +.IR lhs +to have two different +.BR map +definitions at the same time: one for command mode and one for text +input mode. +.br +.P +For command mode mappings: +.sp +.RS +When the +.IR lhs +is entered as any part of a +.IR 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 +.IR rhs +had been entered. +.P +If any character in the command, other than the first, is escaped using +a +<control>\(hyV +character, that character shall not be part of a match to an +.IR lhs . +.P +It is unspecified whether implementations shall support +.BR map +commands where the +.IR lhs +is more than a single character in length, where the first character of +the +.IR lhs +is printable. +.RE +.P +.sp +.RS +If +.IR lhs +contains more than one character and the first character is +.BR '#' , +followed by a sequence of digits corresponding to a numbered function +key, then when this function key is typed it shall be mapped to +.IR rhs . +Characters other than digits following a +.BR '#' +character also represent the function key named by the characters in +the +.IR lhs +following the +.BR '#' +and may be mapped to +.IR rhs . +It is unspecified how function keys are named or what function keys are +supported. +.RE +.P +For text input mode mappings: +.sp +.RS +When the +.IR lhs +is entered as any part of text entered in open or visual text input +modes, the action shall be as if the corresponding +.IR rhs +had been entered. +.P +If any character in the input text is escaped using a +<control>\(hyV +character, that character shall not be part of a match to an +.IR lhs . +.P +It is unspecified whether the +.IR lhs +text entered for subsequent +.BR map +or +.BR unmap +commands is replaced with the +.IR rhs +text for the purposes of the screen display; regardless of whether or +not the display appears as if the corresponding +.IR rhs +text was entered, the effect of the command shall be as if the +.IR lhs +text was entered. +.RE +.P +If only part of the +.IR 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 +.IR lhs . +.P +The +.IR rhs +characters shall themselves be subject to remapping, unless otherwise +specified by the +.BR remap +edit option, except that if the characters in +.IR lhs +occur as prefix characters in +.IR rhs , +those characters shall not be remapped. +.P +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. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Mark" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRma\fB[\fRrk\fB] \fIcharacter +\fB[\fI1addr\fB] \fRk \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +Implementations shall support +.IR 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. +.P +If executing the +.IR vi +.BR 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. +.P +Otherwise, set the specified mark to the specified line and 1-based +numbered first non-\c +<blank> +non-\c +<newline> +in the line, if any; otherwise, the last non-\c +<newline> +in the line, if any; otherwise, column position 1. +.P +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 +.BR 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. +.P +The marks +.BR ` +and +.BR ' +shall be set as described previously, immediately before the following +events occur in the editor: +.IP " 1." 4 +The use of +.BR '$' +as an +.IR ex +address +.IP " 2." 4 +The use of a positive decimal number as an +.IR ex +address +.IP " 3." 4 +The use of a search command as an +.IR ex +address +.IP " 4." 4 +The use of a mark reference as an +.IR ex +address +.IP " 5." 4 +The use of the following open and visual mode commands: +<control>\(hy], +.BR % , +.BR ( , +.BR ) , +.BR [ , +.BR ] , +.BR { , +.BR } +.IP " 6." 4 +The use of the following open and visual mode commands: +.BR ' , +.BR G , +.BR H , +.BR L , +.BR M , +.BR z +if the current line will change as a result of the command +.IP " 7." 4 +The use of the open and visual mode commands: +.BR / , +.BR ? , +.BR N , +.BR ` , +.BR n +if the current line or column will change as a result of the command +.IP " 8." 4 +The use of the +.IR ex +mode commands: +.BR z , +.BR undo , +.BR global , +.BR v +.P +For rules 1., 2., 3., and 4., the +.BR ` +and +.BR ' +marks shall not be set if the +.IR ex +command is parsed as specified by rule 6.a. in +.IR "Command Line Parsing in ex". +.P +For rules 5., 6., and 7., the +.BR ` +and +.BR ' +marks shall not be set if the commands are used as motion commands in +open and visual mode. +.P +For rules 1., 2., 3., 4., 5., 6., 7., and 8., the +.BR ` +and +.BR ' +marks shall not be set if the command fails. +.P +The +.BR ` +and +.BR ' +marks shall be set as described previously, each time the contents of +the edit buffer are replaced (including the editing of the initial +buffer), if in open or visual mode, or if in +.BR ex +mode and the edit buffer is not empty, before any commands or movements +(including commands or movements specified by the +.BR \(mic +or +.BR \(mit +options or the +.BR + \c +.IR command +argument) are executed on the edit buffer. If in open or visual mode, +the marks shall be set as if executing the +.IR vi +.BR m +command; otherwise, as if executing the +.IR ex +.BR mark +command. +.P +When changing from +.BR ex +mode to open or visual mode, if the +.BR ` +and +.BR ' +marks are not already set, the +.BR ` +and +.BR ' +marks shall be set as described previously. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Move" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRm\fB[\fRove\fB] \fI1addr\fR \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Move the specified lines after the specified destination line. A +destination of line zero specifies that the lines shall be placed at +the beginning of the edit buffer. It shall be an error if the +destination line is within the range of lines to be moved. +.P +.IR "Current line" : +Set to the last of the moved lines. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Next" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +n\fB[\fRext\fB][\fR!\fB][\fR+\fIcommand\fB][\fIfile \fR...\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +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 +.BR autowrite +option. +.br +.P +If one or more files is specified: +.IP " 1." 4 +Set the argument list to the specified filenames. +.IP " 2." 4 +Set the current argument list reference to be the first entry in the +argument list. +.IP " 3." 4 +Set the current pathname to the first filename specified. +.P +Otherwise: +.IP " 1." 4 +It shall be an error if there are no more filenames in the argument +list after the filename currently referenced. +.IP " 2." 4 +Set the current pathname and the current argument list reference to +the filename after the filename currently referenced in the argument +list. +.P +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. +.P +This command shall be affected by the +.BR autowrite +and +.BR writeany +edit options. +.P +The +.BR + \c +.IR command +option shall be +<blank>-delimited; +<blank> +characters can be escaped by preceding them with a +<backslash> +character. The +.BR + \c +.IR command +shall be interpreted as an +.IR ex +command immediately after the contents of the edit buffer have been +replaced and the current line and column have been set. +.P +.IR "Current line" : +Set as described for the +.BR edit +command. +.P +.IR "Current column" : +Set as described for the +.BR edit +command. +.SS "Number" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRnu\fB[\fRmber\fB][\fIcount\fB][\fIflags\fB] +[\fI2addr\fB] \fR#\fB[\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +These commands shall be equivalent to the +.IR ex +command: +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB] \fR#\fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.P +See +.IR "Print". +.SS "Open" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRo\fB[\fRpen\fB]\fR /\fIpattern\fR/ \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +This command need not be supported on block-mode terminals or terminals +with insufficient capabilities. If standard input, standard output, or +standard error are not terminal devices, the results are unspecified. +.P +Enter open mode. +.P +The trailing delimiter can be omitted from +.IR pattern +at the end of the command line. If +.IR pattern +is empty (for example, +.BR \(dq//\(dq ) +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-\c +<blank> +other than +<backslash>, +<vertical-line>, +<newline>, +or +double-quote. +.P +.IR "Current line" : +Set to the specified line. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Preserve" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +pre\fB[\fRserve\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Save the edit buffer in a form that can later be recovered by using the +.BR \(mir +option or by using the +.IR ex +.BR 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 +.IR mailx +utility. The message shall contain the name of the file, the time of +preservation, and an +.IR ex +command that could be used to recover the file. Additional information +may be included in the mail message. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Print" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +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. +.P +Non-printable characters, except for the +<tab>, +shall be written as implementation-defined multi-character sequences. +.P +If the +.BR # +flag is specified or the +.BR number +edit option is set, each line shall be preceded by its line number in +the following format: +.sp +.RS 4 +.nf +\fB +"%6d ", <\fIline number\fR> +.fi \fR +.P +.RE +.P +If the +.BR l +flag is specified or the +.BR list +edit option is set: +.IP " 1." 4 +The characters listed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +shall be written as the corresponding escape sequence. +.IP " 2." 4 +Non-printable characters not in the Base Definitions volume of POSIX.1\(hy2008, +.IR "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). +.IP " 3." 4 +The end of each line shall be marked with a +.BR '$' , +and literal +.BR '$' +characters within the line shall be written with a preceding +<backslash>. +.P +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. +.P +If a line is folded, and the +.BR l +flag is not specified and the +.BR 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. +.P +.IR "Current line" : +Set to the last written line. +.P +.IR "Current column" : +Unchanged if the current line is unchanged; otherwise, set to non-\c +<blank>. +.SS "Put" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRpu\fB[\fRt\fB][\fIbuffer\fB]\fR +.fi \fR +.P +.RE +.RE +.P +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. +.P +.IR "Current line" : +Set to the last line entered into the edit buffer. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Quit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +q\fB[\fRuit\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name: +.IP " 1." 4 +If the edit buffer has been modified since the last complete write, it +shall be an error. +.IP " 2." 4 +If there are filenames in the argument list after the filename +currently referenced, and the last command was not a +.BR quit , +.BR wq , +.BR xit , +or +.BR ZZ +(see +.IR "Exit") +command, it shall be an error. +.P +Otherwise, terminate the editing session. +.SS "Read" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRr\fB[\fRead\fB][\fR!\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.BR '!' +is not the first non-\c +<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 +.IR file +is named, the current pathname shall be the default. If there is no +current pathname, then +.IR file +shall become the current pathname. If there is no current pathname or +.IR file +operand, it shall be an error. Specifying a +.IR file +that is not of type regular shall have unspecified results. +.P +Otherwise, if +.IR file +is preceded by +.BR '!' , +the rest of the line after the +.BR '!' +shall have +.BR '%' , +.BR '#' , +and +.BR '!' +characters expanded as described in +.IR "Command Line Parsing in ex". +.P +The +.IR ex +utility shall then pass two arguments to the program named by the +shell edit option; the first shall be +.BR \(mic +and the second shall be the expanded arguments to the +.BR read +command as a single argument. The standard input of the program shall +be set to the standard input of the +.IR 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. +.P +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. +.P +The special meaning of the +.BR '!' +following the +.BR read +command can be overridden by escaping it with a +<backslash> +character. +.P +.IR "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. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Recover" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +rec\fB[\fRover\fB][\fR!\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error. +.P +If no +.IR file +operand is specified, then the current pathname shall be used. If +there is no current pathname or +.IR file +operand, it shall be an error. +.P +If no recovery information has previously been saved about +.IR file , +the +.BR recover +command shall behave identically to the +.BR edit +command, and an informational message to this effect shall be written. +.P +Otherwise, set the current pathname to +.IR file , +and replace the current contents of the edit buffer with the recovered +contents of +.IR 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. +.P +.IR "Current file" : +Set as described for the +.BR edit +command. +.P +.IR "Current column" : +Set as described for the +.BR edit +command. +.SS "Rewind" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +rew\fB[\fRind\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +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 +.BR autowrite +option. +.P +If the argument list is empty, it shall be an error. +.P +The current argument list reference and the current pathname shall be +set to the first filename in the argument list. +.P +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. +.P +This command shall be affected by the +.BR autowrite +and +.BR writeany +edit options. +.P +.IR "Current line" : +Set as described for the +.BR edit +command. +.P +.IR "Current column" : +Set as described for the +.BR edit +command. +.SS "Set" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +se\fB[\fRt\fB][\fIoption\fB[\fR=\fB[\fIvalue\fB]]\fR ...\fB][\fRno\fIoption\fR ...\fB][\fIoption\fR? ...\fB][\fRall\fB]\fR +.fi \fR +.P +.RE +.RE +.P +When no arguments are specified, write the value of the +.BR term +edit option and those options whose values have been changed from the +default settings; when the argument +.IR all +is specified, write all of the option values. +.P +Giving an option name followed by the character +.BR '?' +shall cause the current value of that option to be written. The +.BR '?' +can be separated from the option name by zero or more +<blank> +characters. The +.BR '?' +shall be necessary only for Boolean valued options. Boolean options can +be given values by the form +.BR set +.IR option +to turn them on or +.BR set +.BR no \c +.IR option +to turn them off; string and numeric options can be assigned by the +form +.BR set +.IR option =\c +.IR value . +Any +<blank> +characters in strings can be included as is by preceding each +<blank> +with an escaping +<backslash>. +More than one option can be set or listed by a single set command by +specifying multiple arguments, each separated from the next by one or more +<blank> +characters. +.P +See +.IR "Edit Options in ex" +for details about specific options. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Shell" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +sh\fB[\fRell\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Invoke the program named in the +.BR shell +edit option with the single argument +.BR \(mii +(interactive mode). Editing shall be resumed when the program exits. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Source" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +so\fB[\fRurce\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +Read and execute +.IR ex +commands from +.IR file . +Lines in the file that are blank lines shall be ignored. +.P +.IR "Current line" : +As specified for the individual +.IR ex +commands. +.P +.IR "Current column" : +As specified for the individual +.IR ex +commands. +.SS "Substitute" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRs\fB[\fRubstitute\fB][\fR/\fIpattern\fR/\fIrepl\fR/\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR +.br +\fB[\fI2addr\fB] \fR&\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR +.br +\fB[\fI2addr\fB] \fR~\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR +.fi \fR +.P +.RE +.RE +.P +Replace the first instance of the pattern +.IR pattern +by the string +.IR repl +on each specified line. (See +.IR "Regular Expressions in ex" +and +.IR "Replacement Strings in ex".) +Any non-alphabetic, non-\c +<blank> +delimiter other than +<backslash>, +.BR '|' , +<newline>, +or double-quote +can be used instead of +.BR '/' . +<backslash> +characters can be used to escape delimiters, +<backslash> +characters, and other special characters. +.P +The trailing delimiter can be omitted from +.IR pattern +or from +.IR repl +at the end of the command line. If both +.IR pattern +and +.IR repl +are not specified or are empty (for example, +.BR \(dq//\(dq ), +the last +.BR s +command shall be repeated. If only +.IR pattern +is not specified or is empty, the last regular expression used in the +editor shall be used as the pattern. If only +.IR repl +is not specified or is empty, the pattern shall be replaced by nothing. +If the entire replacement pattern is +.BR '%' , +the last replacement pattern to an +.BR s +command shall be used. +.P +Entering a +<carriage-return> +in +.IR repl +(which requires an escaping +<backslash> +in +.IR ex +mode and an escaping +<control>\(hyV +in open or +.IR vi +mode) shall split the line at that point, creating a new line in the +edit buffer. The +<carriage-return> +shall be discarded. +.P +If +.IR options +includes the letter +.BR 'g' +(\c +.BR global ), +all non-overlapping instances of the pattern in the line shall be +replaced. +.P +If +.IR options +includes the letter +.BR 'c' +(\c +.BR confirm ), +then before each substitution the line shall be written; the written +line shall reflect all previous substitutions. On the following line, +<space> +characters shall be written beneath the characters from the line that +are before the +.IR pattern +to be replaced, and +.BR '^' +characters written beneath the characters included in the +.IR pattern +to be replaced. The +.IR ex +utility shall then wait for a response from the user. An affirmative +response shall cause the substitution to be done, while any other input +shall not make the substitution. An affirmative response shall consist +of a line with the affirmative response (as defined by the current +locale) at the beginning of the line. This line shall be subject to +editing in the same way as the +.IR ex +command line. +.P +If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications +confirmed by the user shall be preserved in the edit buffer after the +interrupt. +.P +If the remembered search direction is not set, the +.BR s +command shall set it to forward. +.P +In the second Synopsis, the +.BR & +command shall repeat the previous substitution, as if the +.BR & +command were replaced by: +.sp +.RS 4 +.nf +\fB +s/\fIpattern\fR/\fIrepl\fR/ +.fi \fR +.P +.RE +.P +where +.IR pattern +and +.IR repl +are as specified in the previous +.BR s , +.BR & , +or +.BR ~ +command. +.P +In the third Synopsis, the +.BR ~ +command shall repeat the previous substitution, as if the +.BR '~' +were replaced by: +.sp +.RS 4 +.nf +\fB +s/\fIpattern\fR/\fIrepl\fR/ +.fi \fR +.P +.RE +.P +where +.IR pattern +shall be the last regular expression specified to the editor, and +.IR repl +shall be from the previous substitution (including +.BR & +and +.BR ~ ) +command. +.P +These commands shall be affected by the +.IR LC_MESSAGES +environment variable. +.P +.IR "Current line" : +Set to the last line in which a substitution occurred, or, unchanged if +no substitution occurred. +.P +.IR "Current column": +Set to non-\c +<blank>. +.SS "Suspend" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +su\fB[\fRspend\fB][\fR!\fB]\fR +st\fB[\fRop\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Allow control to return to the invoking process; +.IR ex +shall suspend itself as if it had received the SIGTSTP signal. The +suspension shall occur only if job control is enabled in the invoking +shell (see the description of +.IR set +.BR \(mim ). +.P +These commands shall be affected by the +.BR autowrite +and +.BR writeany +edit options. +.P +The current +.BR susp +character (see +.IR "\fIstty\fR\^") +shall be equivalent to the +.BR suspend +command. +.SS "Tag" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ta\fB[\fRg\fB][\fR!\fB] \fItagstring\fR +.fi \fR +.P +.RE +.RE +.P +The results are unspecified if the format of a tags file is not as +specified by the +.IR ctags +utility (see +.IR "\fIctags\fR\^") +description. +.P +The +.BR tag +command shall search for +.IR tagstring +in the tag files referred to by the +.BR tag +edit option, in the order they are specified, until a reference to +.IR tagstring +is found. Files shall be searched from beginning to end. If no +reference is found, it shall be an error and an error message to this +effect shall be written. If the reference is not found, or if an error +occurs while processing a file referred to in the +.BR tag +edit option, it shall be an error, and an error message shall be +written at the first occurrence of such an error. +.P +Otherwise, if the tags file contained a pattern, the pattern shall be +treated as a regular expression used in the editor; for example, for +the purposes of the +.BR s +command. +.P +If the +.IR tagstring +is in a file with a different name than the current pathname, set the +current pathname to the name of that file, and replace the contents of +the edit buffer with the contents of that file. In this case, if no +.BR '!' +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 +.BR autowrite +option. +.P +This command shall be affected by the +.BR autowrite , +.BR tag , +.BR taglength , +and +.BR writeany +edit options. +.P +.IR "Current line" : +If the tags file contained a line number, set to that line number. If +the line number is larger than the last line in the edit buffer, an +error message shall be written and the current line shall be set as +specified for the +.BR edit +command. +.P +If the tags file contained a pattern, set to the first occurrence of +the pattern in the file. If no matching pattern is found, an error +message shall be written and the current line shall be set as specified +for the +.BR edit +command. +.P +.IR "Current column" : +If the tags file contained a line-number reference and that line-number +was not larger than the last line in the edit buffer, or if the tags +file contained a pattern and that pattern was found, set to non-\c +<blank>. +Otherwise, set as specified for the +.BR edit +command. +.SS "Unabbreviate" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +una\fB[\fRbbrev\fB] \fIlhs\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR lhs +is not an entry in the current list of abbreviations (see +.IR "Abbreviate"), +it shall be an error. Otherwise, delete +.IR lhs +from the list of abbreviations. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Undo" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +u\fB[\fRndo\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Reverse the changes made by the last command that modified the contents +of the edit buffer, including +.BR undo . +For this purpose, the +.BR global , +.BR v , +.BR open , +and +.BR visual +commands, and commands resulting from buffer executions and mapped +character expansions, are considered single commands. +.P +If no action that can be undone preceded the +.BR undo +command, it shall be an error. +.P +If the +.BR undo +command restores lines that were marked, the mark shall also be +restored unless it was reset subsequent to the deletion of the lines. +.P +.IR "Current line" : +.IP " 1." 4 +If lines are added or changed in the file, set to the first line added +or changed. +.IP " 2." 4 +Set to the line before the first line deleted, if it exists. +.IP " 3." 4 +Set to 1 if the edit buffer is not empty. +.IP " 4." 4 +Set to zero. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Unmap" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +unm\fB[\fRap\fB][\fR!\fB] \fIlhs\fR +.fi \fR +.P +.RE +.RE +.P +If +.BR '!' +is appended to the command name, and if +.IR lhs +is not an entry in the list of text input mode map definitions, it +shall be an error. Otherwise, delete +.IR lhs +from the list of text input mode map definitions. +.P +If no +.BR '!' +is appended to the command name, and if +.IR lhs +is not an entry in the list of command mode map definitions, it shall +be an error. Otherwise, delete +.IR lhs +from the list of command mode map definitions. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Version" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ve\fB[\fRrsion\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write a message containing version information for the editor. The +format of the message is unspecified. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Visual" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRvi\fB[\fRsual\fB][\fItype\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR ex +is currently in open or visual mode, the Synopsis and behavior of the +visual command shall be the same as the +.BR edit +command, as specified by +.IR "Edit". +.P +Otherwise, this command need not be supported on block-mode terminals +or terminals with insufficient capabilities. If standard input, +standard output, or standard error are not terminal devices, the +results are unspecified. +.P +If +.IR count +is specified, the value of the +.BR window +edit option shall be set to +.IR count +(as described in +.IR "window"). +If the +.BR '^' +type character was also specified, the +.BR window +edit option shall be set before being used by the type character. +.P +Enter visual mode. If +.IR type +is not specified, it shall be as if a +.IR type +of +.BR '\(pl' +was specified. The +.IR type +shall cause the following effects: +.IP "\fR+\fP" 6 +Place the beginning of the specified line at the top of the display. +.IP "\fR-\fP" 6 +Place the end of the specified line at the bottom of the display. +.IP "\fR.\fP" 6 +Place the beginning of the specified line in the middle of the display. +.IP "\fR^\fP" 6 +If the specified line is less than or equal to the value of the +.BR window +edit option, set the line to 1; otherwise, decrement the line by the +value of the +.BR window +edit option minus 1. Place the beginning of this line as close to the +bottom of the displayed lines as possible, while still displaying the +value of the +.BR window +edit option number of lines. +.P +.IR "Current line" : +Set to the specified line. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Write" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRw\fB[\fRrite\fB][\fR!\fB][\fR>>\fB][\fIfile\fB] +[\fI2addr\fB] \fRw\fB[\fRrite\fB][\fR!\fB][\fIfile\fB] +[\fI2addr\fB] \fRwq\fB[\fR!\fB][\fR>>\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no lines are specified, the lines shall default to the entire file. +.P +The command +.BR wq +shall be equivalent to a +.BR write +command followed by a +.BR quit +command; +.BR wq! +shall be equivalent to +.BR write! +followed by +.BR quit . +In both cases, if the +.BR write +command fails, the +.BR quit +shall not be attempted. +.P +If the command name is not followed by one or more +<blank> +characters, or +.IR file +is not preceded by a +.BR '!' +character, the +.BR write +shall be to a file. +.IP " 1." 4 +If the +.BR >> +argument is specified, and the file already exists, the lines shall be +appended to the file instead of replacing its contents. If the +.BR >> +argument is specified, and the file does not already exist, it is +unspecified whether the write shall proceed as if the +.BR >> +argument had not been specified or if the write shall fail. +.IP " 2." 4 +If the +.BR readonly +edit option is set (see +.IR "readonly"), +the +.BR write +shall fail. +.IP " 3." 4 +If +.IR file +is specified, and is not the current pathname, and the file exists, +the +.BR write +shall fail. +.IP " 4." 4 +If +.IR file +is not specified, the current pathname shall be used. If there is no +current pathname, the +.BR write +command shall fail. +.IP " 5." 4 +If the current pathname is used, and the current pathname has been +changed by the +.BR file +or +.BR read +commands, and the file exists, the +.BR write +shall fail. If the +.BR write +is successful, subsequent +.BR write s +shall not fail for this reason (unless the current pathname is changed +again). +.IP " 6." 4 +If the whole edit buffer is not being written, and the file to be +written exists, the +.BR write +shall fail. +.P +For rules 1., 2., 3., and 5., the +.BR write +can be forced by appending the character +.BR '!' +to the command name. +.P +For rules 2., 3., and 5., the +.BR write +can be forced by setting the +.BR writeany +edit option. +.P +Additional, implementation-defined tests may cause the +.BR write +to fail. +.P +If the edit buffer is empty, a file without any contents shall be written. +.P +An informational message shall be written noting the number of lines +and bytes written. +.P +Otherwise, if the command is followed by one or more +<blank> +characters, and the file is preceded by +.BR '!' , +the rest of the line after the +.BR '!' +shall have +.BR '%' , +.BR '#' , +and +.BR '!' +characters expanded as described in +.IR "Command Line Parsing in ex". +.P +The +.IR ex +utility shall then pass two arguments to the program named by the +.BR shell +edit option; the first shall be +.BR \(mic +and the second shall be the expanded arguments to the +.BR 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 +.BR print +command. If the last character in that output is not a +<newline>, +a +<newline> +shall be written at the end of the output. +.P +The special meaning of the +.BR '!' +following the +.BR write +command can be overridden by escaping it with a +<backslash> +character. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Write and Exit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRx\fB[\fRit\fB][\fR!\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If the edit buffer has not been modified since the last complete +.BR write , +.BR xit +shall be equivalent to the +.BR quit +command, or if a +.BR '!' +is appended to the command name, to +.BR quit! . +.P +Otherwise, +.BR xit +shall be equivalent to the +.BR wq +command, or if a +.BR '!' +is appended to the command name, to +.BR wq! . +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Yank" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRya\fB[\fRnk\fB][\fIbuffer\fB][\fIcount\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Copy the specified lines to the specified buffer (by default, the +unnamed buffer), which shall become a line-mode buffer. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Adjust Window" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRz\fB[\fR!\fB][\fItype \fR...\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no line is specified, the current line shall be the default; if +.IR 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. +.P +If there are +<blank> +characters between the +.IR type +argument and the preceding +.BR z +command name or optional +.BR '!' +character, it shall be an error. +.P +If +.IR count +is specified, the value of the +.BR window +edit option shall be set to +.IR count +(as described in +.IR "window"). +If +.IR count +is omitted, it shall default to 2 times the value of the +.BR scroll +edit option, or if +.BR ! +was specified, the number of lines in the display minus 1. +.P +If +.IR type +is omitted, then +.IR count +lines starting with the specified line shall be written. Otherwise, +.IR count +lines starting with the line specified by the +.IR type +argument shall be written. +.P +The +.IR type +argument shall change the lines to be written. The possible values of +.IR type +are as follows: +.IP "\fR\(mi\fP" 6 +The specified line shall be decremented by the following value: +.RS 6 +.sp +.RS 4 +.nf +\fB +(((number of ``\(mi'' characters) x \fIcount\fR) \(mi1) +.fi \fR +.P +.RE +.P +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 +.IR count +lines or the last line in the edit buffer has been written. +.RE +.IP "\fR+\fP" 6 +The specified line shall be incremented by the following value: +.RS 6 +.sp +.RS 4 +.nf +\fB +(((number of ``+'' characters) \(mi1) x \fIcount\fR) +1 +.fi \fR +.P +.RE +.P +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 +.IR count +lines or the last line in the edit buffer has been written. +.RE +.IP "\fR=\fR,\fR.\fR" 6 +If more than a single +.BR '.' +or +.BR '=' +is specified, it shall be an error. The following steps shall be +taken: +.RS 6 +.IP " 1." 4 +If +.IR count +is zero, nothing shall be written. +.IP " 2." 4 +Write as many of the +.IR N +lines before the current line in the edit buffer as exist. If +.IR count +or +.BR '!' +was specified, +.IR N +shall be: +.RS 4 +.sp +.RS 4 +.nf +\fB +(\fIcount\fR \(mi1) /2 +.fi \fR +.P +.RE +.P +Otherwise, +.IR N +shall be: +.sp +.RS 4 +.nf +\fB +(\fIcount\fP \(mi3) /2 +.fi \fR +.P +.RE +.P +If +.IR N +is a number less than 3, no lines shall be written. +.RE +.IP " 3." 4 +If +.BR '=' +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 +.BR '\(mi' +characters. +.IP " 4." 4 +Write the current line. +.IP " 5." 4 +Repeat step 3. +.IP " 6." 4 +Write as many of the +.IR N +lines after the current line in the edit buffer as exist. +.IR N +shall be defined as in step 2. If +.IR N +is a number less than 3, no lines shall be written. If +.IR count +is less than 3, no lines shall be written. +.RE +.IP "\fR^\fP" 6 +The specified line shall be decremented by the following value: +.RS 6 +.sp +.RS 4 +.nf +\fB +(((number of ``^'' characters) +1) x \fIcount\fR) \(mi1 +.fi \fR +.P +.RE +.P +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 +.IR count +lines or the last line in the edit buffer has been written. +.RE +.P +.IR "Current line" : +Set to the last line written, unless the type is +.BR = , +in which case, set to the specified line. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Escape" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +! \fIcommand +\fB[\fIaddr\fB]\fR! \fIcommand\fR +.fi \fR +.P +.RE +.RE +.P +The contents of the line after the +.BR '!' +shall have +.BR '%' , +.BR '#' , +and +.BR '!' +characters expanded as described in +.IR "Command Line Parsing in ex". +If the expansion causes the text of the line to change, it shall be +redisplayed, preceded by a single +.BR '!' +character. +.P +The +.IR ex +utility shall execute the program named by the +.BR shell +edit option. It shall pass two arguments to the program; the first +shall be +.BR \(mic , +and the second shall be the expanded arguments to the +.BR ! +command as a single argument. +.P +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 +.IR 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 +.BR warn +edit option is set. +.P +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. +.P +If in +.IR ex +mode, a single +.BR '!' +character shall be written when the program completes. +.P +This command shall be affected by the +.BR shell +and +.BR warn +edit options. If no lines are specified, this command shall be affected +by the +.BR autowrite +and +.BR writeany +edit options. If lines are specified, this command shall be affected by +the +.BR autoprint +edit option. +.br +.P +.IR "Current line" : +.IP " 1." 4 +If no lines are specified, unchanged. +.IP " 2." 4 +Otherwise, set to the last line read in, if any lines are read in. +.IP " 3." 4 +Otherwise, set to the line before the first line of the lines +specified, if that line exists. +.IP " 4." 4 +Otherwise, set to the first line of the edit buffer if the edit buffer +is not empty. +.IP " 5." 4 +Otherwise, set to zero. +.P +.IR "Current column" : +If no lines are specified, unchanged. Otherwise, set to non-\c +<blank>. +.SS "Shift Left" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB]\fR <\fB[\fR< ...\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +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 +.BR shiftwidth +edit option. Only leading +<blank> +characters shall be deleted or changed into other +<blank> +characters in shifting; other characters shall not be affected. +.P +Lines to be shifted shall be copied into the unnamed buffer, which +shall become a line-mode buffer. +.P +This command shall be affected by the +.BR autoprint +edit option. +.P +.IR "Current line" : +Set to the last line in the lines specified. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Shift Right" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB]\fR >\fB[\fR> ...\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Shift the specified lines away from 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 +.BR shiftwidth +edit option. The shift shall be accomplished by adding +<blank> +characters as a prefix to the line or changing leading +<blank> +characters into other +<blank> +characters. Empty lines shall not be changed. +.P +Lines to be shifted shall be copied into the unnamed buffer, which +shall become a line-mode buffer. +.P +This command shall be affected by the +.BR autoprint +edit option. +.P +.IR "Current line" : +Set to the last line in the lines specified. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "<control>\(hyD" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +<control>-D +.fi \fR +.P +.RE +.RE +.P +Write the next +.IR n +lines, where +.IR n +is the minimum of the values of the +.BR 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. +.P +.IR "Current line" : +Set to the last line written. +.P +.IR "Current column" : +Set to non-\c +<blank>. +.SS "Write Line Number" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fR= \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR line +is not specified, it shall default to the last line in the edit buffer. +Write the line number of the specified line. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Execute" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB]\fR @ \fIbuffer\fR +\fB[\fI2addr\fB]\fR * \fIbuffer\fR +.fi \fR +.P +.RE +.RE +.P +If no buffer is specified or is specified as +.BR '@' +or +.BR '*' , +the last buffer executed shall be used. If no previous buffer has been +executed, it shall be an error. +.P +For each line specified by the addresses, set the current line (\c +.BR '.' ) +to the specified line, and execute the contents of the named +.IR buffer +(as they were at the time the +.BR @ +command was executed) as +.IR ex +commands. For each line of a line-mode buffer, and all but the last +line of a character-mode buffer, the +.IR ex +command parser shall behave as if the line was terminated by a +<newline>. +.P +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 +.IR ex +.BR :edit +command) an error message shall be written, and no more commands +resulting from the execution of this command shall be processed. +.P +.IR "Current line" : +As specified for the individual +.IR ex +commands. +.P +.IR "Current column" : +As specified for the individual +.IR ex +commands. +.SS "Regular Expressions in ex" +.P +The +.IR ex +utility shall support regular expressions that are a superset of the +basic regular expressions described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +A null regular expression (\c +.BR \(dq//\(dq ) +shall be equivalent to the last regular expression encountered. +.P +Regular expressions can be used in addresses to specify lines and, in +some commands (for example, the +.BR substitute +command), to specify portions of a line to be substituted. +.P +The following constructs can be used to enhance the basic regular +expressions: +.IP "\fR\e<\fR" 6 +Match the beginning of a +.IR word . +(See the definition of +.IR word +at the beginning of +.IR "Command Descriptions in ex".) +.IP "\fR\e>\fR" 6 +Match the end of a +.IR word . +.IP "\fR~\fR" 6 +Match the replacement part of the last +.BR substitute +command. The +<tilde> +(\c +.BR '~' ) +character can be escaped in a regular expression to become a normal +character with no special meaning. The +<backslash> +shall be discarded. +.P +When the editor option +.BR magic +is not set, the only characters with special meanings shall be +.BR '^' +at the beginning of a pattern, +.BR '$' +at the end of a pattern, and +<backslash>. +The characters +.BR '.' , +.BR '*' , +.BR '[' , +and +.BR '~' +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>. +<backslash> +characters used to escape other characters shall be discarded. +.SS "Replacement Strings in ex" +.P +The character +.BR '&' +(\c +.BR '\e&' +if the editor option +.BR magic +is not set) in the replacement string shall stand for the text matched +by the pattern to be replaced. The character +.BR '~' +(\c +.BR '\e~' +if +.BR magic +is not set) shall be replaced by the replacement part of the previous +.BR substitute +command. The sequence +.BR '\en' , +where +.IR 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 +.BR '\en' +shall be replaced by the empty string. +.P +The strings +.BR '\el' , +.BR '\eu' , +.BR '\eL' , +and +.BR '\eU' +can be used to modify the case of elements in the replacement string +(using the +.BR '\e&' +or +.BR \(dq\e\(dq digit) +notation. The string +.BR '\el' +(\c +.BR '\eu' ) +shall cause the character that follows to be converted to lowercase +(uppercase). The string +.BR '\eL' +(\c +.BR '\eU' ) +shall cause all characters subsequent to it to be converted to +lowercase (uppercase) as they are inserted by the substitution until +the string +.BR '\ee' +or +.BR '\eE' , +or the end of the replacement string, is encountered. +.P +Otherwise, any character following a +<backslash> +shall be treated as that literal character, and the escaping +<backslash> +shall be discarded. +.P +An example of case conversion with the +.BR s +command is as follows: +.sp +.RS 4 +.nf +\fB +\fB:\fRp +\fBThe cat sat on the mat. +\fB:\fRs/\e<.at\e>/\eu&/gp +\fBThe Cat Sat on the Mat. +\fB:\fRs/S\e(.*\e)M/S\eU\e1\eeM/p +\fBThe Cat SAT ON THE Mat.\fR +.fi \fR +.P +.RE +.SS "Edit Options in ex" +.P +The +.IR ex +utility has a number of options that modify its behavior. These options +have default settings, which can be changed using the +.BR set +command. +.P +Options are Boolean unless otherwise specified. +.SS "autoindent, ai" +.P +[Default \fIunset\fR] +.P +If +.BR 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 +.BR tabstop , +and then using +<space> +characters) to align with another line, as follows: +.IP " 1." 4 +If in open or visual mode and the text input is part of a line-oriented +command (see the EXTENDED DESCRIPTION in +.IR "\fIvi\fR\^"), +align to the first column. +.IP " 2." 4 +Otherwise, if in open or visual mode, indentation for each line shall +be set as follows: +.RS 4 +.IP " a." 4 +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>\(hyD +character in +.IR "Input Mode Commands in vi". +.IP " b." 4 +Otherwise, it shall be set to the indentation of the previous current +line, if any; otherwise, to the first column. +.RE +.IP " 3." 4 +For the +.IR ex +.BR a , +.BR i , +and +.BR c +commands, indentation for each line shall be set as follows: +.RS 4 +.IP " a." 4 +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 +.IR eof +character in +.IR "Scroll". +.IP " b." 4 +Otherwise, if the command is the +.IR ex +.BR a +command, it shall be set to the line appended after, if any; otherwise +to the first column. +.IP " c." 4 +Otherwise, if the command is the +.IR ex +.BR i +command, it shall be set to the line inserted before, if any; otherwise +to the first column. +.IP " d." 4 +Otherwise, if the command is the +.IR ex +.BR c +command, it shall be set to the indentation of the line replaced. +.RE +.SS "autoprint, ap" +.P +[Default \fIset\fR] +.P +If +.BR autoprint +is set, the current line shall be written after each +.IR ex +command that modifies the contents of the current edit buffer, and +after each +.BR tag +command for which the tag search pattern was found or tag line number +was valid, unless: +.IP " 1." 4 +The command was executed while in open or visual mode. +.IP " 2." 4 +The command was executed as part of a +.BR global +or +.BR v +command or +.BR @ +buffer execution. +.IP " 3." 4 +The command was the form of the +.BR read +command that reads a file into the edit buffer. +.IP " 4." 4 +The command was the +.BR append , +.BR change , +or +.BR insert +command. +.IP " 5." 4 +The command was not terminated by a +<newline>. +.IP " 6." 4 +The current line shall be written by a flag specified to the command; +for example, +.BR "delete #" +shall write the current line as specified for the flag modifier to the +.BR delete +command, and not as specified by the +.BR autoprint +edit option. +.SS "autowrite, aw" +.P +[Default \fIunset\fR] +.P +If +.BR 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 +.IR ex +.BR write +command had been specified without arguments, before each command +affected by the +.BR autowrite +edit option is executed. Appending the character +.BR '!' +to the command name of any of the +.IR ex +commands except +.BR '!' +shall prevent the write. If the write fails, it shall be an error and +the command shall not be executed. +.SS "beautify, bf" +.P +[Default \fIunset\fR] +.P +If +.BR beautify +is set, all non-printable characters, other than +<tab>, +<newline>, +and +<form-feed> +characters, shall be discarded from text read in from files. +.SS "directory, dir" +.P +[Default \fIimplementation-defined\fR] +.P +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. +.SS "edcompatible, ed" +.P +[Default \fIunset\fR] +.P +Causes the presence of +.BR g +and +.BR c +suffixes on substitute commands to be remembered, and toggled by +repeating the suffixes. +.SS "errorbells, eb" +.P +[Default \fIunset\fR] +.P +If the editor is in +.IR ex +mode, and the terminal does not support a standout mode (such as +inverse video), and +.BR errorbells +is set, error messages shall be preceded by alerting the terminal. +.SS "exrc" +.P +[Default \fIunset\fR] +.P +If +.BR exrc +is set, +.IR ex +shall access any +.BR .exrc +file in the current directory, as described in +.IR "Initialization in ex and vi". +If +.BR exrc +is not set, +.IR ex +shall ignore any +.BR .exrc +file in the current directory during initialization, unless the current +directory is that named by the +.IR HOME +environment variable. +.SS "ignorecase, ic" +.P +[Default \fIunset\fR] +.P +If +.BR ignorecase +is set, characters that have uppercase and lowercase representations +shall have those representations considered as equivalent for purposes +of regular expression comparison. +.P +The +.BR ignorecase +edit option shall affect all remembered regular expressions; for +example, unsetting the +.BR ignorecase +edit option shall cause a subsequent +.IR vi +.BR n +command to search for the last basic regular expression in a +case-sensitive fashion. +.SS "list" +.P +[Default \fIunset\fR] +.P +If +.BR list +is set, edit buffer lines written while in +.IR ex +command mode shall be written as specified for the +.BR print +command with the +.BR l +flag specified. In open or visual mode, each edit buffer line shall be +displayed as specified for the +.IR ex +.BR print +command with the +.BR l +flag specified. In open or visual text input mode, when the cursor +does not rest on any character in the line, it shall rest on the +.BR '$' +marking the end of the line. +.SS "magic" +.P +[Default \fIset\fR] +.P +If +.BR magic +is set, modify the interpretation of characters in regular expressions +and substitution replacement strings (see +.IR "Regular Expressions in ex" +and +.IR "Replacement Strings in ex"). +.SS "mesg" +.P +[Default \fIset\fR] +.P +If +.BR mesg +is set, the permission for others to use the +.BR write +or +.BR talk +commands to write to the terminal shall be turned on while in open or +visual mode. The shell-level command +.IR mesg +.BR n +shall take precedence over any setting of the +.IR ex +.BR mesg +option; that is, if +.BR "mesg y" +was issued before the editor started (or in a shell escape), such as: +.sp +.RS 4 +.nf +\fB +:!mesg y +.fi \fR +.P +.RE +.P +the +.BR mesg +option in +.IR ex +shall suppress incoming messages, but the +.BR mesg +option shall not enable incoming messages if +.BR "mesg n" +was issued. +.SS "number, nu" +.P +[Default \fIunset\fR] +.P +If +.BR number +is set, edit buffer lines written while in +.IR ex +command mode shall be written with line numbers, in the format +specified by the +.BR print +command with the +.BR # +flag specified. In +.IR ex +text input mode, each line shall be preceded by the line number it will +have in the file. +.P +In open or visual mode, each edit buffer line shall be displayed with a +preceding line number, in the format specified by the +.IR ex +.BR print +command with the +.BR # +flag specified. This line number shall not be considered part of the +line for the purposes of evaluating the current column; that is, column +position 1 shall be the first column position after the format +specified by the +.BR print +command. +.SS "paragraphs, para" +.P +[Default in the POSIX locale \fRIPLPPPQPP LIpplpipbp\fR] +.P +The +.BR paragraphs +edit option shall define additional paragraph boundaries for the open +and visual mode commands. The +.BR paragraphs +edit option can be set to a character string consisting of zero or more +character pairs. It shall be an error to set it to an odd number of +characters. +.SS "prompt" +.P +[Default \fIset\fR] +.P +If +.BR prompt +is set, +.IR ex +command mode input shall be prompted for with a +<colon> +(\c +.BR ':' ); +when unset, no prompt shall be written. +.SS "readonly" +.P +[Default \fIsee text\fR] +.P +If the +.BR readonly +edit option is set, read-only mode shall be enabled (see +.IR "Write"). +The +.BR readonly +edit option shall be initialized to set if either of the following +conditions are true: +.IP " *" 4 +The command-line option +\(miR +was specified. +.IP " *" 4 +Performing actions equivalent to the +\fIaccess\fR() +function called with the following arguments indicates that the file +lacks write permission: +.RS 4 +.IP " 1." 4 +The current pathname is used as the +.IR path +argument. +.IP " 2." 4 +The constant +.BR W_OK +is used as the +.IR amode +argument. +.RE +.P +The +.BR readonly +edit option may be initialized to set for other, +implementation-defined reasons. The +.BR readonly +edit option shall not be initialized to unset based on any special +privileges of the user or process. The +.BR readonly +edit option shall be reinitialized each time that the contents of the +edit buffer are replaced (for example, by an +.BR edit +or +.BR next +command) unless the user has explicitly set it, in which case it shall +remain set until the user explicitly unsets it. Once unset, it shall +again be reinitialized each time that the contents of the edit buffer +are replaced. +.SS "redraw" +.P +[Default \fIunset\fR] +.P +The editor simulates an intelligent terminal on a dumb terminal. +(Since this is likely to require a large amount of output to the +terminal, it is useful only at high transmission speeds.) +.SS "remap" +.P +[Default \fIset\fR] +.P +If +.BR remap +is set, map translation shall allow for maps defined in terms of other +maps; translation shall continue until a final product is obtained. If +unset, only a one-step translation shall be done. +.SS "report" +.P +[Default 5] +.P +The value of this +.BR report +edit option specifies what number of lines being added, copied, +deleted, or modified in the edit buffer will cause an informational +message to be written to the user. The following conditions shall cause +an informational message. The message shall contain the number of lines +added, copied, deleted, or modified, but is otherwise unspecified. +.IP " *" 4 +An +.IR ex +or +.IR vi +editor command, other than +.BR open , +.BR undo , +or +.BR visual , +that modifies at least the value of the +.BR report +edit option number of lines, and which is not part of an +.IR ex +.BR global +or +.BR v +command, or +.IR ex +or +.IR vi +buffer execution, shall cause an informational message to be written. +.IP " *" 4 +An +.IR ex +.BR yank +or +.IR vi +.BR y +or +.BR Y +command, that copies at least the value of the +.BR report +edit option plus 1 number of lines, and which is not part of an +.IR ex +.BR global +or +.BR v +command, or +.IR ex +or +.IR vi +buffer execution, shall cause an informational message to be written. +.IP " *" 4 +An +.IR ex +.BR global , +.BR v , +.BR open , +.BR undo , +or +.BR visual +command or +.IR ex +or +.IR vi +buffer execution, that adds or deletes a total of at least the value of +the +.BR report +edit option number of lines, and which is not part of an +.IR ex +.BR global +or +.BR v +command, or +.IR ex +or +.IR vi +buffer execution, shall cause an informational message to be written. +(For example, if 3 lines were added and 8 lines deleted during an +.IR ex +.BR visual +command, 5 would be the number compared against the +.BR report +edit option after the command completed.) +.SS "scroll, scr" +.P +[Default (number of lines in the display \(mi1)/2] +.P +The value of the +.BR scroll +edit option shall determine the number of lines scrolled by the +.IR ex +<control>\(hyD +and +.BR z +commands. For the +.IR vi +<control>\(hyD +and +<control>\(hyU +commands, it shall be the initial number of lines to scroll when no +previous +<control>\(hyD +or +<control>\(hyU +command has been executed. +.SS "sections" +.P +[Default in the POSIX locale \fRNHSHH HUnhsh\fR] +.P +The +.BR sections +edit option shall define additional section boundaries for the open and +visual mode commands. The +.BR sections +edit option can be set to a character string consisting of zero or more +character pairs; it shall be an error to set it to an odd number of +characters. +.SS "shell, sh" +.P +[Default from the environment variable +.IR SHELL ] +.P +The value of this option shall be a string. The default shall be taken +from the +.IR SHELL +environment variable. If the +.IR SHELL +environment variable is null or empty, the +.IR sh +(see +.IR "\fIsh\fR\^") +utility shall be the default. +.SS "shiftwidth, sw" +.P +[Default 8] +.P +The value of this option shall give the width in columns of an +indentation level used during autoindentation and by the shift commands +(\c +.BR < +and +.BR > ). +.SS "showmatch, sm" +.P +[Default \fIunset\fR] +.P +The functionality described for the +.BR showmatch +edit option need not be supported on block-mode terminals or terminals +with insufficient capabilities. +.P +If +.BR showmatch +is set, in open or visual mode, when a +.BR ')' +or +.BR '}' +is typed, if the matching +.BR '(' +or +.BR '{' +is currently visible on the display, the matching +.BR '(' +or +.BR '{' +shall be flagged moving the cursor to its location for an unspecified +amount of time. +.SS "showmode" +.P +[Default \fIunset\fP] +.P +If +.BR showmode +is set, in open or visual mode, the current mode that the editor is in +shall be displayed on the last line of the display. Command mode and +text input mode shall be differentiated; other unspecified modes and +implementation-defined information may be displayed. +.SS "slowopen" +.P +[Default \fIunset\fR] +.P +If +.BR 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 display the characters entered by the user (see +.IR "Input Mode Commands in vi"). +.SS "tabstop, ts" +.P +[Default 8] +.P +The value of this edit option shall specify the column boundary used by +a +<tab> +in the display (see +.IR "autoprint" ", " "ap" +and +.IR "Input Mode Commands in vi"). +.SS "taglength, tl" +.P +[Default zero] +.P +The value of this edit option shall specify the maximum number of +characters that are considered significant in the user-specified tag +name and in the tag name from the tags file. If the value is zero, all +characters in both tag names shall be significant. +.SS "tags" +.P +[Default \fIsee text\fP] +.P +The value of this edit option shall be a string of +<blank>-delimited +pathnames of files used by the +.BR tag +command. The default value is unspecified. +.SS "term" +.P +[Default from the environment variable +.IR TERM ] +.P +The value of this edit option shall be a string. The default shall be +taken from the +.IR TERM +variable in the environment. If the +.IR TERM +environment variable is empty or null, the default is unspecified. The +editor shall use the value of this edit option to determine the type of +the display device. +.P +The results are unspecified if the user changes the value of the term +edit option after editor initialization. +.SS "terse" +.P +[Default \fIunset\fR] +.P +If +.BR terse +is set, error messages may be less verbose. However, except for this +caveat, error messages are unspecified. Furthermore, not all error +messages need change for different settings of this option. +.SS "warn" +.P +[Default \fIset\fR] +.P +If +.BR warn +is set, and the contents of the edit buffer have been modified since +they were last completely written, the editor shall write a warning +message before certain +.BR ! +commands (see +.IR "Escape"). +.SS "window" +.P +[Default \fIsee text\fR] +.P +A value used in open and visual mode, by the +<control>\(hyB +and +<control>\(hyF +commands, and, in visual mode, to specify the number of lines displayed +when the screen is repainted. +.P +If the +.BR \(miw +command-line option is not specified, the default value shall be set to +the value of the +.IR LINES +environment variable. If the +.IR LINES +environment variable is empty or null, the default shall be the number +of lines in the display minus 1. +.P +Setting the +.BR window +edit option to zero or to a value greater than the number of lines in +the display minus 1 (either explicitly or based on the +.BR \(miw +option or the +.IR LINES +environment variable) shall cause the +.BR window +edit option to be set to the number of lines in the display minus 1. +.P +The baud rate of the terminal line may change the default in an +implementation-defined manner. +.SS "wrapmargin, wm" +.P +[Default 0] +.P +If the value of this edit option is zero, it shall have no effect. +.P +If not in the POSIX locale, the effect of this edit option is +implementation-defined. +.P +Otherwise, it shall specify a number of columns from the ending margin +of the terminal. +.P +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 +.BR wrapmargin +columns from the ending margin of the display line, the editor shall +behave as follows: +.IP " 1." 4 +If the character triggering this event is a +<blank>, +it, and all immediately preceding +<blank> +characters on the current line entered during the execution of the +current text input command, shall be discarded, and the editor shall +behave as if the user had entered a single +<newline> +instead. In addition, if the next user-entered character is a +<space>, +it shall be discarded as well. +.IP " 2." 4 +Otherwise, if there are one or more +<blank> +characters on the current line immediately preceding the last group of +inserted non-\c +<blank> +characters which was entered during the execution of the current text +input command, the +<blank> +characters shall be replaced as if the user had entered a single +<newline> +instead. +.P +If the +.BR autoindent +edit option is set, and the events described in 1. or 2. are performed, +any +<blank> +characters at or after the cursor in the current line shall be discarded. +.P +The ending margin shall be determined by the system or overridden by +the user, as described for +.IR COLUMNS +in the ENVIRONMENT VARIABLES section and the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SS "wrapscan, ws" +.P +[Default \fIset\fR] +.P +If +.BR wrapscan +is set, searches (the +.IR ex +.BR / +or +.BR ? +addresses, or open and visual mode +.BR / , +.BR ? , +.BR N , +and +.BR n +commands) shall wrap around the beginning or end of the edit buffer; +when unset, searches shall stop at the beginning or end of the edit +buffer. +.SS "writeany, wa" +.P +[Default \fIunset\fR] +.P +If +.BR writeany +is set, some of the checks performed when executing the +.IR ex +.BR write +commands shall be inhibited, as described in editor option +.BR autowrite . +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When any error is encountered and the standard input is not a terminal +device file, +.IR ex +shall not write the file or return to command or text input mode, and +shall terminate with a non-zero exit status. +.P +Otherwise, when an unrecoverable error is encountered, it shall be +equivalent to a SIGHUP asynchronous event. +.P +Otherwise, when an error is encountered, the editor shall behave as +specified in +.IR "Command Line Parsing in ex". +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If a SIGSEGV signal is received while +.IR ex +is saving a file, the file might not be successfully saved. +.P +The +.BR next +command can accept more than one file, so usage such as: +.sp +.RS 4 +.nf +\fB +next `ls [abc]*` +.fi \fR +.P +.RE +.P +is valid; it would not be valid for the +.BR edit +or +.BR read +commands, for example, because they expect only one file and +unspecified results occur. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR ex /\c +.IR vi +specification is based on the historical practice found in the 4 BSD and +System V implementations of +.IR ex +and +.IR vi . +.P +A +.IR "restricted editor" +(both the historical +.IR red +utility and modifications to +.IR ex ) +were considered and rejected for inclusion. Neither option provided the +level of security that users might expect. +.P +It is recognized that +.IR 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 +.IR ex +implementation should provide the full set of capabilities on all +terminals capable of supporting them. +.SS "Options" +.P +The +.BR \(mic +replacement for +.BR + \c +.IR command +was inspired by the +.BR \(mie +option of +.IR sed . +Historically, all such commands (see +.BR edit +and +.BR next +as well) were executed from the last line of the edit buffer. This +meant, for example, that +.BR \(dq+/pattern\(dq +would fail unless the +.BR wrapscan +option was set. POSIX.1\(hy2008 requires conformance to historical practice. The +.BR \(pl \c +.IR command +option is no longer specified by POSIX.1\(hy2008 but may be present in +some implementations. Historically, some implementations restricted the +.IR ex +commands that could be listed as part of the command line arguments. +For consistency, POSIX.1\(hy2008 does not permit these restrictions. +.P +In historical implementations of the editor, the +.BR \(miR +option (and the +.BR readonly +edit option) only prevented overwriting of files; appending to files +was still permitted, mapping loosely into the +.IR csh +.BR noclobber +variable. Some implementations, however, have not followed this +semantic, and +.BR readonly +does not permit appending either. POSIX.1\(hy2008 follows the latter practice, +believing that it is a more obvious and intuitive meaning of +.BR readonly . +.P +The +.BR \(mis +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''. +.P +The +.BR \(mit +option was required because the +.IR ctags +utility appears in POSIX.1\(hy2008 and the option is available in all historical +implementations of +.IR ex . +.P +Historically, the +.IR ex +and +.IR vi +utilities accepted a +.BR \(mix +option, which did encryption based on the algorithm found in the +historical +.IR crypt +utility. The +.BR \(mix +option for encryption, and the associated +.IR 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. +.SS "Standard Input" +.P +An end-of-file condition is not equivalent to an end-of-file character. +A common end-of-file character, +<control>\(hyD, +is historically an +.IR ex +command. +.P +There was no maximum line length in historical implementations of +.IR 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 +.IR ex +and to aid test suite writers in their development of realistic tests +that exercise this limit. +.SS "Input Files" +.P +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 +.IR ex +and +.IR 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 +.IR ex +and +.IR 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 +.IR ex +or +.IR vi +implementation be required to handle files other than text files. +.P +The paragraph in the INPUT FILES section, ``By default, .\|.\|.'', is +intended to close a long-standing security problem in +.IR ex +and +.IR 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 +.BR \(dqex:\(dq +or +.BR \(dqvi:\(dq +(and, apparently, +.BR \(dqei:\(dq +or +.BR \(dqvx:\(dq ) +to be a line containing editor commands, and +.IR ex +interprets all the text up to the next +.BR ':' +or +<newline> +as a command. Consider the consequences, for example, of an +unsuspecting user using +.IR ex +or +.IR vi +as the editor when replying to a mail message in which a line such as: +.sp +.RS 4 +.nf +\fB +ex:! rm \(mirf : +.fi \fR +.P +.RE +.P +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 +.IR ex +and +.IR vi . +.SS "Asynchronous Events" +.P +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. +.P +Historically, SIGQUIT was ignored by +.IR ex , +but was the equivalent of the +.BR Q +command in visual mode; that is, it exited visual mode and entered +.IR ex +mode. POSIX.1\(hy2008 permits, but does not require, this behavior. Historically, +SIGINT was often used by +.IR vi +users to terminate text input mode (\c +<control>\(hyC +is often easier to enter than +<ESC>). +Some implementations of +.IR vi +alerted the terminal on this event, and some did not. POSIX.1\(hy2008 requires +that SIGINT behave identically to +<ESC>, +and that the terminal not be alerted. +.P +Historically, suspending the +.IR 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\(hy2008 is silent on this issue; implementations are +encouraged to follow historical practice, where possible. +.P +Historically, the +.IR 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 +.IR exec s +an application that then +.IR exec s +.IR 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 +.IR curses +package did not handle SIGTSTP safely, and the receipt of SIGTSTP at +the wrong time would cause them to crash. POSIX.1\(hy2008 is silent on this issue; +implementations are encouraged to treat suspension as an asynchronous +event if possible. +.P +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\(hy2008 permits this behavior, noting that the +.BR undo +command is required to be able to undo these partially completed +commands. +.P +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. +.SS "Standard Error" +.P +For +.IR ex /\c +.IR vi , +diagnostic messages are those messages reported as a result of a failed +attempt to invoke +.IR ex +or +.IR 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. +.SS "Initialization in ex and vi" +.P +If an +.IR ex +command (other than +.BR cd , +.BR chdir , +or +.BR source ) +has a filename argument, one or both of the alternate and current +pathnames will be set. Informally, they are set as follows: +.IP " 1." 4 +If the +.IR ex +command is one that replaces the contents of the edit buffer, and it +succeeds, the current pathname will be set to the filename argument +(the first filename argument in the case of the +.BR next +command) and the alternate pathname will be set to the previous +current pathname, if there was one. +.IP " 2." 4 +In the case of the file read/write forms of the +.BR read +and +.BR write +commands, if there is no current pathname, the current pathname will +be set to the filename argument. +.IP " 3." 4 +Otherwise, the alternate pathname will be set to the filename +argument. +.P +For example, +.BR ":edit foo" +and +.BR ":recover foo" , +when successful, set the current pathname, and, if there was a +previous current pathname, the alternate pathname. The commands +.BR :write , +.BR !command , +and +.BR :edit +set neither the current or alternate pathnames. If the +.BR ":edit foo" +command were to fail for some reason, the alternate pathname would be +set. The +.BR read +and +.BR write +commands set the alternate pathname to their +.IR file +argument, unless the current pathname is not set, in which case they +set the current pathname to their +.IR file +arguments. The alternate pathname was not historically set by the +.BR :source +command. POSIX.1\(hy2008 requires conformance to historical practice. +Implementations adding commands that take filenames as arguments are +encouraged to set the alternate pathname as described here. +.P +Historically, +.IR ex +and +.IR vi +read the +.BR .exrc +file in the +.IR $HOME +directory twice, if the editor was executed in the +.IR $HOME +directory. POSIX.1\(hy2008 prohibits this behavior. +.P +Historically, the 4 BSD +.IR ex +and +.IR vi +read the +.IR $HOME +and local +.BR .exrc +files if they were owned by the real ID of the user, or the +.BR sourceany +option was set, regardless of other considerations. This was a security +problem because it is possible to put normal UNIX system commands +inside a +.BR .exrc +file. POSIX.1\(hy2008 does not specify the +.BR sourceany +option, and historical implementations are encouraged to delete it. +.P +The +.BR .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 continue to +use the +.BR .exrc +files in their home directories. +.P +System V Release 3.2 and later +.IR vi +implementations added the option +.BR [no]exrc . +The behavior is that local +.BR .exrc +files are read-only if the +.BR exrc +option is set. The default for the +.BR exrc +option was off, so by default, local +.BR .exrc +files were not read. The problem this was intended to solve was that +System V permitted users to give away files, so there is no possible +ownership or writeability test to ensure that the file is safe. This is +still a security problem on systems where users can give away files, +but there is nothing additional that POSIX.1\(hy2008 can do. The +implementation-defined exception is intended to permit groups to have +local +.BR .exrc +files that are shared by users, by creating pseudo-users to own the +shared files. +.P +POSIX.1\(hy2008 does not mention system-wide +.IR ex +and +.IR vi +start-up files. While they exist in several implementations of +.IR ex +and +.IR vi , +they are not present in any implementations considered historical +practice by POSIX.1\(hy2008. Implementations that 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 +.IR EXINIT +variable, +.BR $HOME/.exrc , +or local +.BR .exrc +files are evaluated. +.P +Historically, any +.IR ex +command could be entered in the +.IR EXINIT +variable or the +.BR .exrc +file, although ones requiring that the edit buffer already contain +lines of text generally caused historical implementations of the editor +to drop +.BR core . +POSIX.1\(hy2008 requires that any +.IR ex +command be permitted in the +.IR EXINIT +variable and +.BR .exrc +files, for simplicity of specification and consistency, although many +of them will obviously fail under many circumstances. +.P +The initialization of the contents of the edit buffer uses the phrase +``the effect shall be'' with regard to various +.IR 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 +.BR .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 +.IR ex +commands. +.P +Historically, the +.BR \(mit +option behaved as if the tag search were a +.BR + \c +.IR 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 +.BR wrapscan +edit option was not set. POSIX.1\(hy2008 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. +.P +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\(hy2008; +however, implementations are encouraged to provide users a temporary +filename for this buffer because it permits them the use of +.IR ex +commands that use the current pathname during temporary edit +sessions. +.P +Historically, the file specified using the +.BR \(mit +option was not part of the current argument list. This practice is +permitted by POSIX.1\(hy2008; however, implementations are encouraged to include +its name in the current argument list for consistency. +.P +Historically, the +.BR \(mic +command was generally not executed until a file that already exists was +edited. POSIX.1\(hy2008 requires conformance to this historical practice. +Commands that could cause the +.BR \(mic +command to be executed include the +.IR ex +commands +.BR edit , +.BR next , +.BR recover , +.BR rewind , +and +.BR tag , +and the +.IR vi +commands +<control>\(hy^ +and +<control>\(hy]. +Historically, reading a file into an edit buffer did not cause the +.BR \(mic +command to be executed (even though it might set the current pathname) +with the exception that it did cause the +.BR \(mic +command to be executed if: the editor was in +.IR 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\(hy2008 does not permit this behavior. +.P +Historically, the +.BR \(mir +option was the same as a normal edit session if there was no recovery +information available for the file. This allowed users to enter: +.sp +.RS 4 +.nf +\fB +vi \(mir *.c +.fi \fR +.P +.RE +.P +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 +.BR \(mir +if +.BR \(mit +was specified or did not support command line +.IR file +arguments with the +.BR \(mit +option. For consistency and simplicity of specification, POSIX.1\(hy2008 +disallows these special cases, and requires that recovery be attempted +the first time each file is edited. +.P +Historically, +.IR vi +initialized the +.BR ` +and +.BR ' +marks, but +.IR ex +did not. This meant that if the first command in +.IR ex +mode was +.BR visual +or if an +.IR ex +command was executed first (for example, +.IR vi ++10 +.IR file ), +.IR 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\(hy2008 requires that they +always be initialized if in open or visual mode, or if in +.IR ex +mode and the edit buffer is not empty. Not initializing it in +.IR 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. +.SS "Addressing" +.P +Historically, +.IR ex +and +.IR vi +accepted the additional addressing forms +.BR '\e/' +and +.BR '\e?' . +They were equivalent to +.BR \(dq//\(dq +and +.BR \(dq??\(dq , +respectively. They are not required by POSIX.1\(hy2008, mostly because nobody can +remember whether they ever did anything different historically. +.P +Historically, +.IR ex +and +.IR vi +permitted an address of zero for several commands, and permitted the +.BR % +address in empty files for others. For consistency, POSIX.1\(hy2008 requires +support for the former in the few commands where it makes sense, and +disallows it otherwise. In addition, because POSIX.1\(hy2008 requires that +.BR % +be logically equivalent to +.BR \(dq1,$\(dq , +it is also supported where it makes sense and disallowed otherwise. +.P +Historically, the +.BR % +address could not be followed by further addresses. For consistency and +simplicity of specification, POSIX.1\(hy2008 requires that additional addresses +be supported. +.P +All of the following are valid +.IR addresses : +.IP "\fR+++\fP" 10 +Three lines after the current line. +.IP "\fR/\fIre\fR/\(mi\fR" 10 +One line before the next occurrence of +.IR re . +.IP "\fR\(mi2\fR" 10 +Two lines before the current line. +.IP "\fR3\0\(mi\|\(mi\|\(mi\|\(mi\02\fR" 10 +Line one (note intermediate negative address). +.IP "\fR1\02\03\fR" 10 +Line six. +.P +Any number of addresses can be provided to commands taking addresses; +for example, +.BR \(dq1,2,3,4,5p\(dq +prints lines 4 and 5, because two is the greatest valid number of +addresses accepted by the +.BR 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 +.BR "3;/foo/;+2print" +will display the first line after line 3 that contains the pattern +.IR foo , +plus the next two lines. Note that the address +.BR "3;" +must be evaluated before being discarded because the search origin for +the +.BR /foo/ +command depends on this. +.P +Historically, values could be added to addresses by including them +after one or more +<blank> +characters; for example, +.BR "3\0\(mi\05p" +wrote the seventh line of the file, and +.BR "/foo/\05" +was the same as +.BR "/foo/+5" . +However, only absolute values could be added; for example, +.BR "5\0/foo/" +was an error. POSIX.1\(hy2008 requires conformance to historical practice. +Address offsets are separately specified from addresses because they +could historically be provided to visual mode search commands. +.P +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\(hy2008 requires it for leading +<semicolon> +addresses as well. +.P +Historically, +.IR ex +and +.IR vi +accepted the +.BR '^' +character as both an address and as a flag offset for commands. In both +cases it was identical to the +.BR '\(mi' +character. POSIX.1\(hy2008 does not require or prohibit this behavior. +.P +Historically, the enhancements to basic regular expressions could be +used in addressing; for example, +.BR '~' , +.BR '\e<' , +and +.BR '\e>' . +POSIX.1\(hy2008 requires conformance to historical practice; that is, that +regular expression usage be consistent, and that regular expression +enhancements be supported wherever regular expressions are used. +.SS "Command Line Parsing in ex" +.P +Historical +.IR ex +command parsing was even more complex than that described here. POSIX.1\(hy2008 +requires the subset of the 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 obscure, at best.) +Historical implementations will require changes in order to comply with +POSIX.1\(hy2008; however, users are not expected to notice any of these changes. +Most of the complexity in +.IR ex +parsing is to handle three special termination cases: +.IP " 1." 4 +The +.BR ! , +.BR global , +.BR v , +and the filter versions of the +.BR read +and +.BR write +commands are delimited by +<newline> +characters (they can contain +<vertical-line> +characters that are usually shell pipes). +.IP " 2." 4 +The +.BR ex , +.BR edit , +.BR next , +and +.BR visual +in open and visual mode commands all take +.IR ex +commands, optionally containing +<vertical-line> +characters, as their first arguments. +.IP " 3." 4 +The +.BR s +command takes a regular expression as its first argument, and uses the +delimiting characters to delimit the command. +.P +Historically, +<vertical-line> +characters in the +.BR + \c +.IR command +argument of the +.BR ex , +.BR edit , +.BR next , +.BR vi , +and +.BR visual +commands, and in the +.IR pattern +and +.IR replacement +parts of the +.BR s +command, did not delimit the command, and in the filter cases for +.BR read +and +.BR write , +and the +.BR ! , +.BR global , +and +.BR v +commands, they did not delimit the command at all. For example, the +following commands are all valid: +.sp +.RS 4 +.nf +\fB +\fB:\fRedit +25 | s/abc/ABC/ file.c +\fB:\fRs/ | /PIPE/ +\fB:\fRread !spell % | columnate +\fB:\fRglobal/pattern/p | l +\fB:\fRs/a/b/ | s/c/d | set +.fi \fR +.P +.RE +.P +Historically, empty or +<blank> +filled lines in +.BR .exrc +files and +.BR source d +files (as well as +.IR EXINIT +variables and +.IR ex +command scripts) were treated as default commands; that is, +.BR print +commands. POSIX.1\(hy2008 specifically requires that they be ignored when +encountered in +.BR .exrc +and +.BR source d +files to eliminate a common source of new user error. +.P +Historically, +.IR ex +commands with multiple adjacent (or +<blank>-separated) +vertical lines were handled oddly when executed from +.IR ex +mode. For example, the command +.BR "|||" +<carriage-return>, +when the cursor was on line 1, displayed lines 2, 3, and 5 of the file. +In addition, the command +.BR | +would only display the line after the next line, instead of the next +two lines. The former worked more logically when executed from +.IR vi +mode, and displayed lines 2, 3, and 4. POSIX.1\(hy2008 requires the +.IR 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. +.P +Historically, +.IR ex +permitted a single extra +<colon> +as a leading command character; for example, +.BR ":g/pattern/:p" +was a valid command. POSIX.1\(hy2008 generalizes this to require that any number +of leading +<colon> +characters be stripped. +.P +Historically, any prefix of the +.BR delete +command could be followed without intervening +<blank> +characters by a flag character because in the command +.BR "d\0p" , +.IR p +is interpreted as the buffer +.IR p . +POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR k +command could be followed by the mark name without intervening +<blank> +characters. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR s +command could be immediately followed by flag and option characters; +for example, +.BR "s/e/E/|s|sgc3p" +was a valid command. However, flag characters could not stand alone; +for example, the commands +.BR sp +and +.BR s\0l +would fail, while the command +.BR sgp +and +.BR "s\0gl" +would succeed. (Obviously, the +.BR '#' +flag character was used as a delimiter character if it followed the +command.) Another issue was that option characters had to precede flag +characters even when the command was fully specified; for example, the +command +.BR s/e/E/pg +would fail, while the command +.BR s/e/E/gp +would succeed. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the first command name that had a prefix matching the +input from the user was the executed command; for example, +.BR ve , +.BR ver , +and +.BR vers +all executed the +.BR version +command. Commands were in a specific order, however, so that +.BR a +matched +.BR append , +not +.BR abbreviate . +POSIX.1\(hy2008 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. +.P +Historical implementations of +.IR ex +and +.IR vi +did not correctly handle multiple +.IR ex +commands, separated by +<vertical-line> +characters, that entered or exited visual mode or the editor. Because +implementations of +.IR vi +exist that do not exhibit this failure mode, POSIX.1\(hy2008 does not permit it. +.P +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 +.BR '!' +character, except as specified for the exceptions, the +.BR delete , +.BR k , +and +.BR s +commands. +.P +Historically, the repeated execution of the +.IR ex +default +.BR print +commands (\c +<control>\(hyD, +.IR 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\(hy2008 does not require this behavior because it +may be impossible in some situations; however, implementations are +strongly encouraged to provide this semantic if possible. +.P +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: +.sp +.RS 4 +.nf +\fB +:edit +25 file.c | s/abc/ABC/ | 1 +.fi \fR +.P +.RE +.P +was a valid command, and the substitution was attempted in the newly +edited file. POSIX.1\(hy2008 requires conformance to historical practice. The +following commands are examples that exercise the +.IR ex +parser: +.sp +.RS 4 +.nf +\fB +echo 'foo | bar' > file1; echo 'foo/bar' > file2; +vi +:edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\e//SLASH/ | wq +.fi \fR +.P +.RE +.P +Historically, there was no protection in editor implementations to +avoid +.IR ex +.BR global , +.BR v , +.BR @ , +or +.BR * +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\(hy2008 requires that changing the edit buffer during a +.BR global +or +.BR v +command, or during a +.BR @ +or +.BR * +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. +.P +The +.IR ex +command quoting required by POSIX.1\(hy2008 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, +.BR ":edit\0foo\e\e\e\0bar" +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 +.BR edit , +.BR ex , +.BR next , +or +.BR visual +command at all. POSIX.1\(hy2008 extends historical practice, requiring that +quoting behavior be made consistent across all +.IR ex +commands, except for the +.BR map , +.BR unmap , +.BR abbreviate , +and +.BR unabbreviate +commands, which historically used +<control>\(hyV +instead of +<backslash> +characters for quoting. For those four commands, POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Backslash quoting in +.IR ex +is non-intuitive. +<backslash>-escapes +are ignored unless they escape a special character; for example, when +performing +.IR file +argument expansion, the string +.BR \(dq\e\e%\(dq +is equivalent to +.BR '\e%' , +not \fR"\e<\fIcurrent\ pathname\fR>"\fR. +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 +.BR '\el' +sequence in substitute replacement patterns, because the character +.BR 'l' +is not special to any parsing layer above it. +.P +<control>\(hyV +quoting in +.IR ex +is slightly different from backslash quoting. In the four commands +where +<control>\(hyV +quoting applies (\c +.BR abbreviate , +.BR unabbreviate , +.BR map , +and +.BR unmap ), +any character may be escaped by a +<control>\(hyV +whether it would have a special meaning or not. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historical implementations of the editor did not require delimiters +within character classes to be escaped; for example, the command +.BR ":s/[/]//" +on the string +.BR \(dqxxx/yyy\(dq +would delete the +.BR '/' +from the string. POSIX.1\(hy2008 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. +.P +Historically, quoting +<newline> +characters in +.IR 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 +.IR ex +commands. However, some +.IR ex +commands (for example, +.BR s , +.BR map , +and +.BR abbreviation ) +permitted +<newline> +characters to be escaped (although in the case of +.BR map +and +.BR abbreviation , +<control>\(hyV +characters escaped them instead of +<backslash> +characters). This was true in not only the command line, but also +.BR .exrc +and +.BR source d +files. For example, the command: +.sp +.RS 4 +.nf +\fB +map = foo<control-V><newline>bar +.fi \fR +.P +.RE +.P +would succeed, although it was sometimes difficult to get the +<control>\(hyV +and the inserted +<newline> +passed to the +.IR ex +parser. For consistency and simplicity of specification, POSIX.1\(hy2008 requires +that it be possible to escape +<newline> +characters in +.IR ex +commands at all times, using +<backslash> +characters for most +.IR ex +commands, and using +<control>\(hyV +characters for the +.BR map +and +.BR abbreviation +commands. For example, the command +.BR print \c +<newline>\c +.BR list +is required to be parsed as the single command +.BR print \c +<newline>\c +.BR list . +While this differs from historical practice, POSIX.1\(hy2008 developers believed +it unlikely that any script or user depended on the historical +behavior. +.P +Historically, an error in a command specified using the +.BR \(mic +option did not cause the rest of the +.BR \(mic +commands to be discarded. POSIX.1\(hy2008 disallows this for consistency with +mapped keys, the +.BR @ , +.BR global , +.BR source , +and +.BR v +commands, the +.IR EXINIT +environment variable, and the +.BR .exrc +files. +.SS "Input Editing in ex" +.P +One of the common uses of the historical +.IR 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\(hy2008 requires that +.IR ex +be implemented using canonical mode input processing, as was done +historically. +.P +POSIX.1\(hy2008 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 +.IR ex , +although they must have the required effect. Implementations that +resolve them after the line has been ended using a +<newline> +or +<control>\(hyM +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. +.P +Historically, when the +.IR eof +character was used to decrement the +.BR autoindent +level, the cursor moved to display the new end of the +.BR autoindent +characters, but did not move the cursor to a new line, nor did it erase +the +<control>\(hyD +character from the line. POSIX.1\(hy2008 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>\(hyD +character on the line should be erased. +.P +POSIX.1\(hy2008 does not require the historical 4 BSD input editing character +``reprint'', traditionally +<control>\(hyR, +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\(hy2008 makes no requirements about this +functionality. Implementations are strongly urged to make this +historical functionality available, if possible. +.P +Historically, +<control>\(hyQ +did not perform a literal next function in +.IR ex , +as it did in +.IR vi . +POSIX.1\(hy2008 requires conformance to historical practice to avoid breaking +historical +.IR ex +scripts and +.BR .exrc +files. +.SS "eof" +.P +Whether the +.IR eof +character immediately modifies the +.BR 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. +.P +The specification of the handling of the +.IR eof +character differs from historical practice only in that +.IR eof +characters are not discarded if they follow normal characters in the +text input. Historically, they were always discarded. +.SS "Command Descriptions in ex" +.P +Historically, several commands (for example, +.BR global , +.BR v , +.BR visual , +.BR s , +.BR write , +.BR wq , +.BR yank , +.BR ! , +.BR < , +.BR > , +.BR & , +and +.BR ~ ) +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\(hy2008 requires this behavior for such commands and +disallows it otherwise, for consistency and simplicity of +specification. +.P +A count to an +.IR 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 +.BR "1,6print" +would fail, but the command +.BR "1print300" +would succeed. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the use of flags in +.IR ex +commands could be obscure. General historical practice was as described +by POSIX.1\(hy2008, but there were some special cases. For instance, the +.BR list , +.BR number , +and +.BR print +commands ignored trailing address offsets; for example, +.BR "3p\0+++#" +would display line 3, and 3 would be the current line after the +execution of the command. The +.BR open +and +.BR visual +commands ignored both the trailing offsets and the trailing flags. +Also, flags specified to the +.BR open +and +.BR visual +commands interacted badly with the +.BR list +edit option, and setting and then unsetting it during the open/visual +session would cause +.IR vi +to stop displaying lines in the specified format. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit any of these +exceptions to the general rule. +.P +POSIX.1\(hy2008 uses the word +.IR copy +in several places when discussing buffers. This is not intended to +imply implementation. +.P +Historically, +.IR ex +users could not specify numeric buffers because of the ambiguity this +would cause; for example, in the command +.BR "3\0delete\02" , +it is unclear whether 2 is a buffer name or a +.IR count . +POSIX.1\(hy2008 requires conformance to historical practice by default, but does +not preclude extensions. +.P +Historically, the contents of the unnamed buffer were frequently +discarded after commands that did not explicitly affect it; for +example, when using the +.BR edit +command to switch files. For consistency and simplicity of +specification, POSIX.1\(hy2008 does not permit this behavior. +.P +The +.IR ex +utility did not historically have access to the numeric buffers, and, +furthermore, deleting lines in +.IR ex +did not modify their contents. For example, if, after doing a delete in +.IR vi , +the user switched to +.IR ex , +did another delete, and then switched back to +.IR vi , +the contents of the numeric buffers would not have changed. POSIX.1\(hy2008 +requires conformance to historical practice. Numeric buffers are +described in the +.IR ex +utility in order to confine the description of buffers to a single +location in POSIX.1\(hy2008. +.P +The metacharacters that trigger shell expansion in +.IR 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 +.BR shellmeta +string edit option. +.P +Historically, +.IR ex +commands executed from +.IR vi +refreshed the screen when it did not strictly need to do so; for +example, +.BR ":!date\0>\0/dev/null" +does not require a screen refresh because the output of the UNIX +.IR date +command requires only a single line of the screen. POSIX.1\(hy2008 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. +.SS "Abbreviate" +.P +Historical practice was that characters that were entered as part of an +abbreviation replacement were subject to +.BR map +expansions, the +.BR 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\(hy2008 requires conformance to historical practice. +Historical practice was that whenever a non-word character (that had +not been escaped by a +<control>\(hyV) +was entered after a word character, +.IR 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. +.P +This means that, for the abbreviation to work, the +.IR lhs +must end with a word character, there can be no transitions from word +to non-word characters (or \fIvice versa\fP) other than between the +last and next-to-last characters in the +.IR lhs , +and there can be no +<blank> +characters in the +.IR lhs . +In addition, because of the historical quoting rules, it was impossible +to enter a literal +<control>\(hyV +in the +.IR lhs . +POSIX.1\(hy2008 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. +.br +.P +For example, the following abbreviations will work: +.sp +.RS 4 +.nf +\fB +:ab (p REPLACE +:ab p REPLACE +:ab ((p REPLACE +.fi \fR +.P +.RE +.P +The following abbreviations will not work: +.sp +.RS 4 +.nf +\fB +:ab ( REPLACE +:ab (pp REPLACE +.fi \fR +.P +.RE +.P +Historical practice is that words on the +.IR vi +colon command line were subject to abbreviation expansion, including +the arguments to the +.BR abbrev +(and more interestingly) the +.BR 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\(hy2008. However, the following sequence: +.sp +.RS 4 +.nf +\fB +:ab foo bar +:ab foo baz +.fi \fR +.P +.RE +.P +resulted in the addition of an abbreviation of +.BR \(dqbaz\(dq +for the string +.BR \(dqbar\(dq +in historical +.IR ex /\c +.IR vi , +and the sequence: +.sp +.RS 4 +.nf +\fB +:ab foo1 bar +:ab foo2 bar +:unabbreviate foo2 +.fi \fR +.P +.RE +.P +deleted the abbreviation +.BR \(dqfoo1\(dq , +not +.BR \(dqfoo2\(dq . +These behaviors are not permitted by POSIX.1\(hy2008 because they clearly violate +the expectations of the user. +.P +It was historical practice that +<control>\(hyV, +not +<backslash>, +characters be interpreted as escaping subsequent characters in the +.BR abbreviate +command. POSIX.1\(hy2008 requires conformance to historical practice; however, it +should be noted that an abbreviation containing a +<blank> +will never work. +.SS "Append" +.P +Historically, any text following a +<vertical-line> +command separator after an +.BR append , +.BR change , +or +.BR insert +command became part of the insert text. For example, in the command: +.sp +.RS 4 +.nf +\fB +:g/pattern/append|stuff1 +.fi \fR +.P +.RE +.P +a line containing the text +.BR \(dqstuff1\(dq +would be appended to each line matching pattern. It was also +historically valid to enter: +.sp +.RS 4 +.nf +\fB +:append|stuff1 +stuff2 +\&. +.fi \fR +.P +.RE +.P +and the text on the +.IR ex +command line would be appended along with the text inserted after it. +There was an historical bug, however, that the user had to enter two +terminating lines (the +.BR '.' +lines) to terminate text input mode in this case. POSIX.1\(hy2008 requires +conformance to historical practice, but disallows the historical need +for multiple terminating lines. +.SS "Change" +.P +See the RATIONALE for the +.BR append +command. Historical practice for cursor positioning after the change +command when no text is input, is as described in POSIX.1\(hy2008. However, one +System V implementation is known to have been modified such that the +cursor is positioned on the first address specified, and not on the +line before the first address. POSIX.1\(hy2008 disallows this modification for +consistency. +.P +Historically, the +.BR change +command did not support buffer arguments, although some implementations +allow the specification of an optional buffer. This behavior is neither +required nor disallowed by POSIX.1\(hy2008. +.SS "Change Directory" +.P +A common extension in +.IR ex +implementations is to use the elements of a +.BR cdpath +edit option as prefix directories for +.IR path +arguments to +.BR chdir +that are relative pathnames and that do not have +.BR '.' +or +.BR \(dq..\(dq +as their first component. Elements in the +.BR cdpath +edit option are +<colon>-separated. +The initial value of the +.BR cdpath +edit option is the value of the shell +.IR CDPATH +environment variable. This feature was not included in POSIX.1\(hy2008 because it +does not exist in any of the implementations considered historical +practice. +.SS "Copy" +.P +Historical implementations of +.IR ex +permitted copies to lines inside of the specified range; for example, +.BR ":2,5copy3" +was a valid command. POSIX.1\(hy2008 requires conformance to historical +practice. +.SS "Delete" +.P +POSIX.1\(hy2008 requires support for the historical parsing of a +.BR delete +command followed by flags, without any intervening +<blank> +characters. For example: +.IP "\fB1dp\fP" 8 +Deletes the first line and prints the line that was second. +.IP "\fB1delep\fP" 8 +As for +.BR 1dp . +.IP "\fB1d\fP" 8 +Deletes the first line, saving it in buffer +.IR p . +.IP "\fB1d\0p1l\fP" 8 +(Pee-one-ell.) Deletes the first line, saving it in buffer +.IR p , +and listing the line that was second. +.SS "Edit" +.P +Historically, any +.IR ex +command could be entered as a +.BR + \c +.IR command +argument to the +.BR edit +command, although some (for example, +.BR insert +and +.BR append ) +were known to confuse historical implementations. For consistency and +simplicity of specification, POSIX.1\(hy2008 requires that any command be +supported as an argument to the +.BR edit +command. +.P +Historically, the command argument was executed with the current line +set to the last line of the file, regardless of whether the +.BR edit +command was executed from visual mode or not. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historically, the +.BR + \c +.IR command +specified to the +.BR edit +and +.BR next +commands was delimited by the first +<blank>, +and there was no way to quote them. For consistency, POSIX.1\(hy2008 requires +that the usual +.IR ex +backslash quoting be provided. +.P +Historically, specifying the +.BR + \c +.IR command +argument to the edit command required a filename to be specified as +well; for example, +.BR ":edit\0+100" +would always fail. For consistency and simplicity of specification, +POSIX.1\(hy2008 does not permit this usage to fail for that reason. +.P +Historically, only the cursor position of the last file edited was +remembered by the editor. POSIX.1\(hy2008 requires that this be supported; +however, implementations are permitted to remember and restore the +cursor position for any file previously edited. +.SS "File" +.P +Historical versions of the +.IR ex +editor +.BR file +command displayed a current line and number of lines in the edit buffer +of 0 when the file was empty, while the +.IR vi +<control>\(hyG +command displayed a current line and number of lines in the edit buffer +of 1 in the same situation. POSIX.1\(hy2008 does not permit this discrepancy, +instead requiring that a message be displayed indicating that the file +is empty. +.SS "Global" +.P +The two-pass operation of the +.BR global +and +.BR v +commands is not intended to imply implementation, only the required +result of the operation. +.P +The current line and column are set as specified for the individual +.IR ex +commands. This requirement is cumulative; that is, the current line and +column must track across all the commands executed by the +.BR global +or +.BR v +commands. +.SS "Insert" +.P +See the RATIONALE for the +.BR append +command. +.P +Historically, +.BR insert +could not be used with an address of zero; that is, not when the edit +buffer was empty. POSIX.1\(hy2008 requires that this command behave consistently +with the +.BR append +command. +.SS "Join" +.P +The action of the +.BR 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. +.SS "List" +.P +The historical output of the +.BR list +command was potentially ambiguous. The standard developers believed +correcting this to be more important than adhering to historical +practice, and POSIX.1\(hy2008 requires unambiguous output. +.SS "Map" +.P +Historically, command mode maps only applied to command names; for +example, if the character +.BR 'x' +was mapped to +.BR 'y' , +the command +.BR fx +searched for the +.BR 'x' +character, not the +.BR 'y' +character. POSIX.1\(hy2008 requires this behavior. Historically, entering +<control>\(hyV +as the first character of a +.IR vi +command was an error. Several implementations have extended the +semantics of +.IR vi +such that +<control>\(hyV +means that the subsequent command character is not mapped. This is +permitted, but not required, by POSIX.1\(hy2008. Regardless, using +<control>\(hyV +to escape the second or later character in a sequence of characters +that might match a +.BR map +command, or any character in text input mode, is historical practice, +and stops the entered keys from matching a map. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historical implementations permitted digits to be used as a +.BR map +command +.IR lhs , +but then ignored the map. POSIX.1\(hy2008 requires that the mapped digits not be +ignored. +.P +The historical implementation of the +.BR map +command did not permit +.BR 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\(hy2008. +.P +Historically, mapped characters were remapped unless the +.BR remap +edit option was not set, or the prefix of the mapped characters matched +the mapping characters; for example, in the +.BR map : +.sp +.RS 4 +.nf +\fB +:map ab abcd +.fi \fR +.P +.RE +.P +the characters +.BR \(dqab\(dq +were used as is and were not remapped, but the characters +.BR \(dqcd\(dq +were mapped if appropriate. This can cause infinite loops in the +.IR vi +mapping mechanisms. POSIX.1\(hy2008 requires conformance to historical practice, +and that such loops be interruptible. +.P +Text input maps had the same problems with expanding the +.IR lhs +for the +.IR ex +.BR map! +and +.BR unmap! +command as did the +.IR ex +.BR abbreviate +and +.BR unabbreviate +commands. See the RATIONALE for the +.IR ex +.BR abbreviate +command. POSIX.1\(hy2008 requires similar modification of some historical +practice for the +.BR map +and +.BR unmap +commands, as described for the +.BR abbreviate +and +.BR unabbreviate +commands. +.P +Historically, +.BR map s +that were subsets of other +.BR map s +behaved differently depending on the order in which they were defined. +For example: +.sp +.RS 4 +.nf +\fB +:map! ab short +:map! abc long +.fi \fR +.P +.RE +.P +would always translate the characters +.BR \(dqab\(dq +to +.BR \(dqshort\(dq , +regardless of how fast the characters +.BR \(dqabc\(dq +were entered. If the entry order was reversed: +.sp +.RS 4 +.nf +\fB +:map! abc long +:map! ab short +.fi \fR +.P +.RE +.P +the characters +.BR \(dqab\(dq +would cause the editor to pause, waiting for the completing +.BR 'c' +character, and the characters might never be mapped to +.BR \(dqshort\(dq . +For consistency and simplicity of specification, POSIX.1\(hy2008 requires that +the shortest match be used at all times. +.P +The length of time the editor spends waiting for the characters to +complete the +.IR 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 +.IR vi +have added a +.BR 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 +.IR vi +text input mode, +.BR map s +starting with +<ESC> +characters are generally exempted from this timeout period, or, at +least timed out differently. +.SS "Mark" +.P +Historically, users were able to set the ``previous context'' marks +explicitly. In addition, the +.IR ex +commands +.BR '' +and +.BR '` +and the +.IR vi +commands +.BR '' , +.BR `` , +.BR `' , +and +.BR '` +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\(hy2008 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\(hy2008 requires +conformance to historical practice. +.P +The description of the special events that set the +.BR ` +and +.BR ' +marks matches historical practice. For example, historically the +command +.BR "/a/,/b/" +did not set the +.BR ` +and +.BR ' +marks, but the command +.BR "/a/,/b/delete" +did. +.SS "Next" +.P +Historically, any +.IR ex +command could be entered as a +.BR + \c +.IR command +argument to the +.BR next +command, although some (for example, +.BR insert +and +.BR append ) +were known to confuse historical implementations. POSIX.1\(hy2008 requires that +any command be permitted and that it behave as specified. The +.BR next +command can accept more than one file, so usage such as: +.sp +.RS 4 +.nf +\fB +next `ls [abc] ` +.fi \fR +.P +.RE +.P +is valid; it need not be valid for the +.BR edit +or +.BR read +commands, for example, because they expect only one filename. +.P +Historically, the +.BR next +command behaved differently from the +.BR :rewind +command in that it ignored the force flag if the +.BR autowrite +flag was set. For consistency, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR next +command positioned the cursor as if the file had never been edited +before, regardless. POSIX.1\(hy2008 does not permit this behavior, for +consistency with the +.BR edit +command. +.P +Implementations wanting to provide a counterpart to the +.BR next +command that edited the previous file have used the command +.BR prev[ious], +which takes no +.IR file +argument. POSIX.1\(hy2008 does not require this command. +.SS "Open" +.P +Historically, the +.BR open +command would fail if the +.BR open +edit option was not set. POSIX.1\(hy2008 does not mention the +.BR 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 +.IR ex +mode. For consistency, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, entering open mode from the command line (that is, +.IR vi +.BR +open ) +resulted in anomalous behaviors; for example, the +.IR ex +file and +.IR set +commands, and the +.IR vi +command +<control>\(hyG +did not work. For consistency, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR open +command only permitted +.BR '/' +characters to be used as the search pattern delimiter. For consistency, +POSIX.1\(hy2008 requires that the search delimiters used by the +.BR s , +.BR global , +and +.BR v +commands be accepted as well. +.SS "Preserve" +.P +The +.BR 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\(hy2008 requires conformance to historical practice. +.P +Historical documentation stated that mail was not sent to the user when +preserve was executed; however, historical implementations did send +mail in this case. POSIX.1\(hy2008 requires conformance to the historical +implementations. +.SS "Print" +.P +The writing of NUL by the +.BR print +command is not specified as a special case because the standard +developers did not want to require +.IR ex +to support NUL characters. Historically, characters were displayed +using the ARPA standard mappings, which are as follows: +.IP " 1." 4 +Printable characters are left alone. +.IP " 2." 4 +Control characters less than \e177 are represented as +.BR '^' +followed by the character offset from the +.BR '@' +character in the ASCII map; for example, \e007 is represented as +.BR '^G' . +.IP " 3." 4 +\e177 is represented as +.BR '^' +followed by +.BR '?' . +.P +The display of characters having their eighth bit set was less +standard. Existing implementations use hex (0x00), octal (\e000), and a +meta-bit display. (The latter displayed bytes that had their eighth bit +set as the two characters +.BR \(dqM\(mi\(dq +followed by the seven-bit display as described above.) The latter +probably has the best claim to historical practice because it was used +for the +.BR \(miv +option of 4 BSD and 4 BSD-derived versions of the +.IR cat +utility since 1980. +.P +No specific display format is required by POSIX.1\(hy2008. +.P +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, for instance, +.BR \(dq^I\(dq +for the +<tab>. +Implementations are encouraged to conform to historical practice in the +absence of any strong reason to diverge. +.P +Historically, all +.IR ex +commands beginning with the letter +.BR 'p' +could be entered using capitalized versions of the commands; for +example, +.BR P[rint] , +.BR Pre[serve] , +and +.BR Pu[t] +were all valid command names. POSIX.1\(hy2008 permits, but does not require, this +historical practice because capital forms of the commands are used by +some implementations for other purposes. +.SS "Put" +.P +Historically, an +.IR ex +.BR put +command, executed from open or visual mode, was the same as the open or +visual mode +.BR P +command, if the buffer was named and was cut in character mode, and the +same as the +.BR 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 +.BR put , +and the buffer was handled as if in line mode, but it was possible to +get extremely anomalous behavior. In addition, using the +.BR Q +command to switch into +.IR ex +mode, and then doing a +.BR put +often resulted in errors as well, such as appending text that was +unrelated to the (supposed) contents of the buffer. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit these behaviors. All +.IR ex +.BR 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. +.SS "Read" +.P +Historically, an +.IR ex +.BR 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\(hy2008 does not permit this behavior. +Historically, a +.BR 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\(hy2008 does not permit this +behavior. +.P +Historical implementations of +.IR ex +were unable to undo +.BR read +commands that read from the output of a program. For consistency, POSIX.1\(hy2008 +does not permit this behavior. +.P +Historically, the +.IR ex +and +.IR vi +message after a successful +.BR read +or +.BR write +command specified ``characters'', not ``bytes''. POSIX.1\(hy2008 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. +.P +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 +.IR ex +and +.IR vi +were originally written). Because the historical +.IR ex +evaluated +.BR read! +and +.BR read\0! +equivalently, there can be no optional way to force the read. POSIX.1\(hy2008 +permits, but does not require, this behavior. +.SS "Recover" +.P +Some historical implementations of the editor permitted users to +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\(hy2008 in requiring that the edit buffer be treated as already +modified is to prevent this user error. +.SS "Rewind" +.P +Historical implementations supported the +.BR rewind +command when the user was editing the first file in the list; that is, +the file that the +.BR rewind +command would edit. POSIX.1\(hy2008 requires conformance to historical practice. +.SS "Substitute" +.P +Historically, +.IR ex +accepted an +.BR r +option to the +.BR s +command. The effect of the +.BR r +option was to use the last regular expression used in any command as +the pattern, the same as the +.BR ~ +command. The +.BR r +option is not required by POSIX.1\(hy2008. Historically, the +.BR c +and +.BR g +options were toggled; for example, the command +.BR ":s/abc/def/" +was the same as +.BR "s/abc/def/ccccgggg" . +For simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +.P +The tilde command is often used to replace the last search RE. For +example, in the sequence: +.sp +.RS 4 +.nf +\fB +s/red/blue/ +/green +~ +.fi \fR +.P +.RE +.P +the +.BR ~ +command is equivalent to: +.sp +.RS 4 +.nf +\fB +s/green/blue/ +.fi \fR +.P +.RE +.P +Historically, +.IR ex +accepted all of the following forms: +.sp +.RS 4 +.nf +\fB +s/abc/def/ +s/abc/def +s/abc/ +s/abc +.fi \fR +.P +.RE +.P +POSIX.1\(hy2008 requires conformance to this historical practice. +.P +The +.BR s +command presumes that the +.BR '^' +character only occupies a single column in the display. Much of the +.IR ex +and +.IR 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. +.P +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-\c +<blank>. +For consistency and simplicity of specification, POSIX.1\(hy2008 requires that +the final column position always be set to the first non-\c +<blank>. +.SS "Set" +.P +Historical implementations redisplayed all of the options for each +occurrence of the +.BR all +keyword. POSIX.1\(hy2008 permits, but does not require, this behavior. +.SS "Tag" +.P +No requirement is made as to where +.IR ex +and +.IR vi +shall look for the file referenced by the tag entry. Historical +practice has been to look for the path found in the +.BR 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. +.P +Because users often specify many different tags files, some of which +need not be relevant or exist at any particular time, POSIX.1\(hy2008 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 +.BR tag +edit option is changed. +.P +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\(hy2008 does not permit this behavior, +requiring that the name be the only factor in the decision. +.P +Historically, +.IR vi +only searched for tags in the current file from the current cursor to +the end of the file, and therefore, if the +.BR wrapscan +option was not set, tags occurring before the current cursor were not +found. POSIX.1\(hy2008 considers this a bug, and implementations are required to +search for the first occurrence in the file, regardless. +.SS "Undo" +.P +The +.BR undo +description deliberately uses the word ``modified''. The +.BR undo +command is not intended to undo commands that replace the contents of +the edit buffer, such as +.BR edit , +.BR next , +.BR tag , +or +.BR recover . +.P +Cursor positioning after the +.BR undo +command was inconsistent in the historical +.IR vi , +sometimes attempting to restore the original cursor position (\c +.BR global , +.BR undo , +and +.BR 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\(hy2008 requires +a simplified behavior for consistency and simplicity of specification. +.SS "Version" +.P +The +.BR 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. +.SS "Write" +.P +Historically, the +.IR ex +and +.IR vi +message after a successful +.BR read +or +.BR write +command specified ``characters'', not ``bytes''. POSIX.1\(hy2008 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. +.P +Implementation-defined tests are permitted so that implementations +can make additional checks; for example, for locks or file modification +times. +.P +Historically, attempting to append to a nonexistent file caused an +error. It has been left unspecified in POSIX.1\(hy2008 to permit implementations +to let the +.BR write +succeed, so that the append semantics are similar to those of the +historical +.IR csh . +.P +Historical +.IR vi +permitted empty edit buffers to be written. However, since the way +.IR vi +got around dealing with ``empty'' files was to always have a line in +the edit buffer, no matter what, it wrote them as files of a single, +empty line. POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, +.IR ex +restored standard output and standard error to their values as of when +.IR ex +was invoked, before writes to programs were performed. This could +disturb the terminal configuration as well as be a security issue for +some terminals. POSIX.1\(hy2008 does not permit this, requiring that the program +output be captured and displayed as if by the +.IR ex +.BR print +command. +.SS "Adjust Window" +.P +Historically, the line count was set to the value of the +.BR scroll +option if the type character was end-of-file. This feature was broken +on most historical implementations long ago, however, and is not +documented anywhere. For this reason, POSIX.1\(hy2008 is resolutely silent. +.P +Historically, the +.BR z +command was +<blank>-sensitive +and +.BR z\0+ +and +.BR z\0\(mi +did different things than +.BR z+ +and +.BR z\(mi +because the type could not be distinguished from a flag. (The commands +.BR z\0. +and +.BR z\0= +were historically invalid.) POSIX.1\(hy2008 requires conformance to this +historical practice. +.P +Historically, the +.BR z +command was further +<blank>-sensitive +in that the +.IR count +could not be +<blank>-delimited; +for example, the commands +.BR z=\05 +and +.BR z\(mi\05 +were also invalid. Because the +.IR count +is not ambiguous with respect to either the type character or the +flags, this is not permitted by POSIX.1\(hy2008. +.SS "Escape" +.P +Historically, +.IR ex +filter commands only read the standard output of the commands, letting +standard error appear on the terminal as usual. The +.IR vi +utility, however, read both standard output and standard error. POSIX.1\(hy2008 +requires the latter behavior for both +.IR ex +and +.IR vi , +for consistency. +.SS "Shift Left and Shift Right" +.P +Historically, it was possible to add shift characters to increase the +effect of the command; for example, +.BR <<< +outdented (or +.BR >>> +indented) the lines 3 levels of indentation instead of the default 1. +POSIX.1\(hy2008 requires conformance to historical practice. +.SS "<control>\(hyD" +.P +Historically, the +<control>\(hyD +command erased the prompt, providing the user with an unbroken +presentation of lines from the edit buffer. This is not required by +POSIX.1\(hy2008; implementations are encouraged to provide it if possible. +Historically, the +<control>\(hyD +command took, and then ignored, a +.IR count . +POSIX.1\(hy2008 does not permit this behavior. +.SS "Write Line Number" +.P +Historically, the +.IR ex +.BR = +command, when executed in +.IR 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\(hy2008 does +not permit this behavior. +.SS "Execute" +.P +Historically, +.IR ex +did not correctly handle the inclusion of text input commands (that is, +.BR append , +.BR insert , +and +.BR change ) +in executed buffers. POSIX.1\(hy2008 does not permit this exclusion for +consistency. +.P +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 did not support self-modifying +code. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR @ +command took a range of lines, and the +.BR @ +buffer was executed once per line, with the current line (\c +.BR '.' ) +set to each specified line. POSIX.1\(hy2008 requires conformance to historical +practice. +.P +Some historical implementations did not notice if errors occurred +during buffer execution. This, coupled with the ability to specify a +range of lines for the +.IR ex +.BR @ +command, makes it trivial to cause them to drop +.BR core . +POSIX.1\(hy2008 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 +.IR ex +.BR :edit +command). +.SS "Regular Expressions in ex" +.P +Historical practice is that the characters in the replacement part of +the last +.BR s +command\(emthat is, those matched by entering a +.BR '~' +in the regular expression\(emwere not further expanded by the regular +expression engine. So, if the characters contained the string +.BR \(dqa.,\(dq +they would match +.BR 'a' +followed by +.BR \(dq.,\(dq +and not +.BR 'a' +followed by any character. POSIX.1\(hy2008 requires conformance to historical +practice. +.SS "Edit Options in ex" +.P +The following paragraphs describe the historical behavior of some edit +options that were not, for whatever reason, included in POSIX.1\(hy2008. +Implementations are strongly encouraged to only use these names if the +functionality described here is fully supported. +.IP "\fBextended\fP" 10 +The +.BR extended +edit option has been used in some implementations of +.IR vi +to provide extended regular expressions instead of basic regular +expressions This option was omitted from POSIX.1\(hy2008 because it is not +widespread historical practice. +.IP "\fBflash\fP" 10 +The +.BR flash +edit option historically caused the screen to flash instead of beeping +on error. This option was omitted from POSIX.1\(hy2008 because it is not found in +some historical implementations. +.IP "\fBhardtabs\fP" 10 +The +.BR hardtabs +edit option historically defined the number of columns between hardware +tab settings. This option was omitted from POSIX.1\(hy2008 because it was +believed to no longer be generally useful. +.IP "\fBmodeline\fP" 10 +The +.BR modeline +(sometimes named +.BR modelines ) +edit option historically caused +.IR ex +or +.IR 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. +.IP "\fBopen\fP" 10 +The +.BR open +edit option historically disallowed the +.IR ex +.BR open +and +.BR visual +commands. This edit option was omitted because these commands are +required by POSIX.1\(hy2008. +.IP "\fBoptimize\fP" 10 +The +.BR 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\(hy2008 because it was intended for terminals +without addressable cursors, which are rarely, if ever, still used. +.IP "\fBruler\fP" 10 +The +.BR ruler +edit option has been used in some implementations of +.IR vi +to present a current row/column ruler for the user. This option was +omitted from POSIX.1\(hy2008 because it is not widespread historical practice. +.IP "\fBsourceany\fP" 10 +The +.BR sourceany +edit option historically caused +.IR ex +or +.IR 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. +.IP "\fBtimeout\fP" 10 +The +.BR 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\(hy2008 because its behavior is +now standard, it is not widely useful, and it was rarely documented. +.IP "\fBverbose\fP" 10 +The +.BR verbose +edit option has been used in some implementations of +.IR vi +to cause +.IR 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 +.IR vi +only alerted the terminal and presented no message for such errors. The +historical editor option +.BR 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\(hy2008 because it is not widespread historical practice; however, +implementors are encouraged to use it if they wish to provide error +messages for naive users. +.IP "\fBwraplen\fP" 10 +The +.BR wraplen +edit option has been used in some implementations of +.IR 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\(hy2008 +because it is not widespread historical practice; however, implementors +are encouraged to use it if they add this functionality. +.SS "autoindent, ai" +.P +Historically, the command +.BR 0a +did not do any autoindentation, regardless of the current indentation +of line 1. POSIX.1\(hy2008 requires that any indentation present in line 1 be +used. +.SS "autoprint, ap" +.P +Historically, the +.BR autoprint +edit option was not completely consistent or based solely on +modifications to the edit buffer. Exceptions were the +.BR read +command (when reading from a file, but not from a filter), the +.BR append , +.BR change , +.BR insert , +.BR global , +and +.BR v +commands, all of which were not affected by +.BR autoprint , +and the +.BR tag +command, which was affected by +.BR autoprint . +POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR autoprint +option only applied to the last of multiple commands entered using +<vertical-line> +delimiters; for example, +.BR delete +<newline> +was affected by +.BR autoprint , +but +.BR delete|version +<newline> +was not. POSIX.1\(hy2008 requires conformance to historical practice. +.SS "autowrite, aw" +.P +Appending the +.BR '!' +character to the +.IR ex +.BR next +command to avoid performing an automatic write was not supported in +historical implementations. POSIX.1\(hy2008 requires that the behavior match the +other +.IR ex +commands for consistency. +.SS "ignorecase, ic" +.P +Historical implementations of case-insensitive matching (the +.BR ignorecase +edit option) lead to counter-intuitive situations when uppercase +characters were used in range expressions. Historically, the process +was as follows: +.IP " 1." 4 +Take a line of text from the edit buffer. +.IP " 2." 4 +Convert uppercase to lowercase in text line. +.IP " 3." 4 +Convert uppercase to lowercase in regular expressions, except in +character class specifications. +.IP " 4." 4 +Match regular expressions against text. +.P +This would mean that, with +.BR ignorecase +in effect, the text: +.sp +.RS 4 +.nf +\fB +The cat sat on the mat +.fi \fR +.P +.RE +.P +would be matched by +.sp +.RS 4 +.nf +\fB +/^the/ +.fi \fR +.P +.RE +.P +but not by: +.sp +.RS 4 +.nf +\fB +/^[A\(miZ]he/ +.fi \fR +.P +.RE +.P +For consistency with other commands implementing regular expressions, +POSIX.1\(hy2008 does not permit this behavior. +.SS "paragraphs, para" +.P +The ISO\ POSIX\(hy2:\|1993 standard made the default +.BR paragraphs +and +.BR sections +edit options implementation-defined, arguing they were historically +oriented to the UNIX system +.IR troff +text formatter, and a ``portable user'' could use the +.BR { , +.BR } , +.BR [[ , +.BR ]] , +.BR ( , +and +.BR ) +commands in open or visual mode and have the cursor stop in unexpected +places. POSIX.1\(hy2008 specifies their values in the POSIX locale because the +unusual grouping (they only work when grouped into two characters at a +time) means that they cannot be used for general-purpose movement, +regardless. +.SS "readonly" +.P +Implementations are encouraged to provide the best possible information +to the user as to the read-only status of the file, with the exception +that they should not consider the current special privileges of the +process. This provides users with a safety net because they must force +the overwrite of read-only files, even when running with additional +privileges. +.P +The +.BR readonly +edit option specification largely conforms to historical practice. The +only difference is that historical implementations did not notice that +the user had set the +.BR readonly +edit option in cases where the file was already marked read-only for +some reason, and would therefore reinitialize the +.BR readonly +edit option the next time the contents of the edit buffer were +replaced. This behavior is disallowed by POSIX.1\(hy2008. +.SS "report" +.P +The requirement that lines copied to a buffer interact differently than +deleted lines is historical practice. For example, if the +.BR 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. +.P +The requirement that the +.IR ex +.BR global , +.BR v , +.BR open , +.BR undo , +and +.BR visual +commands present reports based on the total number of lines added or +deleted during the command execution, and that commands executed by the +.BR global +and +.BR v +commands not present reports, is historical practice. POSIX.1\(hy2008 extends +historical practice by requiring that buffer execution be treated +similarly. The reasons for this are two-fold. Historically, only the +report by the last command executed from the buffer would be seen by +the user, as each new report would overwrite the last. In addition, the +standard developers believed that buffer execution had more in common +with +.BR global +and +.BR v +commands than it did with other +.IR ex +commands, and should behave similarly, for consistency and simplicity +of specification. +.SS "showmatch, sm" +.P +The length of time the cursor spends on the matching character is +unspecified because the timing capabilities of systems are often +inexact and variable. The time should be long enough for the user to +notice, but not long enough for the user to become annoyed. Some +implementations of +.IR vi +have added a +.BR matchtime +option that permits users to set the number of 0,1 second intervals the +cursor pauses on the matching character. +.SS "showmode" +.P +The +.BR showmode +option has been used in some historical implementations of +.IR ex +and +.IR 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. In addition, a preceding +.BR '*' +character often denoted whether the contents of the edit buffer had +been modified. The latter display has sometimes been part of the +.BR showmode +option, and sometimes based on another option. This option was not +available in the 4 BSD historical implementation of +.IR vi , +but was viewed as generally useful, particularly to novice users, and +is required by POSIX.1\(hy2008. +.P +The +.BR smd +shorthand for the +.BR showmode +option was not present in all historical implementations of the editor. +POSIX.1\(hy2008 requires it, for consistency. +.P +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\(hy2008 permits this behavior for +consistency with historical practice, but implementations are +encouraged to provide a display string for both modes. +.SS "slowopen" +.P +Historically, the +.BR slowopen +option was automatically set if the terminal baud rate was less than +1\|200 baud, or if the baud rate was 1\|200 baud and the +.BR redraw +option was not set. The +.BR 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. Finally, terminals that were sufficiently intelligent +caused the editor to ignore the +.BR slowopen +option. POSIX.1\(hy2008 permits most historical behavior, extending historical +practice to require +.BR slowopen +behaviors if the edit option is set by the user. +.SS "tags" +.P +The default path for tags files is left unspecified as implementations +may have their own +.BR tags +implementations that do not correspond to the historical ones. The +default +.BR tags +option value should probably at least include the file +.BR ./tags . +.SS "term" +.P +Historical implementations of +.IR ex +and +.IR vi +ignored changes to the +.BR term +edit option after the initial terminal information was loaded. This is +permitted by POSIX.1\(hy2008; however, implementations are encouraged to permit +the user to modify their terminal type at any time. +.SS "terse" +.P +Historically, the +.BR terse +edit option optionally provided a shorter, less descriptive error +message, for some error messages. This is permitted, but not required, +by POSIX.1\(hy2008. 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 +.BR edit +option +.BR verbose , +and not +.BR terse . +.SS "window" +.P +In historical implementations, the default for the +.BR window +edit option was based on the baud rate as follows: +.IP " 1." 4 +If the baud rate was less than 1\|200, the +.BR edit +option +.BR w300 +set the window value; for example, the line: +.RS 4 +.sp +.RS 4 +.nf +\fB +set w300=12 +.fi \fR +.P +.RE +.P +would set the window option to 12 if the baud rate was less than +1\|200. +.RE +.IP " 2." 4 +If the baud rate was equal to 1\|200, the +.BR edit +option +.BR w1200 +set the window value. +.IP " 3." 4 +If the baud rate was greater than 1\|200, the +.BR edit +option +.BR w9600 +set the window value. +.P +The +.BR w300 , +.BR w1200 , +and +.BR w9600 +options do not appear in POSIX.1\(hy2008 because of their dependence on specific +baud rates. +.P +In historical implementations, the size of the window displayed by +various commands was related to, but not necessarily the same as, the +.BR window +edit option. For example, the size of the window was set by the +.IR ex +command +.BR "visual 10" , +but it did not change the value of the +.BR window +edit option. However, changing the value of the +.BR window +edit option did change the number of lines that were displayed when the +screen was repainted. POSIX.1\(hy2008 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 +.BR window +edit option. +.SS "wrapmargin, wm" +.P +Historically, the +.BR wrapmargin +option did not affect maps inserting characters that also had +associated +.IR count s; +for example +.BR ":map\0K\05aABC\0DEF" . +Unfortunately, there are widely used maps that depend on this behavior. +For consistency and simplicity of specification, POSIX.1\(hy2008 does not permit +this behavior. +.P +Historically, +.BR wrapmargin +was calculated using the column display width of all characters on the +screen. For example, an implementation using +.BR \(dq^I\(dq +to represent +<tab> +characters when the +.BR list +edit option was set, where +.BR '^' +and +.BR 'I' +each took up a single column on the screen, would calculate the +.BR wrapmargin +based on a value of 2 for each +<tab>. +The +.BR number +edit option similarly changed the effective length of the line as well. +POSIX.1\(hy2008 requires conformance to historical practice. +.P +Earlier versions of this standard allowed for implementations +with bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +.IR "\fIctags\fR\^", +.IR "\fIed\fR\^", +.IR "\fIsed\fR\^", +.IR "\fIsh\fR\^", +.IR "\fIstty\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIaccess\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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 . |