1EX(1P) POSIX Programmer's Manual EX(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 ex - text editor
13
15 ex [-rR][-s | -v][-c command][-t tagstring][-w size][file ...]
16
18 The ex utility is a line-oriented text editor. There are two other
19 modes of the editor-open and visual-in which screen-oriented editing is
20 available. This is described more fully by the ex open and visual com‐
21 mands and in vi .
22 This section uses the term edit buffer to describe the current working
24 text. No specific implementation is implied by this term. All editing
25 changes are performed on the edit buffer, and no changes to it shall
26 affect any file until an editor command writes the file.
27 Certain terminals do not have all the capabilities necessary to support
29 the complete ex definition, such as the full-screen editing commands (
30 visual mode or open mode). When these commands cannot be supported on
31 such terminals, this condition shall not produce an error message such
32 as "not an editor command" or report a syntax error. The implementation
33 may either accept the commands and produce results on the screen that
34 are the result of an unsuccessful attempt to meet the requirements of
35 this volume of IEEE Std 1003.1-2001 or report an error describing the
36 terminal-related deficiency.
37
39 The ex utility shall conform to the Base Definitions volume of
40 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
41 The following options shall be supported:
43 -c command
45 Specify an initial command to be executed in the first edit buf‐
46 fer loaded from an existing file (see the EXTENDED DESCRIPTION
47 section). Implementations may support more than a single -c
48 option. In such implementations, the specified commands shall be
49 executed in the order specified on the command line.
50 -r Recover the named files (see the EXTENDED DESCRIPTION section).
52 Recovery information for a file shall be saved during an editor
53 or system crash (for example, when the editor is terminated by a
54 signal which the editor can catch), or after the use of an ex
55 preserve command.
56 A crash in this context is an unexpected failure of the system or util‐
58 ity that requires restarting the failed system or utility. A system
59 crash implies that any utilities running at the time also crash. In the
60 case of an editor or system crash, the number of changes to the edit
61 buffer (since the most recent preserve command) that will be recovered
62 is unspecified.
63 If no file operands are given and the -t option is not specified, all
65 other options, the EXINIT variable, and any .exrc files shall be
66 ignored; a list of all recoverable files available to the invoking user
67 shall be written, and the editor shall exit normally without further
68 action.
69 -R Set readonly edit option.
71 -s Prepare ex for batch use by taking the following actions:
73 * Suppress writing prompts and informational (but not diagnos‐
75 tic) messages.
76 * Ignore the value of TERM and any implementation default ter‐
78 minal type and assume the terminal is a type incapable of
79 supporting open or visual modes; see the visual command and
80 the description of vi .
81 * Suppress the use of the EXINIT environment variable and the
83 reading of any .exrc file; see the EXTENDED DESCRIPTION sec‐
84 tion.
85 * Suppress autoindentation, ignoring the value of the autoin‐
87 dent edit option.
88 -t tagstring
90 Edit the file containing the specified tagstring; see ctags .
91 The tags feature represented by -t tagstring and the tag command
92 is optional. It shall be provided on any system that also pro‐
93 vides a conforming implementation of ctags; otherwise, the use
94 of -t produces undefined results. On any system, it shall be an
95 error to specify more than a single -t option.
96 -v Begin in visual mode (see vi ).
98 -w size
100 Set the value of the window editor option to size.
101
104 The following operand shall be supported:
105 file A pathname of a file to be edited.
107
110 The standard input consists of a series of commands and input text, as
111 described in the EXTENDED DESCRIPTION section. The implementation may
112 limit each line of standard input to a length of {LINE_MAX}.
113 If the standard input is not a terminal device, it shall be as if the
115 -s option had been specified.
116 If a read from the standard input returns an error, or if the editor
118 detects an end-of-file condition from the standard input, it shall be
119 equivalent to a SIGHUP asynchronous event.
120
122 Input files shall be text files or files that would be text files
123 except for an incomplete last line that is not longer than {LINE_MAX}-1
124 bytes in length and contains no NUL characters. By default, any incom‐
125 plete last line shall be treated as if it had a trailing <newline>. The
126 editing of other forms of files may optionally be allowed by ex imple‐
127 mentations.
128 The .exrc files and source files shall be text files consisting of ex
130 commands; see the EXTENDED DESCRIPTION section.
131 By default, the editor shall read lines from the files to be edited
133 without interpreting any of those lines as any form of editor command.
134
136 The following environment variables shall affect the execution of ex:
137 COLUMNS
139 Override the system-selected horizontal screen size. See the
140 Base Definitions volume of IEEE Std 1003.1-2001, Chapter 8,
141 Environment Variables for valid values and results when it is
142 unset or null.
143 EXINIT Determine a list of ex commands that are executed on editor
145 start-up. See the EXTENDED DESCRIPTION section for more details
146 of the initialization phase.
147 HOME Determine a pathname of a directory that shall be searched for
149 an editor start-up file named .exrc; see the EXTENDED DESCRIP‐
150 TION section.
151 LANG Provide a default value for the internationalization variables
153 that are unset or null. (See the Base Definitions volume of
154 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
155 ables for the precedence of internationalization variables used
156 to determine the values of locale categories.)
157 LC_ALL If set to a non-empty string value, override the values of all
159 the other internationalization variables.
160 LC_COLLATE
162 Determine the locale for the behavior of ranges, equivalence
164 classes, and multi-character collating elements within regular
165 expressions.
166 LC_CTYPE
168 Determine the locale for the interpretation of sequences of
169 bytes of text data as characters (for example, single-byte as
170 opposed to multi-byte characters in arguments and input files),
171 the behavior of character classes within regular expressions,
172 the classification of characters as uppercase or lowercase let‐
173 ters, the case conversion of letters, and the detection of word
174 boundaries.
175 LC_MESSAGES
177 Determine the locale that should be used to affect the format
178 and contents of diagnostic messages written to standard error.
179 LINES Override the system-selected vertical screen size, used as the
181 number of lines in a screenful and the vertical screen size in
182 visual mode. See the Base Definitions volume of
183 IEEE Std 1003.1-2001, Chapter 8, Environment Variables for valid
184 values and results when it is unset or null.
185 NLSPATH
187 Determine the location of message catalogs for the processing of
188 LC_MESSAGES .
189 PATH Determine the search path for the shell command specified in the
191 ex editor commands !, shell, read, and write, and the open and
192 visual mode command !; see the description of command search and
193 execution in Command Search and Execution .
194 SHELL Determine the preferred command line interpreter for use as the
196 default value of the shell edit option.
197 TERM Determine the name of the terminal type. If this variable is
199 unset or null, an unspecified default terminal type shall be
200 used.
201
204 The following term is used in this and following sections to specify
205 command and asynchronous event actions:
206 complete write
208 A complete write is a write of the entire contents of the edit
210 buffer to a file of a type other than a terminal device, or the
211 saving of the edit buffer caused by the user executing the ex
212 preserve command. Writing the contents of the edit buffer to a
213 temporary file that will be removed when the editor exits shall
214 not be considered a complete write.
215 The following actions shall be taken upon receipt of signals:
218 SIGINT If the standard input is not a terminal device, ex shall not
220 write the file or return to command or text input mode, and
221 shall exit with a non-zero exit status.
222 Otherwise, if executing an open or visual text input mode command, ex
224 in receipt of SIGINT shall behave identically to its receipt of the
225 <ESC> character.
226 Otherwise:
228 1. If executing an ex text input mode command, all input lines
230 that have been completely entered shall be resolved into the
231 edit buffer, and any partially entered line shall be dis‐
232 carded.
233 2. If there is a currently executing command, it shall be
235 aborted and a message displayed. Unless otherwise specified
236 by the ex or vi command descriptions, it is unspecified
237 whether any lines modified by the executing command appear
238 modified, or as they were before being modified by the exe‐
239 cuting command, in the buffer.
240 If the currently executing command was a motion command, its
242 associated command shall be discarded.
243 3. If in open or visual command mode, the terminal shall be
245 alerted.
246 4. The editor shall then return to command mode.
248 SIGCONT
250 The screen shall be refreshed if in open or visual mode.
251 SIGHUP If the edit buffer has been modified since the last complete
253 write, ex shall attempt to save the edit buffer so that it can
254 be recovered later using the -r option or the ex recover com‐
255 mand. The editor shall not write the file or return to command
256 or text input mode, and shall terminate with a non-zero exit
257 status.
258 SIGTERM
260 Refer to SIGHUP.
261 The action taken for all other signals is unspecified.
264
266 The standard output shall be used only for writing prompts to the user,
267 for informational messages, and for writing lines from the file.
268
270 The standard error shall be used only for diagnostic messages.
271
273 The output from ex shall be text files.
274
276 Only the ex mode of the editor is described in this section. See vi
277 for additional editing capabilities available in ex.
278 When an error occurs, ex shall write a message. If the terminal sup‐
280 ports a standout mode (such as inverse video), the message shall be
281 written in standout mode. If the terminal does not support a standout
282 mode, and the edit option errorbells is set, an alert action shall pre‐
283 cede the error message.
284 By default, ex shall start in command mode, which shall be indicated by
286 a : prompt; see the prompt command. Text input mode can be entered by
287 the append, insert, or change commands; it can be exited (and command
288 mode re-entered) by typing a period ( '.' ) alone at the beginning of a
289 line.
290 Initialization in ex and vi
292 The following symbols are used in this and following sections to spec‐
293 ify locations in the edit buffer:
294 alternate and current pathnames
296 Two pathnames, named current and alternate, are maintained by
298 the editor. Any ex commands that take filenames as arguments
299 shall set them as follows:
300 1. If a file argument is specified to the ex edit, ex, or
302 recover commands, or if an ex tag command replaces the con‐
303 tents of the edit buffer.
304 a. If the command replaces the contents of the edit buffer,
306 the current pathname shall be set to the file argument
307 or the file indicated by the tag, and the alternate
308 pathname shall be set to the previous value of the cur‐
309 rent pathname.
310 b. Otherwise, the alternate pathname shall be set to the
312 file argument.
313 2. If a file argument is specified to the ex next command:
315 a. If the command replaces the contents of the edit buffer,
317 the current pathname shall be set to the first file
318 argument, and the alternate pathname shall be set to the
319 previous value of the current pathname.
320 3. If a file argument is specified to the ex file command, the
322 current pathname shall be set to the file argument, and the
323 alternate pathname shall be set to the previous value of the
324 current pathname.
325 4. If a file argument is specified to the ex read and write
327 commands (that is, when reading or writing a file, and not
328 to the program named by the shell edit option), or a file
329 argument is specified to the ex xit command:
330 a. If the current pathname has no value, the current path‐
332 name shall be set to the file argument.
333 b. Otherwise, the alternate pathname shall be set to the
335 file argument.
336 If the alternate pathname is set to the previous value of the current
338 pathname when the current pathname had no previous value, then the
339 alternate pathname shall have no value as a result.
340 current line
342 The line of the edit buffer referenced by the cursor. Each com‐
344 mand description specifies the current line after the command
345 has been executed, as the current line value. When the edit buf‐
346 fer contains no lines, the current line shall be zero; see
347 Addressing in ex .
348 current column
350 The current display line column occupied by the cursor. (The
352 columns shall be numbered beginning at 1.) Each command descrip‐
353 tion specifies the current column after the command has been
354 executed, as the current column value. This column is an ideal
355 column that is remembered over the lifetime of the editor. The
356 actual display line column upon which the cursor rests may be
357 different from the current column; see the cursor positioning
358 discussion in Command Descriptions in vi .
359 set to non-<blank>
361 A description for a current column value, meaning that the cur‐
363 rent column shall be set to the last display line column on
364 which is displayed any part of the first non- <blank> of the
365 line. If the line has no non- <blank> non- <newline>s, the cur‐
366 rent column shall be set to the last display line column on
367 which is displayed any part of the last non- <newline> in the
368 line. If the line is empty, the current column shall be set to
369 column position 1.
370 The length of lines in the edit buffer may be limited to {LINE_MAX}
373 bytes. In open and visual mode, the length of lines in the edit buffer
374 may be limited to the number of characters that will fit in the dis‐
375 play. If either limit is exceeded during editing, an error message
376 shall be written. If either limit is exceeded by a line read in from a
377 file, an error message shall be written and the edit session may be
378 terminated.
379 If the editor stops running due to any reason other than a user com‐
381 mand, and the edit buffer has been modified since the last complete
382 write, it shall be equivalent to a SIGHUP asynchronous event. If the
383 system crashes, it shall be equivalent to a SIGHUP asynchronous event.
384 During initialization (before the first file is copied into the edit
386 buffer or any user commands from the terminal are processed) the fol‐
387 lowing shall occur:
388 1. If the environment variable EXINIT is set, the editor shall execute
390 the ex commands contained in that variable.
391 2. If the EXINIT variable is not set, and all of the following are
393 true:
394 a. The HOME environment variable is not null and not empty.
396 b. The file .exrc in the directory referred to by the HOME envi‐
398 ronment variable:
399 1. Exists
401 2. Is owned by the same user ID as the real user ID of the
403 process or the process has appropriate privileges
404 3. Is not writable by anyone other than the owner
406 the editor shall execute the ex commands contained in that file.
408 3. If and only if all of the following are true:
410 a. The current directory is not referred to by the HOME environ‐
412 ment variable.
413 b. A command in the EXINIT environment variable or a command in
415 the .exrc file in the directory referred to by the HOME envi‐
416 ronment variable sets the editor option exrc.
417 c. The .exrc file in the current directory:
419 1. Exists
421 2. Is owned by the same user ID as the real user ID of the
423 process, or by one of a set of implementation-defined user
424 IDs
425 3. Is not writable by anyone other than the owner
427 the editor shall attempt to execute the ex commands contained in that
429 file.
430 Lines in any .exrc file that are blank lines shall be ignored. If any
432 .exrc file exists, but is not read for ownership or permission reasons,
433 it shall be an error.
434 After the EXINIT variable and any .exrc files are processed, the first
436 file specified by the user shall be edited, as follows:
437 1. If the user specified the -t option, the effect shall be as if the
439 ex tag command was entered with the specified argument, with the
440 exception that if tag processing does not result in a file to edit,
441 the effect shall be as described in step 3. below.
442 2. Otherwise, if the user specified any command line file arguments,
444 the effect shall be as if the ex edit command was entered with the
445 first of those arguments as its file argument.
446 3. Otherwise, the effect shall be as if the ex edit command was
448 entered with a nonexistent filename as its file argument. It is
449 unspecified whether this action shall set the current pathname. In
450 an implementation where this action does not set the current path‐
451 name, any editor command using the current pathname shall fail
452 until an editor command sets the current pathname.
453 If the -r option was specified, the first time a file in the initial
455 argument list or a file specified by the -t option is edited, if recov‐
456 ery information has previously been saved about it, that information
457 shall be recovered and the editor shall behave as if the contents of
458 the edit buffer have already been modified. If there are multiple
459 instances of the file to be recovered, the one most recently saved
460 shall be recovered, and an informational message that there are previ‐
461 ous versions of the file that can be recovered shall be written. If no
462 recovery information about a file is available, an informational mes‐
463 sage to this effect shall be written, and the edit shall proceed as
464 usual.
465 If the -c option was specified, the first time a file that already
467 exists (including a file that might not exist but for which recovery
468 information is available, when the -r option is specified) replaces or
469 initializes the contents of the edit buffer, the current line shall be
470 set to the last line of the edit buffer, the current column shall be
471 set to non- <blank>, and the ex commands specified with the -c option
472 shall be executed. In this case, the current line and current column
473 shall not be set as described for the command associated with the
474 replacement or initialization of the edit buffer contents. However, if
475 the -t option or a tag command is associated with this action, the -c
476 option commands shall be executed and then the movement to the tag
477 shall be performed.
478 The current argument list shall initially be set to the filenames spec‐
480 ified by the user on the command line. If no filenames are specified by
481 the user, the current argument list shall be empty. If the -t option
482 was specified, it is unspecified whether any filename resulting from
483 tag processing shall be prepended to the current argument list. In the
484 case where the filename is added as a prefix to the current argument
485 list, the current argument list reference shall be set to that file‐
486 name. In the case where the filename is not added as a prefix to the
487 current argument list, the current argument list reference shall logi‐
488 cally be located before the first of the filenames specified on the
489 command line (for example, a subsequent ex next command shall edit the
490 first filename from the command line). If the -t option was not speci‐
491 fied, the current argument list reference shall be to the first of the
492 filenames on the command line.
493 Addressing in ex
495 Addressing in ex relates to the current line and the current column;
496 the address of a line is its 1-based line number, the address of a col‐
497 umn is its 1-based count from the beginning of the line. Generally, the
498 current line is the last line affected by a command. The current line
499 number is the address of the current line. In each command description,
500 the effect of the command on the current line number and the current
501 column is described.
502 Addresses are constructed as follows:
504 1. The character '.' (period) shall address the current line.
506 2. The character '$' shall address the last line of the edit buffer.
508 3. The positive decimal number n shall address the nth line of the
510 edit buffer.
511 4. The address "'x" refers to the line marked with the mark name char‐
513 acter 'x', which shall be a lowercase letter from the portable
514 character set or one of the characters '`' or '" . It shall be an
515 error if the line that was marked is not currently present in the
516 edit buffer or the mark has not been set. Lines can be marked with
517 the ex mark or k commands, or the vi m command.
518 5. A regular expression enclosed by slashes ( '/' ) shall address the
520 first line found by searching forwards from the line following the
521 current line toward the end of the edit buffer and stopping at the
522 first line for which the line excluding the terminating <newline>
523 matches the regular expression. As stated in Regular Expressions in
524 ex, an address consisting of a null regular expression delimited by
525 slashes "//" shall address the next line for which the line exclud‐
526 ing the terminating <newline> matches the last regular expression
527 encountered. In addition, the second slash can be omitted at the
528 end of a command line. If the wrapscan edit option is set, the
529 search shall wrap around to the beginning of the edit buffer and
530 continue up to and including the current line, so that the entire
531 edit buffer is searched. Within the regular expression, the
532 sequence "\/" shall represent a literal slash instead of the regu‐
533 lar expression delimiter.
534 6. A regular expression enclosed in question marks ( '?' ) shall
536 address the first line found by searching backwards from the line
537 preceding the current line toward the beginning of the edit buffer
538 and stopping at the first line for which the line excluding the
539 terminating <newline> matches the regular expression. An address
540 consisting of a null regular expression delimited by question marks
541 "??" shall address the previous line for which the line excluding
542 the terminating <newline> matches the last regular expression
543 encountered. In addition, the second question mark can be omitted
544 at the end of a command line. If the wrapscan edit option is set,
545 the search shall wrap around from the beginning of the edit buffer
546 to the end of the edit buffer and continue up to and including the
547 current line, so that the entire edit buffer is searched. Within
548 the regular expression, the sequence "\?" shall represent a literal
549 question mark instead of the RE delimiter.
550 7. A plus sign ( '+' ) or a minus sign ( '-' ) followed by a decimal
552 number shall address the current line plus or minus the number. A
553 '+' or '-' not followed by a decimal number shall address the cur‐
554 rent line plus or minus 1.
555 Addresses can be followed by zero or more address offsets, optionally
557 <blank>-separated. Address offsets are constructed as follows:
558 1. A '+' or '-' immediately followed by a decimal number shall add
560 (subtract) the indicated number of lines to (from) the address. A
561 '+' or '-' not followed by a decimal number shall add (subtract) 1
562 to (from) the address.
563 2. A decimal number shall add the indicated number of lines to the
565 address.
566 It shall not be an error for an intermediate address value to be less
568 than zero or greater than the last line in the edit buffer. It shall be
569 an error for the final address value to be less than zero or greater
570 than the last line in the edit buffer.
571 Commands take zero, one, or two addresses; see the descriptions of
573 1addr and 2addr in Command Descriptions in ex . If more than the
574 required number of addresses are provided to a command that requires
575 zero addresses, it shall be an error. Otherwise, if more than the
576 required number of addresses are provided to a command, the addresses
577 specified first shall be evaluated and then discarded until the maximum
578 number of valid addresses remain.
579 Addresses shall be separated from each other by a comma ( ',' ) or a
581 semicolon ( ';' ). If no address is specified before or after a comma
582 or semicolon separator, it shall be as if the address of the current
583 line was specified before or after the separator. In the case of a
584 semicolon separator, the current line ( '.' ) shall be set to the first
585 address, and only then will the next address be calculated. This fea‐
586 ture can be used to determine the starting line for forwards and back‐
587 wards searches (see rules 5. and 6.).
588 A percent sign ( '%' ) shall be equivalent to entering the two
590 addresses "1,$" .
591 Any delimiting <blank>s between addresses, address separators, or
593 address offsets shall be discarded.
594 Command Line Parsing in ex
596 The following symbol is used in this and following sections to describe
597 parsing behavior:
598 escape If a character is referred to as "backslash-escaped" or " <con‐
600 trol>-V-escaped," it shall mean that the character acquired or
601 lost a special meaning by virtue of being preceded, respec‐
602 tively, by a backslash or <control>-V character. Unless other‐
603 wise specified, the escaping character shall be discarded at
604 that time and shall not be further considered for any purpose.
605 Command-line parsing shall be done in the following steps. For each
608 step, characters already evaluated shall be ignored; that is, the
609 phrase "leading character" refers to the next character that has not
610 yet been evaluated.
611 1. Leading colon characters shall be skipped.
613 2. Leading <blank>s shall be skipped.
615 3. If the leading character is a double-quote character, the charac‐
617 ters up to and including the next non-backslash-escaped <newline>
618 shall be discarded, and any subsequent characters shall be parsed
619 as a separate command.
620 4. Leading characters that can be interpreted as addresses shall be
622 evaluated; see Addressing in ex .
623 5. Leading <blank>s shall be skipped.
625 6. If the next character is a vertical-line character or a <newline>:
627 a. If the next character is a <newline>:
629 1. If ex is in open or visual mode, the current line shall be
631 set to the last address specified, if any.
632 2. Otherwise, if the last command was terminated by a verti‐
634 cal-line character, no action shall be taken; for example,
635 the command "||<newline>" shall execute two implied com‐
636 mands, not three.
637 3. Otherwise, step 6.b. shall apply.
639 b. Otherwise, the implied command shall be the print command. The
641 last #, p, and l flags specified to any ex command shall be
642 remembered and shall apply to this implied command. Executing
643 the ex number, print, or list command shall set the remembered
644 flags to #, nothing, and l, respectively, plus any other flags
645 specified for that execution of the number, print, or list com‐
646 mand.
647 If ex is not currently performing a global or v command, and no
649 address or count is specified, the current line shall be incre‐
650 mented by 1 before the command is executed. If incrementing the
651 current line would result in an address past the last line in the
652 edit buffer, the command shall fail, and the increment shall not
653 happen.
654 c. The <newline> or vertical-line character shall be discarded and
656 any subsequent characters shall be parsed as a separate com‐
657 mand.
658 7. The command name shall be comprised of the next character (if the
660 character is not alphabetic), or the next character and any subse‐
661 quent alphabetic characters (if the character is alphabetic), with
662 the following exceptions:
663 a. Commands that consist of any prefix of the characters in the
665 command name delete, followed immediately by any of the charac‐
666 ters 'l', 'p', '+', '-', or '#' shall be interpreted as a
667 delete command, followed by a <blank>, followed by the charac‐
668 ters that were not part of the prefix of the delete command.
669 The maximum number of characters shall be matched to the com‐
670 mand name delete; for example, "del" shall not be treated as
671 "de" followed by the flag l.
672 b. Commands that consist of the character 'k', followed by a char‐
674 acter that can be used as the name of a mark, shall be equiva‐
675 lent to the mark command followed by a <blank>, followed by the
676 character that followed the 'k' .
677 c. Commands that consist of the character 's', followed by charac‐
679 ters that could be interpreted as valid options to the s com‐
680 mand, shall be the equivalent of the s command, without any
681 pattern or replacement values, followed by a <blank>, followed
682 by the characters after the 's' .
683 8. The command name shall be matched against the possible command
685 names, and a command name that contains a prefix matching the char‐
686 acters specified by the user shall be the executed command. In the
687 case of commands where the characters specified by the user could
688 be ambiguous, the executed command shall be as follows:
689 a append n next t t
691 c change p print u undo
692 ch change pr print un undo
693 e edit r read v v
694 m move re read w write
695 ma mark s s
696 Implementation extensions with names causing similar ambiguities shall
698 not be checked for a match until all possible matches for commands
699 specified by IEEE Std 1003.1-2001 have been checked.
700 9. If the command is a ! command, or if the command is a read command
702 followed by zero or more <blank>s and a !, or if the command is a
703 write command followed by one or more <blank>s and a !, the rest of
704 the command shall include all characters up to a non-backslash-
705 escaped <newline>. The <newline> shall be discarded and any subse‐
706 quent characters shall be parsed as a separate ex command.
707 10. Otherwise, if the command is an edit, ex, or next command, or a
709 visual command while in open or visual mode, the next part of the
710 command shall be parsed as follows:
711 a. Any '!' character immediately following the command shall be
713 skipped and be part of the command.
714 b. Any leading <blank>s shall be skipped and be part of the com‐
716 mand.
717 c. If the next character is a '+', characters up to the first non-
719 backslash-escaped <newline> or non-backslash-escaped <blank>
720 shall be skipped and be part of the command.
721 d. The rest of the command shall be determined by the steps speci‐
723 fied in paragraph 12.
724 11. Otherwise, if the command is a global, open, s, or v command, the
726 next part of the command shall be parsed as follows:
727 a. Any leading <blank>s shall be skipped and be part of the com‐
729 mand.
730 b. If the next character is not an alphanumeric, double-quote,
732 <newline>, backslash, or vertical-line character:
733 1. The next character shall be used as a command delimiter.
735 2. If the command is a global, open, or v command, characters
737 up to the first non-backslash-escaped <newline>, or first
738 non-backslash-escaped delimiter character, shall be skipped
739 and be part of the command.
740 3. If the command is an s command, characters up to the first
742 non-backslash-escaped <newline>, or second non-backslash-
743 escaped delimiter character, shall be skipped and be part
744 of the command.
745 c. If the command is a global or v command, characters up to the
747 first non-backslash-escaped <newline> shall be skipped and be
748 part of the command.
749 d. Otherwise, the rest of the command shall be determined by the
751 steps specified in paragraph 12.
752 12. Otherwise:
754 a. If the command was a map, unmap, abbreviate, or unabbreviate
756 command, characters up to the first non- <control>-V-escaped
757 <newline>, vertical-line, or double-quote character shall be
758 skipped and be part of the command.
759 b. Otherwise, characters up to the first non-backslash-escaped
761 <newline>, vertical-line, or double-quote character shall be
762 skipped and be part of the command.
763 c. If the command was an append, change, or insert command, and
765 the step 12.b. ended at a vertical-line character, any subse‐
766 quent characters, up to the next non-backslash-escaped <new‐
767 line> shall be used as input text to the command.
768 d. If the command was ended by a double-quote character, all sub‐
770 sequent characters, up to the next non-backslash-escaped <new‐
771 line>, shall be discarded.
772 e. The terminating <newline> or vertical-line character shall be
774 discarded and any subsequent characters shall be parsed as a
775 separate ex command.
776 Command arguments shall be parsed as described by the Synopsis and
778 Description of each individual ex command. This parsing shall not be
779 <blank>-sensitive, except for the ! argument, which must follow the
780 command name without intervening <blank>s, and where it would otherwise
781 be ambiguous. For example, count and flag arguments need not be
782 <blank>-separated because "d22p" is not ambiguous, but file arguments
783 to the ex next command must be separated by one or more <blank>s. Any
784 <blank> in command arguments for the abbreviate, unabbreviate, map, and
785 unmap commands can be <control>-V-escaped, in which case the <blank>
786 shall not be used as an argument delimiter. Any <blank> in the command
787 argument for any other command can be backslash-escaped, in which case
788 that <blank> shall not be used as an argument delimiter.
789 Within command arguments for the abbreviate, unabbreviate, map, and
791 unmap commands, any character can be <control>-V-escaped. All such
792 escaped characters shall be treated literally and shall have no special
793 meaning. Within command arguments for all other ex commands that are
794 not regular expressions or replacement strings, any character that
795 would otherwise have a special meaning can be backslash-escaped.
796 Escaped characters shall be treated literally, without special meaning
797 as shell expansion characters or '!', '%', and '#' expansion charac‐
798 ters. See Regular Expressions in ex and Replacement Strings in ex for
799 descriptions of command arguments that are regular expressions or
800 replacement strings.
801 Non-backslash-escaped '%' characters appearing in file arguments to any
803 ex command shall be replaced by the current pathname; unescaped '#'
804 characters shall be replaced by the alternate pathname. It shall be an
805 error if '%' or '#' characters appear unescaped in an argument and
806 their corresponding values are not set.
807 Non-backslash-escaped '!' characters in the arguments to either the ex
809 ! command or the open and visual mode ! command, or in the arguments to
810 the ex read command, where the first non- <blank> after the command
811 name is a '!' character, or in the arguments to the ex write command
812 where the command name is followed by one or more <blank>s and the
813 first non- <blank> after the command name is a '!' character, shall be
814 replaced with the arguments to the last of those three commands as they
815 appeared after all unescaped '%', '#', and '!' characters were
816 replaced. It shall be an error if '!' characters appear unescaped in
817 one of these commands and there has been no previous execution of one
818 of these commands.
819 If an error occurs during the parsing or execution of an ex command:
821 * An informational message to this effect shall be written. Execution
823 of the ex command shall stop, and the cursor (for example, the cur‐
824 rent line and column) shall not be further modified.
825 * If the ex command resulted from a map expansion, all characters from
827 that map expansion shall be discarded, except as otherwise specified
828 by the map command.
829 * Otherwise, if the ex command resulted from the processing of an
831 EXINIT environment variable, a .exrc file, a :source command, a -c
832 option, or a + command specified to an ex edit, ex, next, or visual
833 command, no further commands from the source of the commands shall
834 be executed.
835 * Otherwise, if the ex command resulted from the execution of a buffer
837 or a global or v command, no further commands caused by the execu‐
838 tion of the buffer or the global or v command shall be executed.
839 * Otherwise, if the ex command was not terminated by a <newline>, all
841 characters up to and including the next non-backslash-escaped <new‐
842 line> shall be discarded.
843 Input Editing in ex
845 The following symbol is used in this and the following sections to
846 specify command actions:
847 word In the POSIX locale, a word consists of a maximal sequence of
849 letters, digits, and underscores, delimited at both ends by
850 characters other than letters, digits, or underscores, or by the
851 beginning or end of a line or the edit buffer.
852 When accepting input characters from the user, in either ex command
855 mode or ex text input mode, ex shall enable canonical mode input pro‐
856 cessing, as defined in the System Interfaces volume of
857 IEEE Std 1003.1-2001.
858 If in ex text input mode:
860 1. If the number edit option is set, ex shall prompt for input using
862 the line number that would be assigned to the line if it is
863 entered, in the format specified for the ex number command.
864 2. If the autoindent edit option is set, ex shall prompt for input
866 using autoindent characters, as described by the autoindent edit
867 option. autoindent characters shall follow the line number, if any.
868 If in ex command mode:
870 1. If the prompt edit option is set, input shall be prompted for using
872 a single ':' character; otherwise, there shall be no prompt.
873 The input characters in the following sections shall have the following
875 effects on the input line.
876 Scroll
878 Synopsis:
879 eof
882 See the description of the stty eof character in stty .
885 If in ex command mode: If the eof character is the first character
887 entered on the line, the line shall be evaluated as if it contained two
888 characters: a <control>-D and a <newline>.
889 Otherwise, the eof character shall have no special meaning.
891 If in ex text input mode: If the cursor follows an autoindent charac‐
894 ter, the autoindent characters in the line shall be modified so that a
895 part of the next text input character will be displayed on the first
896 column in the line after the previous shiftwidth edit option column
897 boundary, and the user shall be prompted again for input for the same
898 line.
899 Otherwise, if the cursor follows a '0', which follows an autoindent
901 character, and the '0' was the previous text input character, the '0'
902 and all autoindent characters in the line shall be discarded, and the
903 user shall be prompted again for input for the same line.
904 Otherwise, if the cursor follows a '^', which follows an autoindent
906 character, and the '^' was the previous text input character, the '^'
907 and all autoindent characters in the line shall be discarded, and the
908 user shall be prompted again for input for the same line. In addition,
909 the autoindent level for the next input line shall be derived from the
910 same line from which the autoindent level for the current input line
911 was derived.
912 Otherwise, if there are no autoindent or text input characters in the
914 line, the eof character shall be discarded.
915 Otherwise, the eof character shall have no special meaning.
917 <newline>
919 Synopsis:
920 <newline>
923 <control>-J
926 If in ex command mode: Cause the command line to be parsed; <control>-J
929 shall be mapped to the <newline> for this purpose.
930 If in ex text input mode: Terminate the current line. If there are no
932 characters other than autoindent characters on the line, all characters
933 on the line shall be discarded.
934 Prompt for text input on a new line after the current line. If the
936 autoindent edit option is set, an appropriate number of autoindent
937 characters shall be added as a prefix to the line as described by the
938 ex autoindent edit option.
939 <backslash>
941 Synopsis:
942 <backslash>
945 Allow the entry of a subsequent <newline> or <control>-J as a literal
948 character, removing any special meaning that it may have to the editor
949 during text input mode. The backslash character shall be retained and
950 evaluated when the command line is parsed, or retained and included
951 when the input text becomes part of the edit buffer.
952 <control>-V
954 Synopsis:
955 <control>-V
958 Allow the entry of any subsequent character as a literal character,
961 removing any special meaning that it may have to the editor during text
962 input mode. The <control>-V character shall be discarded before the
963 command line is parsed or the input text becomes part of the edit buf‐
964 fer.
965 If the "literal next" functionality is performed by the underlying sys‐
967 tem, it is implementation-defined whether a character other than <con‐
968 trol>-V performs this function.
969 <control>-W
971 Synopsis:
972 <control>-W
975 Discard the <control>-W, and the word previous to it in the input line,
978 including any <blank>s following the word and preceding the <con‐
979 trol>-W. If the "word erase" functionality is performed by the underly‐
980 ing system, it is implementation-defined whether a character other than
981 <control>-W performs this function.
982 Command Descriptions in ex
984 The following symbols are used in this section to represent command
985 modifiers. Some of these modifiers can be omitted, in which case the
986 specified defaults shall be used.
987 1addr A single line address, given in any of the forms described in
989 Addressing in ex ; the default shall be the current line ( '.'
990 ), unless otherwise specified.
991 If the line address is zero, it shall be an error, unless otherwise
993 specified in the following command descriptions.
994 If the edit buffer is empty, and the address is specified with a com‐
996 mand other than =, append, insert, open, put, read, or visual, or the
997 address is not zero, it shall be an error.
998 2addr Two addresses specifying an inclusive range of lines. If no
1000 addresses are specified, the default for 2addr shall be the cur‐
1001 rent line only ( ".,." ), unless otherwise specified in the fol‐
1002 lowing command descriptions. If one address is specified, 2addr
1003 shall specify that line only, unless otherwise specified in the
1004 following command descriptions.
1005 It shall be an error if the first address is greater than the second
1007 address.
1008 If the edit buffer is empty, and the two addresses are specified with a
1010 command other than the !, write, wq, or xit commands, or either address
1011 is not zero, it shall be an error.
1012 count A positive decimal number. If count is specified, it shall be
1014 equivalent to specifying an additional address to the command,
1015 unless otherwise specified by the following command descrip‐
1016 tions. The additional address shall be equal to the last
1017 address specified to the command (either explicitly or by
1018 default) plus count-1.
1019 If this would result in an address greater than the last line of the
1021 edit buffer, it shall be corrected to equal the last line of the edit
1022 buffer.
1023 flags One or more of the characters '+', '-', '#', 'p', or 'l' (ell).
1025 The flag characters can be <blank>-separated, and in any order
1026 or combination. The characters '#', 'p', and 'l' shall cause
1027 lines to be written in the format specified by the print command
1028 with the specified flags.
1029 The lines to be written are as follows:
1031 1. All edit buffer lines written during the execution of the ex
1033 &, ~, list, number, open, print, s, visual, and z commands
1034 shall be written as specified by flags.
1035 2. After the completion of an ex command with a flag as an
1037 argument, the current line shall be written as specified by
1038 flags, unless the current line was the last line written by
1039 the command.
1040 The characters '+' and '-' cause the value of the current line after
1042 the execution of the ex command to be adjusted by the offset address as
1043 described in Addressing in ex . This adjustment shall occur before the
1044 current line is written as described in 2. above.
1045 The default for flags shall be none.
1047 buffer One of a number of named areas for holding text. The named buf‐
1049 fers are specified by the alphanumeric characters of the POSIX
1050 locale. There shall also be one "unnamed" buffer. When no buffer
1051 is specified for editor commands that use a buffer, the unnamed
1052 buffer shall be used. Commands that store text into buffers
1053 shall store the text as it was before the command took effect,
1054 and shall store text occurring earlier in the file before text
1055 occurring later in the file, regardless of how the text region
1056 was specified. Commands that store text into buffers shall store
1057 the text into the unnamed buffer as well as any specified buf‐
1058 fer.
1059 In ex commands, buffer names are specified as the name by itself. In
1061 open or visual mode commands the name is preceded by a double quote ( '
1062 )' character.
1063 If the specified buffer name is an uppercase character, and the buffer
1065 contents are to be modified, the buffer shall be appended to rather
1066 than being overwritten. If the buffer is not being modified, specifying
1067 the buffer name in lowercase and uppercase shall have identical
1068 results.
1069 There shall also be buffers named by the numbers 1 through 9. In open
1071 and visual mode, if a region of text including characters from more
1072 than a single line is being modified by the vi c or d commands, the
1073 motion character associated with the c or d commands specifies that the
1074 buffer text shall be in line mode, or the commands %, `, /, ?, (, ), N,
1075 n, {, or } are used to define a region of text for the c or d commands,
1076 the contents of buffers 1 through 8 shall be moved into the buffer
1077 named by the next numerically greater value, the contents of buffer 9
1078 shall be discarded, and the region of text shall be copied into buffer
1079 1. This shall be in addition to copying the text into a user-specified
1080 buffer or unnamed buffer, or both. Numeric buffers can be specified as
1081 a source buffer for open and visual mode commands; however, specifying
1082 a numeric buffer as the write target of an open or visual mode command
1083 shall have unspecified results.
1084 The text of each buffer shall have the characteristic of being in
1086 either line or character mode. Appending text to a non-empty buffer
1087 shall set the mode to match the characteristic of the text being
1088 appended. Appending text to a buffer shall cause the creation of at
1089 least one additional line in the buffer. All text stored into buffers
1090 by ex commands shall be in line mode. The ex commands that use buffers
1091 as the source of text specify individually how buffers of different
1092 modes are handled. Each open or visual mode command that uses buffers
1093 for any purpose specifies individually the mode of the text stored into
1094 the buffer and how buffers of different modes are handled.
1095 file Command text used to derive a pathname. The default shall be the
1097 current pathname, as defined previously, in which case, if no
1098 current pathname has yet been established it shall be an error,
1099 except where specifically noted in the individual command
1100 descriptions that follow. If the command text contains any of
1101 the characters '~', '{', '[', '*', '?', '$', '`', '", ' ,' and
1102 '\', it shall be subjected to the process of "shell expansions",
1103 as described below; if more than a single pathname results and
1104 the command expects only one, it shall be an error.
1105 The process of shell expansions in the editor shall be done as follows.
1107 The ex utility shall pass two arguments to the program named by the
1108 shell edit option; the first shall be -c, and the second shall be the
1109 string "echo" and the command text as a single argument. The standard
1110 output and standard error of that command shall replace the command
1111 text.
1112 ! A character that can be appended to the command name to modify
1114 its operation, as detailed in the individual command descrip‐
1115 tions. With the exception of the ex read, write, and ! commands,
1116 the '!' character shall only act as a modifier if there are no
1117 <blank>s between it and the command name.
1118 remembered search direction
1120 The vi commands N and n begin searching in a forwards or back‐
1122 wards direction in the edit buffer based on a remembered search
1123 direction, which is initially unset, and is set by the ex
1124 global, v, s, and tag commands, and the vi / and ? commands.
1125 Abbreviate
1128 Synopsis:
1129 ab[breviate][lhs rhs]
1132 If lhs and rhs are not specified, write the current list of abbrevia‐
1135 tions and do nothing more.
1136 Implementations may restrict the set of characters accepted in lhs or
1138 rh, except that printable characters and <blank>s shall not be
1139 restricted. Additional restrictions shall be implementation-defined.
1140 In both lhs and rhs, any character may be escaped with a <control>-V,
1142 in which case the character shall not be used to delimit lhs from rhs,
1143 and the escaping <control>-V shall be discarded.
1144 In open and visual text input mode, if a non-word or <ESC> character
1146 that is not escaped by a <control>-V character is entered after a word
1147 character, a check shall be made for a set of characters matching lhs,
1148 in the text input entered during this command. If it is found, the
1149 effect shall be as if rhs was entered instead of lhs.
1150 The set of characters that are checked is defined as follows:
1152 1. If there are no characters inserted before the word and non-word or
1154 <ESC> characters that triggered the check, the set of characters
1155 shall consist of the word character.
1156 2. If the character inserted before the word and non-word or <ESC>
1158 characters that triggered the check is a word character, the set of
1159 characters shall consist of the characters inserted immediately
1160 before the triggering characters that are word characters, plus the
1161 triggering word character.
1162 3. If the character inserted before the word and non-word or <ESC>
1164 characters that triggered the check is not a word character, the
1165 set of characters shall consist of the characters that were
1166 inserted before the triggering characters that are neither <blank>s
1167 nor word characters, plus the triggering word character.
1168 It is unspecified whether the lhs argument entered for the ex abbrevi‐
1170 ate and unabbreviate commands is replaced in this fashion. Regardless
1171 of whether or not the replacement occurs, the effect of the command
1172 shall be as if the replacement had not occurred.
1173 Current line: Unchanged.
1175 Current column: Unchanged.
1177 Append
1179 Synopsis:
1180 [1addr] a[ppend][!]
1183 Enter ex text input mode; the input text shall be placed after the
1186 specified line. If line zero is specified, the text shall be placed at
1187 the beginning of the edit buffer.
1188 This command shall be affected by the number and autoindent edit
1190 options; following the command name with '!' shall cause the autoindent
1191 edit option setting to be toggled for the duration of this command
1192 only.
1193 Current line: Set to the last input line; if no lines were input, set
1195 to the specified line, or to the first line of the edit buffer if a
1196 line of zero was specified, or zero if the edit buffer is empty.
1197 Current column: Set to non- <blank>.
1199 Arguments
1201 Synopsis:
1202 ar[gs]
1205 Write the current argument list, with the current argument-list entry,
1208 if any, between '[' and ']' characters.
1209 Current line: Unchanged.
1211 Current column: Unchanged.
1213 Change
1215 Synopsis:
1216 [2addr] c[hange][!][count]
1219 Enter ex text input mode; the input text shall replace the specified
1222 lines. The specified lines shall be copied into the unnamed buffer,
1223 which shall become a line mode buffer.
1224 This command shall be affected by the number and autoindent edit
1226 options; following the command name with '!' shall cause the autoindent
1227 edit option setting to be toggled for the duration of this command
1228 only.
1229 Current line: Set to the last input line; if no lines were input, set
1231 to the line before the first address, or to the first line of the edit
1232 buffer if there are no lines preceding the first address, or to zero if
1233 the edit buffer is empty.
1234 Current column: Set to non- <blank>.
1236 Change Directory
1238 Synopsis:
1239 chd[ir][!][directory]cd[!][directory]
1242 Change the current working directory to directory.
1245 If no directory argument is specified, and the HOME environment vari‐
1247 able is set to a non-null and non-empty value, directory shall default
1248 to the value named in the HOME environment variable. If the HOME envi‐
1249 ronment variable is empty or is undefined, the default value of direc‐
1250 tory is implementation-defined.
1251 If no '!' is appended to the command name, and the edit buffer has been
1253 modified since the last complete write, and the current pathname does
1254 not begin with a '/', it shall be an error.
1255 Current line: Unchanged.
1257 Current column: Unchanged.
1259 Copy
1261 Synopsis:
1262 [2addr] co[py] 1addr [flags]
1265 [2addr] t 1addr [flags]
1266 Copy the specified lines after the specified destination line; line
1269 zero specifies that the lines shall be placed at the beginning of the
1270 edit buffer.
1271 Current line: Set to the last line copied.
1273 Current column: Set to non- <blank>.
1275 Delete
1277 Synopsis:
1278 [2addr] d[elete][buffer][count][flags]
1281 Delete the specified lines into a buffer (defaulting to the unnamed
1284 buffer), which shall become a line-mode buffer.
1285 Flags can immediately follow the command name; see Command Line Parsing
1287 in ex .
1288 Current line: Set to the line following the deleted lines, or to the
1290 last line in the edit buffer if that line is past the end of the edit
1291 buffer, or to zero if the edit buffer is empty.
1292 Current column: Set to non- <blank>.
1294 Edit
1296 Synopsis:
1297 e[dit][!][+command][file]ex[!][+command][file]
1300 If no '!' is appended to the command name, and the edit buffer has been
1303 modified since the last complete write, it shall be an error.
1304 If file is specified, replace the current contents of the edit buffer
1306 with the current contents of file, and set the current pathname to
1307 file. If file is not specified, replace the current contents of the
1308 edit buffer with the current contents of the file named by the current
1309 pathname. If for any reason the current contents of the file cannot be
1310 accessed, the edit buffer shall be empty.
1311 The + command option shall be <blank>-delimited; <blank>s within + com‐
1313 mand can be escaped by preceding them with a backslash character. The +
1314 command shall be interpreted as an ex command immediately after the
1315 contents of the edit buffer have been replaced and the current line and
1316 column have been set.
1317 If the edit buffer is empty:
1319 Current line: Set to 0.
1321 Current column: Set to 1.
1323 Otherwise, if executed while in ex command mode or if the + command
1325 argument is specified:
1326 Current line: Set to the last line of the edit buffer.
1328 Current column: Set to non- <blank>.
1330 Otherwise, if file is omitted or results in the current pathname:
1332 Current line: Set to the first line of the edit buffer.
1334 Current column: Set to non- <blank>.
1336 Otherwise, if file is the same as the last file edited, the line and
1338 column shall be set as follows; if the file was previously edited, the
1339 line and column may be set as follows:
1340 Current line: Set to the last value held when that file was last
1342 edited. If this value is not a valid line in the new edit buffer, set
1343 to the first line of the edit buffer.
1344 Current column: If the current line was set to the last value held when
1346 the file was last edited, set to the last value held when the file was
1347 last edited. Otherwise, or if the last value is not a valid column in
1348 the new edit buffer, set to non- <blank>.
1349 Otherwise:
1351 Current line: Set to the first line of the edit buffer.
1353 Current column: Set to non- <blank>.
1355 File
1357 Synopsis:
1358 f[ile][file]
1361 If a file argument is specified, the alternate pathname shall be set to
1364 the current pathname, and the current pathname shall be set to file.
1365 Write an informational message. If the file has a current pathname, it
1367 shall be included in this message; otherwise, the message shall indi‐
1368 cate that there is no current pathname. If the edit buffer contains
1369 lines, the current line number and the number of lines in the edit buf‐
1370 fer shall be included in this message; otherwise, the message shall
1371 indicate that the edit buffer is empty. If the edit buffer has been
1372 modified since the last complete write, this fact shall be included in
1373 this message. If the readonly edit option is set, this fact shall be
1374 included in this message. The message may contain other unspecified
1375 information.
1376 Current line: Unchanged.
1378 Current column: Unchanged.
1380 Global
1382 Synopsis:
1383 [2addr] g[lobal] /pattern/ [commands]
1386 [2addr] v /pattern/ [commands]
1387 The optional '!' character after the global command shall be the same
1390 as executing the v command.
1391 If pattern is empty (for example, "//" ) or not specified, the last
1393 regular expression used in the editor command shall be used as the pat‐
1394 tern. The pattern can be delimited by slashes (shown in the Synopsis),
1395 as well as any non-alphanumeric or non- <blank> other than backslash,
1396 vertical line, double quote, or <newline>.
1397 If no lines are specified, the lines shall default to the entire file.
1399 The global and v commands are logically two-pass operations. First,
1401 mark the lines within the specified lines for which the line excluding
1402 the terminating <newline> matches ( global) or does not match ( v or
1403 global!) the specified pattern. Second, execute the ex commands given
1404 by commands, with the current line ( '.' ) set to each marked line. If
1405 an error occurs during this process, or the contents of the edit buffer
1406 are replaced (for example, by the ex :edit command) an error message
1407 shall be written and no more commands resulting from the execution of
1408 this command shall be processed.
1409 Multiple ex commands can be specified by entering multiple commands on
1411 a single line using a vertical line to delimit them, or one per line,
1412 by escaping each <newline> with a backslash.
1413 If no commands are specified:
1415 1. If in ex command mode, it shall be as if the print command were
1417 specified.
1418 2. Otherwise, no command shall be executed.
1420 For the append, change, and insert commands, the input text shall be
1422 included as part of the command, and the terminating period can be
1423 omitted if the command ends the list of commands. The open and visual
1424 commands can be specified as one of the commands, in which case each
1425 marked line shall cause the editor to enter open or visual mode. If
1426 open or visual mode is exited using the vi Q command, the current line
1427 shall be set to the next marked line, and open or visual mode reen‐
1428 tered, until the list of marked lines is exhausted.
1429 The global, v, and undo commands cannot be used in commands. Marked
1431 lines may be deleted by commands executed for lines occurring earlier
1432 in the file than the marked lines. In this case, no commands shall be
1433 executed for the deleted lines.
1434 If the remembered search direction is not set, the global and v com‐
1436 mands shall set it to forward.
1437 The autoprint and autoindent edit options shall be inhibited for the
1439 duration of the g or v command.
1440 Current line: If no commands executed, set to the last marked line.
1442 Otherwise, as specified for the executed ex commands.
1443 Current column: If no commands are executed, set to non- <blank>; oth‐
1445 erwise, as specified for the individual ex commands.
1446 Insert
1448 Synopsis:
1449 [1addr] i[nsert][!]
1452 Enter ex text input mode; the input text shall be placed before the
1455 specified line. If the line is zero or 1, the text shall be placed at
1456 the beginning of the edit buffer.
1457 This command shall be affected by the number and autoindent edit
1459 options; following the command name with '!' shall cause the autoindent
1460 edit option setting to be toggled for the duration of this command
1461 only.
1462 Current line: Set to the last input line; if no lines were input, set
1464 to the line before the specified line, or to the first line of the edit
1465 buffer if there are no lines preceding the specified line, or zero if
1466 the edit buffer is empty.
1467 Current column: Set to non- <blank>.
1469 Join
1471 Synopsis:
1472 [2addr] j[oin][!][count][flags]
1475 If count is specified: If no address was specified, the join command
1478 shall behave as if 2addr were the current line and the current line
1479 plus count (.,. + count).
1480 If one address was specified, the join command shall behave as if 2addr
1482 were the specified address and the specified address plus count ( addr,
1483 addr + count).
1484 If two addresses were specified, the join command shall behave as if an
1486 additional address, equal to the last address plus count -1 ( addr1,
1487 addr2, addr2 + count -1), was specified.
1488 If this would result in a second address greater than the last line of
1490 the edit buffer, it shall be corrected to be equal to the last line of
1491 the edit buffer.
1492 If no count is specified: If no address was specified, the join command
1494 shall behave as if 2addr were the current line and the next line (.,.
1495 +1).
1496 If one address was specified, the join command shall behave as if 2addr
1498 were the specified address and the next line ( addr, addr +1).
1499 Join the text from the specified lines together into a single line,
1501 which shall replace the specified lines.
1502 If a '!' character is appended to the command name, the join shall be
1504 without modification of any line, independent of the current locale.
1505 Otherwise, in the POSIX locale, set the current line to the first of
1507 the specified lines, and then, for each subsequent line, proceed as
1508 follows:
1509 1. Discard leading <space>s from the line to be joined.
1511 2. If the line to be joined is now empty, delete it, and skip steps 3
1513 through 5.
1514 3. If the current line ends in a <blank>, or the first character of
1516 the line to be joined is a ')' character, join the lines without
1517 further modification.
1518 4. If the last character of the current line is a '.', join the lines
1520 with two <space>s between them.
1521 5. Otherwise, join the lines with a single <space> between them.
1523 Current line: Set to the first line specified.
1525 Current column: Set to non- <blank>.
1527 List
1529 Synopsis:
1530 [2addr] l[ist][count][flags]
1533 This command shall be equivalent to the ex command:
1536 [2addr] p[rint][count] l[flags]
1539 See Print .
1541 Map
1543 Synopsis:
1544 map[!][lhs rhs]
1547 If lhs and rhs are not specified:
1550 1. If '!' is specified, write the current list of text input mode
1552 maps.
1553 2. Otherwise, write the current list of command mode maps.
1555 3. Do nothing more.
1557 Implementations may restrict the set of characters accepted in lhs or
1559 rhs, except that printable characters and <blank>s shall not be
1560 restricted. Additional restrictions shall be implementation-defined. In
1561 both lhs and rhs, any character can be escaped with a <control>-V, in
1562 which case the character shall not be used to delimit lhs from rhs, and
1563 the escaping <control>-V shall be discarded.
1564 If the character '!' is appended to the map command name, the mapping
1566 shall be effective during open or visual text input mode rather than
1567 open or visual command mode. This allows lhs to have two different map
1568 definitions at the same time: one for command mode and one for text
1569 input mode.
1570 For command mode mappings: When the lhs is entered as any part of a vi
1572 command in open or visual mode (but not as part of the arguments to the
1573 command), the action shall be as if the corresponding rhs had been
1574 entered.
1575 If any character in the command, other than the first, is escaped using
1577 a <control>-V character, that character shall not be part of a match to
1578 an lhs.
1579 It is unspecified whether implementations shall support map commands
1581 where the lhs is more than a single character in length, where the
1582 first character of the lhs is printable.
1583 If lhs contains more than one character and the first character is '#',
1585 followed by a sequence of digits corresponding to a numbered function
1586 key, then when this function key is typed it shall be mapped to rhs.
1587 Characters other than digits following a '#' character also represent
1588 the function key named by the characters in the lhs following the '#'
1589 and may be mapped to rhs. It is unspecified how function keys are named
1590 or what function keys are supported.
1591 For text input mode mappings: When the lhs is entered as any part of
1593 text entered in open or visual text input modes, the action shall be as
1594 if the corresponding rhs had been entered.
1595 If any character in the input text is escaped using a <control>-V char‐
1597 acter, that character shall not be part of a match to an lhs.
1598 It is unspecified whether the lhs text entered for subsequent map or
1600 unmap commands is replaced with the rhs text for the purposes of the
1601 screen display; regardless of whether or not the display appears as if
1602 the corresponding rhs text was entered, the effect of the command shall
1603 be as if the lhs text was entered.
1604 If only part of the lhs is entered, it is unspecified how long the edi‐
1606 tor will wait for additional, possibly matching characters before
1607 treating the already entered characters as not matching the lhs.
1608 The rhs characters shall themselves be subject to remapping, unless
1610 otherwise specified by the remap edit option, except that if the char‐
1611 acters in lhs occur as prefix characters in rhs, those characters shall
1612 not be remapped.
1613 On block-mode terminals, the mapping need not occur immediately (for
1615 example, it may occur after the terminal transmits a group of charac‐
1616 ters to the system), but it shall achieve the same results as if it
1617 occurred immediately.
1618 Current line: Unchanged.
1620 Current column: Unchanged.
1622 Mark
1624 Synopsis:
1625 [1addr] ma[rk] character
1628 [1addr] k character
1629 Implementations shall support character values of a single lowercase
1632 letter of the POSIX locale and the characters '`' and '" ; support of
1633 other characters is implementation-defined.
1634 If executing the vi m command, set the specified mark to the current
1636 line and 1-based numbered character referenced by the current column,
1637 if any; otherwise, column position 1.
1638 Otherwise, set the specified mark to the specified line and 1-based
1640 numbered first non- <blank> non- <newline> in the line, if any; other‐
1641 wise, the last non- <newline> in the line, if any; otherwise, column
1642 position 1.
1643 The mark shall remain associated with the line until the mark is reset
1645 or the line is deleted. If a deleted line is restored by a subsequent
1646 undo command, any marks previously associated with the line, which have
1647 not been reset, shall be restored as well. Any use of a mark not asso‐
1648 ciated with a current line in the edit buffer shall be an error.
1649 The marks ` and ' shall be set as described previously, immediately
1651 before the following events occur in the editor:
1652 1. The use of '$' as an ex address
1654 2. The use of a positive decimal number as an ex address
1656 3. The use of a search command as an ex address
1658 4. The use of a mark reference as an ex address
1660 5. The use of the following open and visual mode commands: <con‐
1662 trol>-], %, (, ), [, ], {, }
1663 6. The use of the following open and visual mode commands: ', G, H, L,
1665 M, z if the current line will change as a result of the command
1666 7. The use of the open and visual mode commands: /, ?, N, `, n if the
1668 current line or column will change as a result of the command
1669 8. The use of the ex mode commands: z, undo, global, v
1671 For rules 1., 2., 3., and 4., the ` and ' marks shall not be set if the
1673 ex command is parsed as specified by rule 6.a. in Command Line Parsing
1674 in ex .
1675 For rules 5., 6., and 7., the ` and ' marks shall not be set if the
1677 commands are used as motion commands in open and visual mode.
1678 For rules 1., 2., 3., 4., 5., 6., 7., and 8., the ` and ' marks shall
1680 not be set if the command fails.
1681 The ` and ' marks shall be set as described previously, each time the
1683 contents of the edit buffer are replaced (including the editing of the
1684 initial buffer), if in open or visual mode, or if in ex mode and the
1685 edit buffer is not empty, before any commands or movements (including
1686 commands or movements specified by the -c or -t options or the + com‐
1687 mand argument) are executed on the edit buffer. If in open or visual
1688 mode, the marks shall be set as if executing the vi m command; other‐
1689 wise, as if executing the ex mark command.
1690 When changing from ex mode to open or visual mode, if the ` and ' marks
1692 are not already set, the ` and ' marks shall be set as described previ‐
1693 ously.
1694 Current line: Unchanged.
1696 Current column: Unchanged.
1698 Move
1700 Synopsis:
1701 [2addr] m[ove] 1addr [flags]
1704 Move the specified lines after the specified destination line. A desti‐
1707 nation of line zero specifies that the lines shall be placed at the
1708 beginning of the edit buffer. It shall be an error if the destination
1709 line is within the range of lines to be moved.
1710 Current line: Set to the last of the moved lines.
1712 Current column: Set to non- <blank>.
1714 Next
1716 Synopsis:
1717 n[ext][!][+command][file ...]
1720 If no '!' is appended to the command name, and the edit buffer has been
1723 modified since the last complete write, it shall be an error, unless
1724 the file is successfully written as specified by the autowrite option.
1725 If one or more files is specified:
1727 1. Set the argument list to the specified filenames.
1729 2. Set the current argument list reference to be the first entry in
1731 the argument list.
1732 3. Set the current pathname to the first filename specified.
1734 Otherwise:
1736 1. It shall be an error if there are no more filenames in the argument
1738 list after the filename currently referenced.
1739 2. Set the current pathname and the current argument list reference to
1741 the filename after the filename currently referenced in the argu‐
1742 ment list.
1743 Replace the contents of the edit buffer with the contents of the file
1745 named by the current pathname. If for any reason the contents of the
1746 file cannot be accessed, the edit buffer shall be empty.
1747 This command shall be affected by the autowrite and writeany edit
1749 options.
1750 The + command option shall be <blank>-delimited; <blank>s can be
1752 escaped by preceding them with a backslash character. The + command
1753 shall be interpreted as an ex command immediately after the contents of
1754 the edit buffer have been replaced and the current line and column have
1755 been set.
1756 Current line: Set as described for the edit command.
1758 Current column: Set as described for the edit command.
1760 Number
1762 Synopsis:
1763 [2addr] nu[mber][count][flags]
1766 [2addr] #[count][flags]
1767 These commands shall be equivalent to the ex command:
1770 [2addr] p[rint][count] #[flags]
1773 See Print .
1775 Open
1777 Synopsis:
1778 [1addr] o[pen] /pattern/ [flags]
1781 This command need not be supported on block-mode terminals or terminals
1784 with insufficient capabilities. If standard input, standard output, or
1785 standard error are not terminal devices, the results are unspecified.
1786 Enter open mode.
1788 The trailing delimiter can be omitted from pattern at the end of the
1790 command line. If pattern is empty (for example, "//" ) or not speci‐
1791 fied, the last regular expression used in the editor shall be used as
1792 the pattern. The pattern can be delimited by slashes (shown in the Syn‐
1793 opsis), as well as any alphanumeric, or non- <blank> other than back‐
1794 slash, vertical line, double quote, or <newline>.
1795 Current line: Set to the specified line.
1797 Current column: Set to non- <blank>.
1799 Preserve
1801 Synopsis:
1802 pre[serve]
1805 Save the edit buffer in a form that can later be recovered by using the
1808 -r option or by using the ex recover command. After the file has been
1809 preserved, a mail message shall be sent to the user. This message shall
1810 be readable by invoking the mailx utility. The message shall contain
1811 the name of the file, the time of preservation, and an ex command that
1812 could be used to recover the file. Additional information may be
1813 included in the mail message.
1814 Current line: Unchanged.
1816 Current column: Unchanged.
1818 Print
1820 Synopsis:
1821 [2addr] p[rint][count][flags]
1824 Write the addressed lines. The behavior is unspecified if the number of
1827 columns on the display is less than the number of columns required to
1828 write any single character in the lines being written.
1829 Non-printable characters, except for the <tab>, shall be written as
1831 implementation-defined multi-character sequences.
1832 If the # flag is specified or the number edit option is set, each line
1834 shall be preceded by its line number in the following format:
1835 "%6d ", <line number>
1838 If the l flag is specified or the list edit option is set:
1840 1. The characters listed in the Base Definitions volume of
1842 IEEE Std 1003.1-2001, Table 5-1, Escape Sequences and Associated
1843 Actions shall be written as the corresponding escape sequence.
1844 2. Non-printable characters not in the Base Definitions volume of
1846 IEEE Std 1003.1-2001, Table 5-1, Escape Sequences and Associated
1847 Actions shall be written as one three-digit octal number (with a
1848 preceding backslash) for each byte in the character (most signifi‐
1849 cant byte first). If the size of a byte on the system is greater
1850 than 9 bits, the format used for non-printable characters is imple‐
1851 mentation-defined.
1852 3. The end of each line shall be marked with a '$', and literal '$'
1854 characters within the line shall be written with a preceding back‐
1855 slash.
1856 Long lines shall be folded; the length at which folding occurs is
1858 unspecified, but should be appropriate for the output terminal, consid‐
1859 ering the number of columns of the terminal.
1860 If a line is folded, and the l flag is not specified and the list edit
1862 option is not set, it is unspecified whether a multi-column character
1863 at the folding position is separated; it shall not be discarded.
1864 Current line: Set to the last written line.
1866 Current column: Unchanged if the current line is unchanged; otherwise,
1868 set to non- <blank>.
1869 Put
1871 Synopsis:
1872 [1addr] pu[t][buffer]
1875 Append text from the specified buffer (by default, the unnamed buffer)
1878 to the specified line; line zero specifies that the text shall be
1879 placed at the beginning of the edit buffer. Each portion of a line in
1880 the buffer shall become a new line in the edit buffer, regardless of
1881 the mode of the buffer.
1882 Current line: Set to the last line entered into the edit buffer.
1884 Current column: Set to non- <blank>.
1886 Quit
1888 Synopsis:
1889 q[uit][!]
1892 If no '!' is appended to the command name:
1895 1. If the edit buffer has been modified since the last complete write,
1897 it shall be an error.
1898 2. If there are filenames in the argument list after the filename cur‐
1900 rently referenced, and the last command was not a quit, wq, xit, or
1901 ZZ (see Exit ) command, it shall be an error.
1902 Otherwise, terminate the editing session.
1904 Read
1906 Synopsis:
1907 [1addr] r[ead][!][file]
1910 If '!' is not the first non- <blank> to follow the command name, a copy
1913 of the specified file shall be appended into the edit buffer after the
1914 specified line; line zero specifies that the copy shall be placed at
1915 the beginning of the edit buffer. The number of lines and bytes read
1916 shall be written. If no file is named, the current pathname shall be
1917 the default. If there is no current pathname, then file shall become
1918 the current pathname. If there is no current pathname or file operand,
1919 it shall be an error. Specifying a file that is not of type regular
1920 shall have unspecified results.
1921 Otherwise, if file is preceded by '!', the rest of the line after the
1923 '!' shall have '%', '#', and '!' characters expanded as described in
1924 Command Line Parsing in ex .
1925 The ex utility shall then pass two arguments to the program named by
1927 the shell edit option; the first shall be -c and the second shall be
1928 the expanded arguments to the read command as a single argument. The
1929 standard input of the program shall be set to the standard input of the
1930 ex program when it was invoked. The standard error and standard output
1931 of the program shall be appended into the edit buffer after the speci‐
1932 fied line.
1933 Each line in the copied file or program output (as delimited by <new‐
1935 line>s or the end of the file or output if it is not immediately pre‐
1936 ceded by a <newline>), shall be a separate line in the edit buffer. Any
1937 occurrences of <carriage-return> and <newline> pairs in the output
1938 shall be treated as single <newline>s.
1939 The special meaning of the '!' following the read command can be over‐
1941 ridden by escaping it with a backslash character.
1942 Current line: If no lines are added to the edit buffer, unchanged.
1944 Otherwise, if in open or visual mode, set to the first line entered
1945 into the edit buffer. Otherwise, set to the last line entered into the
1946 edit buffer.
1947 Current column: Set to non- <blank>.
1949 Recover
1951 Synopsis:
1952 rec[over][!] file
1955 If no '!' is appended to the command name, and the edit buffer has been
1958 modified since the last complete write, it shall be an error.
1959 If no file operand is specified, then the current pathname shall be
1961 used. If there is no current pathname or file operand, it shall be an
1962 error.
1963 If no recovery information has previously been saved about file, the
1965 recover command shall behave identically to the edit command, and an
1966 informational message to this effect shall be written.
1967 Otherwise, set the current pathname to file, and replace the current
1969 contents of the edit buffer with the recovered contents of file. If
1970 there are multiple instances of the file to be recovered, the one most
1971 recently saved shall be recovered, and an informational message that
1972 there are previous versions of the file that can be recovered shall be
1973 written. The editor shall behave as if the contents of the edit buffer
1974 have already been modified.
1975 Current file: Set as described for the edit command.
1977 Current column: Set as described for the edit command.
1979 Rewind
1981 Synopsis:
1982 rew[ind][!]
1985 If no '!' is appended to the command name, and the edit buffer has been
1988 modified since the last complete write, it shall be an error, unless
1989 the file is successfully written as specified by the autowrite option.
1990 If the argument list is empty, it shall be an error.
1992 The current argument list reference and the current pathname shall be
1994 set to the first filename in the argument list.
1995 Replace the contents of the edit buffer with the contents of the file
1997 named by the current pathname. If for any reason the contents of the
1998 file cannot be accessed, the edit buffer shall be empty.
1999 This command shall be affected by the autowrite and writeany edit
2001 options.
2002 Current line: Set as described for the edit command.
2004 Current column: Set as described for the edit command.
2006 Set
2008 Synopsis:
2009 se[t][option[=[value]] ...][nooption ...][option? ...][all]
2012 When no arguments are specified, write the value of the term edit
2015 option and those options whose values have been changed from the
2016 default settings; when the argument all is specified, write all of the
2017 option values.
2018 Giving an option name followed by the character '?' shall cause the
2020 current value of that option to be written. The '?' can be separated
2021 from the option name by zero or more <blank>s. The '?' shall be neces‐
2022 sary only for Boolean valued options. Boolean options can be given val‐
2023 ues by the form set option to turn them on or set no option to turn
2024 them off; string and numeric options can be assigned by the form set
2025 option= value. Any <blank>s in strings can be included as is by preced‐
2026 ing each <blank> with an escaping backslash. More than one option can
2027 be set or listed by a single set command by specifying multiple argu‐
2028 ments, each separated from the next by one or more <blank>s.
2029 See Edit Options in ex for details about specific options.
2031 Current line: Unchanged.
2033 Current column: Unchanged.
2035 Shell
2037 Synopsis:
2038 sh[ell]
2041 Invoke the program named in the shell edit option with the single argu‐
2044 ment -i (interactive mode). Editing shall be resumed when the program
2045 exits.
2046 Current line: Unchanged.
2048 Current column: Unchanged.
2050 Source
2052 Synopsis:
2053 so[urce] file
2056 Read and execute ex commands from file. Lines in the file that are
2059 blank lines shall be ignored.
2060 Current line: As specified for the individual ex commands.
2062 Current column: As specified for the individual ex commands.
2064 Substitute
2066 Synopsis:
2067 [2addr] s[ubstitute][/pattern/repl/[options][count][flags]]
2070 [2addr] &[options][count][flags]]
2072 [2addr] ~[options][count][flags]]
2074 Replace the first instance of the pattern pattern by the string repl on
2077 each specified line. (See Regular Expressions in ex and Replacement
2078 Strings in ex .) Any non-alphabetic, non- <blank> delimiter other than
2079 '\', '|', double quote, or <newline> can be used instead of '/' . Back‐
2080 slash characters can be used to escape delimiters, backslash charac‐
2081 ters, and other special characters.
2082 The trailing delimiter can be omitted from pattern or from repl at the
2084 end of the command line. If both pattern and repl are not specified or
2085 are empty (for example, "//" ), the last s command shall be repeated.
2086 If only pattern is not specified or is empty, the last regular expres‐
2087 sion used in the editor shall be used as the pattern. If only repl is
2088 not specified or is empty, the pattern shall be replaced by nothing. If
2089 the entire replacement pattern is '%', the last replacement pattern to
2090 an s command shall be used.
2091 Entering a <carriage-return> in repl (which requires an escaping back‐
2093 slash in ex mode and an escaping <control>-V in open or vi mode) shall
2094 split the line at that point, creating a new line in the edit buffer.
2095 The <carriage-return> shall be discarded.
2096 If options includes the letter 'g' ( global), all non-overlapping
2098 instances of the pattern in the line shall be replaced.
2099 If options includes the letter 'c' ( confirm), then before each substi‐
2101 tution the line shall be written; the written line shall reflect all
2102 previous substitutions. On the following line, <space>s shall be writ‐
2103 ten beneath the characters from the line that are before the pattern to
2104 be replaced, and '^' characters written beneath the characters included
2105 in the pattern to be replaced. The ex utility shall then wait for a
2106 response from the user. An affirmative response shall cause the substi‐
2107 tution to be done, while any other input shall not make the substitu‐
2108 tion. An affirmative response shall consist of a line with the affirma‐
2109 tive response (as defined by the current locale) at the beginning of
2110 the line. This line shall be subject to editing in the same way as the
2111 ex command line.
2112 If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications
2114 confirmed by the user shall be preserved in the edit buffer after the
2115 interrupt.
2116 If the remembered search direction is not set, the s command shall set
2118 it to forward.
2119 In the second Synopsis, the & command shall repeat the previous substi‐
2121 tution, as if the & command were replaced by:
2122 s/pattern/repl/
2125 where pattern and repl are as specified in the previous s, &, or ~ com‐
2127 mand.
2128 In the third Synopsis, the ~ command shall repeat the previous substi‐
2130 tution, as if the '~' were replaced by:
2131 s/pattern/repl/
2134 where pattern shall be the last regular expression specified to the
2136 editor, and repl shall be from the previous substitution (including &
2137 and ~) command.
2138 These commands shall be affected by the LC_MESSAGES environment vari‐
2140 able.
2141 Current line: Set to the last line in which a substitution occurred,
2143 or, unchanged if no substitution occurred.
2144 Current column: Set to non- <blank>.
2146 Suspend
2148 Synopsis:
2149 su[spend][!]st[op][!]
2152 Allow control to return to the invoking process; ex shall suspend
2155 itself as if it had received the SIGTSTP signal. The suspension shall
2156 occur only if job control is enabled in the invoking shell (see the
2157 description of set -m).
2158 These commands shall be affected by the autowrite and writeany edit
2160 options.
2161 The current susp character (see stty ) shall be equivalent to the sus‐
2163 pend command.
2164 Tag
2166 Synopsis:
2167 ta[g][!] tagstring
2170 The results are unspecified if the format of a tags file is not as
2173 specified by the ctags utility (see ctags ) description.
2174 The tag command shall search for tagstring in the tag files referred to
2176 by the tag edit option, in the order they are specified, until a refer‐
2177 ence to tagstring is found. Files shall be searched from beginning to
2178 end. If no reference is found, it shall be an error and an error mes‐
2179 sage to this effect shall be written. If the reference is not found, or
2180 if an error occurs while processing a file referred to in the tag edit
2181 option, it shall be an error, and an error message shall be written at
2182 the first occurrence of such an error.
2183 Otherwise, if the tags file contained a pattern, the pattern shall be
2185 treated as a regular expression used in the editor; for example, for
2186 the purposes of the s command.
2187 If the tagstring is in a file with a different name than the current
2189 pathname, set the current pathname to the name of that file, and
2190 replace the contents of the edit buffer with the contents of that file.
2191 In this case, if no '!' is appended to the command name, and the edit
2192 buffer has been modified since the last complete write, it shall be an
2193 error, unless the file is successfully written as specified by the
2194 autowrite option.
2195 This command shall be affected by the autowrite, tag, taglength, and
2197 writeany edit options.
2198 Current line: If the tags file contained a line number, set to that
2200 line number. If the line number is larger than the last line in the
2201 edit buffer, an error message shall be written and the current line
2202 shall be set as specified for the edit command.
2203 If the tags file contained a pattern, set to the first occurrence of
2205 the pattern in the file. If no matching pattern is found, an error mes‐
2206 sage shall be written and the current line shall be set as specified
2207 for the edit command.
2208 Current column: If the tags file contained a line-number reference and
2210 that line-number was not larger than the last line in the edit buffer,
2211 or if the tags file contained a pattern and that pattern was found, set
2212 to non- <blank>. Otherwise, set as specified for the edit command.
2213 Unabbreviate
2215 Synopsis:
2216 una[bbrev] lhs
2219 If lhs is not an entry in the current list of abbreviations (see Abbre‐
2222 viate ), it shall be an error. Otherwise, delete lhs from the list of
2223 abbreviations.
2224 Current line: Unchanged.
2226 Current column: Unchanged.
2228 Undo
2230 Synopsis:
2231 u[ndo]
2234 Reverse the changes made by the last command that modified the contents
2237 of the edit buffer, including undo. For this purpose, the global, v,
2238 open, and visual commands, and commands resulting from buffer execu‐
2239 tions and mapped character expansions, are considered single commands.
2240 If no action that can be undone preceded the undo command, it shall be
2242 an error.
2243 If the undo command restores lines that were marked, the mark shall
2245 also be restored unless it was reset subsequent to the deletion of the
2246 lines.
2247 Current line:
2249 1. If lines are added or changed in the file, set to the first line
2251 added or changed.
2252 2. Set to the line before the first line deleted, if it exists.
2254 3. Set to 1 if the edit buffer is not empty.
2256 4. Set to zero.
2258 Current column: Set to non- <blank>.
2260 Unmap
2262 Synopsis:
2263 unm[ap][!] lhs
2266 If '!' is appended to the command name, and if lhs is not an entry in
2269 the list of text input mode map definitions, it shall be an error. Oth‐
2270 erwise, delete lhs from the list of text input mode map definitions.
2271 If no '!' is appended to the command name, and if lhs is not an entry
2273 in the list of command mode map definitions, it shall be an error. Oth‐
2274 erwise, delete lhs from the list of command mode map definitions.
2275 Current line: Unchanged.
2277 Current column: Unchanged.
2279 Version
2281 Synopsis:
2282 ve[rsion]
2285 Write a message containing version information for the editor. The for‐
2288 mat of the message is unspecified.
2289 Current line: Unchanged.
2291 Current column: Unchanged.
2293 Visual
2295 Synopsis:
2296 [1addr] vi[sual][type][count][flags]
2299 If ex is currently in open or visual mode, the Synopsis and behavior of
2302 the visual command shall be the same as the edit command, as specified
2303 by Edit .
2304 Otherwise, this command need not be supported on block-mode terminals
2306 or terminals with insufficient capabilities. If standard input, stan‐
2307 dard output, or standard error are not terminal devices, the results
2308 are unspecified.
2309 If count is specified, the value of the window edit option shall be set
2311 to count (as described in window ). If the '^' type character was also
2312 specified, the window edit option shall be set before being used by the
2313 type character.
2314 Enter visual mode. If type is not specified, it shall be as if a type
2316 of '+' was specified. The type shall cause the following effects:
2317 + Place the beginning of the specified line at the top of the dis‐
2319 play.
2320 - Place the end of the specified line at the bottom of the dis‐
2322 play.
2323 . Place the beginning of the specified line in the middle of the
2325 display.
2326 ^ If the specified line is less than or equal to the value of the
2328 window edit option, set the line to 1; otherwise, decrement the
2329 line by the value of the window edit option minus 1. Place the
2330 beginning of this line as close to the bottom of the displayed
2331 lines as possible, while still displaying the value of the win‐
2332 dow edit option number of lines.
2333 Current line: Set to the specified line.
2336 Current column: Set to non- <blank>.
2338 Write
2340 Synopsis:
2341 [2addr] w[rite][!][>>][file]
2344 [2addr] w[rite][!][file]
2345 [2addr] wq[!][>>][file]
2346 If no lines are specified, the lines shall default to the entire file.
2349 The command wq shall be equivalent to a write command followed by a
2351 quit command; wq! shall be equivalent to write! followed by quit. In
2352 both cases, if the write command fails, the quit shall not be
2353 attempted.
2354 If the command name is not followed by one or more <blank>s, or file is
2356 not preceded by a '!' character, the write shall be to a file.
2357 1. If the >> argument is specified, and the file already exists, the
2359 lines shall be appended to the file instead of replacing its con‐
2360 tents. If the >> argument is specified, and the file does not
2361 already exist, it is unspecified whether the write shall proceed as
2362 if the >> argument had not been specified or if the write shall
2363 fail.
2364 2. If the readonly edit option is set (see readonly ), the write shall
2366 fail.
2367 3. If file is specified, and is not the current pathname, and the file
2369 exists, the write shall fail.
2370 4. If file is not specified, the current pathname shall be used. If
2372 there is no current pathname, the write command shall fail.
2373 5. If the current pathname is used, and the current pathname has been
2375 changed by the file or read commands, and the file exists, the
2376 write shall fail. If the write is successful, subsequent writes
2377 shall not fail for this reason (unless the current pathname is
2378 changed again).
2379 6. If the whole edit buffer is not being written, and the file to be
2381 written exists, the write shall fail.
2382 For rules 1., 2., 4., and 5., the write can be forced by appending the
2384 character '!' to the command name.
2385 For rules 2., 4., and 5., the write can be forced by setting the
2387 writeany edit option.
2388 Additional, implementation-defined tests may cause the write to fail.
2390 If the edit buffer is empty, a file without any contents shall be writ‐
2392 ten.
2393 An informational message shall be written noting the number of lines
2395 and bytes written.
2396 Otherwise, if the command is followed by one or more <blank>s, and the
2398 file is preceded by '!', the rest of the line after the '!' shall have
2399 '%', '#', and '!' characters expanded as described in Command Line
2400 Parsing in ex .
2401 The ex utility shall then pass two arguments to the program named by
2403 the shell edit option; the first shall be -c and the second shall be
2404 the expanded arguments to the write command as a single argument. The
2405 specified lines shall be written to the standard input of the command.
2406 The standard error and standard output of the program, if any, shall be
2407 written as described for the print command. If the last character in
2408 that output is not a <newline>, a <newline> shall be written at the end
2409 of the output.
2410 The special meaning of the '!' following the write command can be over‐
2412 ridden by escaping it with a backslash character.
2413 Current line: Unchanged.
2415 Current column: Unchanged.
2417 Write and Exit
2419 Synopsis:
2420 [2addr] x[it][!][file]
2423 If the edit buffer has not been modified since the last complete write,
2426 xit shall be equivalent to the quit command, or if a '!' is appended to
2427 the command name, to quit!.
2428 Otherwise, xit shall be equivalent to the wq command, or if a '!' is
2430 appended to the command name, to wq!.
2431 Current line: Unchanged.
2433 Current column: Unchanged.
2435 Yank
2437 Synopsis:
2438 [2addr] ya[nk][buffer][count]
2441 Copy the specified lines to the specified buffer (by default, the
2444 unnamed buffer), which shall become a line-mode buffer.
2445 Current line: Unchanged.
2447 Current column: Unchanged.
2449 Adjust Window
2451 Synopsis:
2452 [1addr] z[!][type ...][count][flags]
2455 If no line is specified, the current line shall be the default; if type
2458 is omitted as well, the current line value shall first be incremented
2459 by 1. If incrementing the current line would cause it to be greater
2460 than the last line in the edit buffer, it shall be an error.
2461 If there are <blank>s between the type argument and the preceding z
2463 command name or optional '!' character, it shall be an error.
2464 If count is specified, the value of the window edit option shall be set
2466 to count (as described in window ). If count is omitted, it shall
2467 default to 2 times the value of the scroll edit option, or if ! was
2468 specified, the number of lines in the display minus 1.
2469 If type is omitted, then count lines starting with the specified line
2471 shall be written. Otherwise, count lines starting with the line speci‐
2472 fied by the type argument shall be written.
2473 The type argument shall change the lines to be written. The possible
2475 values of type are as follows:
2476 - The specified line shall be decremented by the following value:
2478 (((number of "-" characters) x count) -1)
2481 If the calculation would result in a number less than 1, it shall be an
2483 error. Write lines from the edit buffer, starting at the new value of
2484 line, until count lines or the last line in the edit buffer has been
2485 written.
2486 + The specified line shall be incremented by the following value:
2488 (((number of "+" characters) -1) x count) +1
2491 If the calculation would result in a number greater than the last line
2493 in the edit buffer, it shall be an error. Write lines from the edit
2494 buffer, starting at the new value of line, until count lines or the
2495 last line in the edit buffer has been written.
2496 =,. If more than a single '.' or '=' is specified, it shall be an
2498 error. The following steps shall be taken:
2499 1. If count is zero, nothing shall be written.
2501 2. Write as many of the N lines before the current line in the
2503 edit buffer as exist. If count or '!' was specified, N shall
2504 be:
2505 (count -1) /2
2508 Otherwise, N shall be:
2510 (count -3) /2
2513 If N is a number less than 3, no lines shall be written.
2515 3. If '=' was specified as the type character, write a line
2517 consisting of the smaller of the number of columns in the
2518 display divided by two, or 40 '-' characters.
2519 4. Write the current line.
2521 5. Repeat step 3.
2523 6. Write as many of the N lines after the current line in the
2525 edit buffer as exist. N shall be defined as in step 2. If N
2526 is a number less than 3, no lines shall be written. If count
2527 is less than 3, no lines shall be written.
2528 ^ The specified line shall be decremented by the following value:
2530 (((number of "^" characters) +1) x count) -1
2533 If the calculation would result in a number less than 1, it shall be an
2535 error. Write lines from the edit buffer, starting at the new value of
2536 line, until count lines or the last line in the edit buffer has been
2537 written.
2538 Current line: Set to the last line written, unless the type is =, in
2541 which case, set to the specified line.
2542 Current column: Set to non- <blank>.
2544 Escape
2546 Synopsis:
2547 ! command
2550 [addr]! command
2551 The contents of the line after the '!' shall have '%', '#', and '!'
2554 characters expanded as described in Command Line Parsing in ex . If the
2555 expansion causes the text of the line to change, it shall be redis‐
2556 played, preceded by a single '!' character.
2557 The ex utility shall execute the program named by the shell edit
2559 option. It shall pass two arguments to the program; the first shall be
2560 -c, and the second shall be the expanded arguments to the ! command as
2561 a single argument.
2562 If no lines are specified, the standard input, standard output, and
2564 standard error of the program shall be set to the standard input, stan‐
2565 dard output, and standard error of the ex program when it was invoked.
2566 In addition, a warning message shall be written if the edit buffer has
2567 been modified since the last complete write, and the warn edit option
2568 is set.
2569 If lines are specified, they shall be passed to the program as standard
2571 input, and the standard output and standard error of the program shall
2572 replace those lines in the edit buffer. Each line in the program output
2573 (as delimited by <newline>s or the end of the output if it is not imme‐
2574 diately preceded by a <newline>), shall be a separate line in the edit
2575 buffer. Any occurrences of <carriage-return> and <newline> pairs in the
2576 output shall be treated as single <newline>s. The specified lines shall
2577 be copied into the unnamed buffer before they are replaced, and the
2578 unnamed buffer shall become a line-mode buffer.
2579 If in ex mode, a single '!' character shall be written when the program
2581 completes.
2582 This command shall be affected by the shell and warn edit options. If
2584 no lines are specified, this command shall be affected by the autowrite
2585 and writeany edit options. If lines are specified, this command shall
2586 be affected by the autoprint edit option.
2587 Current line:
2589 1. If no lines are specified, unchanged.
2591 2. Otherwise, set to the last line read in, if any lines are read in.
2593 3. Otherwise, set to the line before the first line of the lines spec‐
2595 ified, if that line exists.
2596 4. Otherwise, set to the first line of the edit buffer if the edit
2598 buffer is not empty.
2599 5. Otherwise, set to zero.
2601 Current column: If no lines are specified, unchanged. Otherwise, set to
2603 non- <blank>.
2604 Shift Left
2606 Synopsis:
2607 [2addr] <[< ...][count][flags]
2610 Shift the specified lines to the start of the line; the number of col‐
2613 umn positions to be shifted shall be the number of command characters
2614 times the value of the shiftwidth edit option. Only leading <blank>s
2615 shall be deleted or changed into other <blank>s in shifting; other
2616 characters shall not be affected.
2617 Lines to be shifted shall be copied into the unnamed buffer, which
2619 shall become a line-mode buffer.
2620 This command shall be affected by the autoprint edit option.
2622 Current line: Set to the last line in the lines specified.
2624 Current column: Set to non- <blank>.
2626 Shift Right
2628 Synopsis:
2629 [2addr] >[> ...][count][flags]
2632 Shift the specified lines away from the start of the line; the number
2635 of column positions to be shifted shall be the number of command char‐
2636 acters times the value of the shiftwidth edit option. The shift shall
2637 be accomplished by adding <blank>s as a prefix to the line or changing
2638 leading <blank>s into other <blank>s. Empty lines shall not be
2639 changed.
2640 Lines to be shifted shall be copied into the unnamed buffer, which
2642 shall become a line-mode buffer.
2643 This command shall be affected by the autoprint edit option.
2645 Current line: Set to the last line in the lines specified.
2647 Current column: Set to non- <blank>.
2649 <control>-D
2651 Synopsis:
2652 <control>-D
2655 Write the next n lines, where n is the minimum of the values of the
2658 scroll edit option and the number of lines after the current line in
2659 the edit buffer. If the current line is the last line of the edit buf‐
2660 fer it shall be an error.
2661 Current line: Set to the last line written.
2663 Current column: Set to non- <blank>.
2665 Write Line Number
2667 Synopsis:
2668 [1addr] = [flags]
2671 If line is not specified, it shall default to the last line in the edit
2674 buffer. Write the line number of the specified line.
2675 Current line: Unchanged.
2677 Current column: Unchanged.
2679 Execute
2681 Synopsis:
2682 [2addr] @ buffer[2addr] * buffer
2685 If no buffer is specified or is specified as '@' or '*', the last buf‐
2688 fer executed shall be used. If no previous buffer has been executed, it
2689 shall be an error.
2690 For each line specified by the addresses, set the current line ( '.' )
2692 to the specified line, and execute the contents of the named buffer (as
2693 they were at the time the @ command was executed) as ex commands. For
2694 each line of a line-mode buffer, and all but the last line of a charac‐
2695 ter-mode buffer, the ex command parser shall behave as if the line was
2696 terminated by a <newline>.
2697 If an error occurs during this process, or a line specified by the
2699 addresses does not exist when the current line would be set to it, or
2700 more than a single line was specified by the addresses, and the con‐
2701 tents of the edit buffer are replaced (for example, by the ex :edit
2702 command) an error message shall be written, and no more commands
2703 resulting from the execution of this command shall be processed.
2704 Current line: As specified for the individual ex commands.
2706 Current column: As specified for the individual ex commands.
2708 Regular Expressions in ex
2710 The ex utility shall support regular expressions that are a superset of
2711 the basic regular expressions described in the Base Definitions volume
2712 of IEEE Std 1003.1-2001, Section 9.3, Basic Regular Expressions. A null
2713 regular expression ( "//" ) shall be equivalent to the last regular
2714 expression encountered.
2715 Regular expressions can be used in addresses to specify lines and, in
2717 some commands (for example, the substitute command), to specify por‐
2718 tions of a line to be substituted.
2719 The following constructs can be used to enhance the basic regular
2721 expressions:
2722 \< Match the beginning of a word. (See the definition of word at
2724 the beginning of Command Descriptions in ex .)
2725 \> Match the end of a word.
2727 ~ Match the replacement part of the last substitute command. The
2729 tilde ( '~' ) character can be escaped in a regular expression
2730 to become a normal character with no special meaning. The back‐
2731 slash shall be discarded.
2732 When the editor option magic is not set, the only characters with spe‐
2735 cial meanings shall be '^' at the beginning of a pattern, '$' at the
2736 end of a pattern, and '\' . The characters '.', '*', '[', and '~'
2737 shall be treated as ordinary characters unless preceded by a '\' ; when
2738 preceded by a '\' they shall regain their special meaning, or in the
2739 case of backslash, be handled as a single backslash. Backslashes used
2740 to escape other characters shall be discarded.
2741 Replacement Strings in ex
2743 The character '&' ( '\&' if the editor option magic is not set) in the
2744 replacement string shall stand for the text matched by the pattern to
2745 be replaced. The character '~' ( '\~' if magic is not set) shall be
2746 replaced by the replacement part of the previous substitute command.
2747 The sequence '\n', where n is an integer, shall be replaced by the text
2748 matched by the pattern enclosed in the nth set of parentheses '\(' and
2749 '\)' .
2750 The strings '\l', '\u', '\L', and '\U' can be used to modify the case
2752 of elements in the replacement string (using the '\&' or "\" digit)
2753 notation. The string '\l' ( '\u' ) shall cause the character that fol‐
2754 lows to be converted to lowercase (uppercase). The string '\L' ( '\U'
2755 ) shall cause all characters subsequent to it to be converted to lower‐
2756 case (uppercase) as they are inserted by the substitution until the
2757 string '\e' or '\E', or the end of the replacement string, is encoun‐
2758 tered.
2759 Otherwise, any character following a backslash shall be treated as that
2761 literal character, and the escaping backslash shall be discarded.
2762 An example of case conversion with the s command is as follows:
2764 :p
2767 The cat sat on the mat.
2768 :s/\<.at\>/\u&/gp
2769 The Cat Sat on the Mat.
2770 :s/S\(.*\)M/S\U\1\eM/p
2771 The Cat SAT ON THE Mat.
2772 Edit Options in ex
2774 The ex utility has a number of options that modify its behavior. These
2775 options have default settings, which can be changed using the set com‐
2776 mand.
2777 Options are Boolean unless otherwise specified.
2779 autoindent, ai
2781 [Default unset]
2782 If autoindent is set, each line in input mode shall be indented (using
2784 first as many <tab>s as possible, as determined by the editor option
2785 tabstop, and then using <space>s) to align with another line, as fol‐
2786 lows:
2787 1. If in open or visual mode and the text input is part of a line-ori‐
2789 ented command (see the EXTENDED DESCRIPTION in vi ), align to the
2790 first column.
2791 2. Otherwise, if in open or visual mode, indentation for each line
2793 shall be set as follows:
2794 a. If a line was previously inserted as part of this command, it
2796 shall be set to the indentation of the last inserted line by
2797 default, or as otherwise specified for the <control>-D charac‐
2798 ter in Input Mode Commands in vi .
2799 b. Otherwise, it shall be set to the indentation of the previous
2801 current line, if any; otherwise, to the first column.
2802 3. For the ex a, i, and c commands, indentation for each line shall be
2804 set as follows:
2805 a. If a line was previously inserted as part of this command, it
2807 shall be set to the indentation of the last inserted line by
2808 default, or as otherwise specified for the eof character in
2809 Scroll .
2810 b. Otherwise, if the command is the ex a command, it shall be set
2812 to the line appended after, if any; otherwise to the first col‐
2813 umn.
2814 c. Otherwise, if the command is the ex i command, it shall be set
2816 to the line inserted before, if any; otherwise to the first
2817 column.
2818 d. Otherwise, if the command is the ex c command, it shall be set
2820 to the indentation of the line replaced.
2821 autoprint, ap
2823 [Default set]
2824 If autoprint is set, the current line shall be written after each ex
2826 command that modifies the contents of the current edit buffer, and
2827 after each tag command for which the tag search pattern was found or
2828 tag line number was valid, unless:
2829 1. The command was executed while in open or visual mode.
2831 2. The command was executed as part of a global or v command or @ buf‐
2833 fer execution.
2834 3. The command was the form of the read command that reads a file into
2836 the edit buffer.
2837 4. The command was the append, change, or insert command.
2839 5. The command was not terminated by a <newline>.
2841 6. The current line shall be written by a flag specified to the com‐
2843 mand; for example, delete # shall write the current line as speci‐
2844 fied for the flag modifier to the delete command, and not as speci‐
2845 fied by the autoprint edit option.
2846 autowrite, aw
2848 [Default unset]
2849 If autowrite is set, and the edit buffer has been modified since it was
2851 last completely written to any file, the contents of the edit buffer
2852 shall be written as if the ex write command had been specified without
2853 arguments, before each command affected by the autowrite edit option is
2854 executed. Appending the character '!' to the command name of any of the
2855 ex commands except '!' shall prevent the write. If the write fails, it
2856 shall be an error and the command shall not be executed.
2857 beautify, bf
2859 [Default unset]
2860 If beautify is set, all non-printable characters, other than <tab>s,
2862 <newline>s, and <form-feed>s, shall be discarded from text read in from
2863 files.
2864 directory, dir
2866 [Default implementation-defined]
2867 The value of this option specifies the directory in which the editor
2869 buffer is to be placed. If this directory is not writable by the user,
2870 the editor shall quit.
2871 edcompatible, ed
2873 [Default unset]
2874 Causes the presence of g and c suffixes on substitute commands to be
2876 remembered, and toggled by repeating the suffixes.
2877 errorbells, eb
2879 [Default unset]
2880 If the editor is in ex mode, and the terminal does not support a stand‐
2882 out mode (such as inverse video), and errorbells is set, error messages
2883 shall be preceded by alerting the terminal.
2884 exrc
2886 [Default unset]
2887 If exrc is set, ex shall access any .exrc file in the current direc‐
2889 tory, as described in Initialization in ex and vi . If exrc is not set,
2890 ex shall ignore any .exrc file in the current directory during initial‐
2891 ization, unless the current directory is that named by the HOME envi‐
2892 ronment variable.
2893 ignorecase, ic
2895 [Default unset]
2896 If ignorecase is set, characters that have uppercase and lowercase rep‐
2898 resentations shall have those representations considered as equivalent
2899 for purposes of regular expression comparison.
2900 The ignorecase edit option shall affect all remembered regular expres‐
2902 sions; for example, unsetting the ignorecase edit option shall cause a
2903 subsequent vi n command to search for the last basic regular expression
2904 in a case-sensitive fashion.
2905 list
2907 [Default unset]
2908 If list is set, edit buffer lines written while in ex command mode
2910 shall be written as specified for the print command with the l flag
2911 specified. In open or visual mode, each edit buffer line shall be dis‐
2912 played as specified for the ex print command with the l flag specified.
2913 In open or visual text input mode, when the cursor does not rest on any
2914 character in the line, it shall rest on the '$' marking the end of the
2915 line.
2916 magic
2918 [Default set]
2919 If magic is set, modify the interpretation of characters in regular
2921 expressions and substitution replacement strings (see Regular Expres‐
2922 sions in ex and Replacement Strings in ex ).
2923 mesg
2925 [Default set]
2926 If mesg is set, the permission for others to use the write or talk com‐
2928 mands to write to the terminal shall be turned on while in open or vis‐
2929 ual mode. The shell-level command mesg n shall take precedence over any
2930 setting of the ex mesg option; that is, if mesg y was issued before the
2931 editor started (or in a shell escape), such as:
2932 :!mesg y
2935 the mesg option in ex shall suppress incoming messages, but the mesg
2937 option shall not enable incoming messages if mesg n was issued.
2938 number, nu
2940 [Default unset]
2941 If number is set, edit buffer lines written while in ex command mode
2943 shall be written with line numbers, in the format specified by the
2944 print command with the # flag specified. In ex text input mode, each
2945 line shall be preceded by the line number it will have in the file.
2946 In open or visual mode, each edit buffer line shall be displayed with a
2948 preceding line number, in the format specified by the ex print command
2949 with the # flag specified. This line number shall not be considered
2950 part of the line for the purposes of evaluating the current column;
2951 that is, column position 1 shall be the first column position after the
2952 format specified by the print command.
2953 paragraphs, para
2955 [Default in the POSIX locale IPLPPPQPP LIpplpipbp]
2956 The paragraphs edit option shall define additional paragraph boundaries
2958 for the open and visual mode commands. The paragraphs edit option can
2959 be set to a character string consisting of zero or more character
2960 pairs. It shall be an error to set it to an odd number of characters.
2961 prompt
2963 [Default set]
2964 If prompt is set, ex command mode input shall be prompted for with a
2966 colon ( ':' ); when unset, no prompt shall be written.
2967 readonly
2969 [Default see text]
2970 If the readonly edit option is set, read-only mode shall be enabled
2972 (see Write ). The readonly edit option shall be initialized to set if
2973 either of the following conditions are true:
2974 * The command-line option -R was specified.
2976 * Performing actions equivalent to the access() function called with
2978 the following arguments indicates that the file lacks write permis‐
2979 sion:
2980 1. The current pathname is used as the path argument.
2982 2. The constant W_OK is used as the amode argument.
2984 The readonly edit option may be initialized to set for other, implemen‐
2986 tation-defined reasons. The readonly edit option shall not be initial‐
2987 ized to unset based on any special privileges of the user or process.
2988 The readonly edit option shall be reinitialized each time that the con‐
2989 tents of the edit buffer are replaced (for example, by an edit or next
2990 command) unless the user has explicitly set it, in which case it shall
2991 remain set until the user explicitly unsets it. Once unset, it shall
2992 again be reinitialized each time that the contents of the edit buffer
2993 are replaced.
2994 redraw
2996 [Default unset]
2997 The editor simulates an intelligent terminal on a dumb terminal. (Since
2999 this is likely to require a large amount of output to the terminal, it
3000 is useful only at high transmission speeds.)
3001 remap
3003 [Default set]
3004 If remap is set, map translation shall allow for maps defined in terms
3006 of other maps; translation shall continue until a final product is
3007 obtained. If unset, only a one-step translation shall be done.
3008 report
3010 [Default 5]
3011 The value of this report edit option specifies what number of lines
3013 being added, copied, deleted, or modified in the edit buffer will cause
3014 an informational message to be written to the user. The following con‐
3015 ditions shall cause an informational message. The message shall contain
3016 the number of lines added, copied, deleted, or modified, but is other‐
3017 wise unspecified.
3018 * An ex or vi editor command, other than open, undo, or visual, that
3020 modifies at least the value of the report edit option number of
3021 lines, and which is not part of an ex global or v command, or ex or
3022 vi buffer execution, shall cause an informational message to be
3023 written.
3024 * An ex yank or vi y or Y command, that copies at least the value of
3026 the report edit option plus 1 number of lines, and which is not part
3027 of an ex global or v command, or ex or vi buffer execution, shall
3028 cause an informational message to be written.
3029 * An ex global, v, open, undo, or visual command or ex or vi buffer
3031 execution, that adds or deletes a total of at least the value of the
3032 report edit option number of lines, and which is not part of an ex
3033 global or v command, or ex or vi buffer execution, shall cause an
3034 informational message to be written. (For example, if 3 lines were
3035 added and 8 lines deleted during an ex visual command, 5 would be
3036 the number compared against the report edit option after the command
3037 completed.)
3038 scroll, scr
3040 [Default (number of lines in the display -1)/2]
3041 The value of the scroll edit option shall determine the number of lines
3043 scrolled by the ex <control>-D and z commands. For the vi <control>-D
3044 and <control>-U commands, it shall be the initial number of lines to
3045 scroll when no previous <control>-D or <control>-U command has been
3046 executed.
3047 sections
3049 [Default in the POSIX locale NHSHH HUnhsh]
3050 The sections edit option shall define additional section boundaries for
3052 the open and visual mode commands. The sections edit option can be set
3053 to a character string consisting of zero or more character pairs; it
3054 shall be an error to set it to an odd number of characters.
3055 shell, sh
3057 [Default from the environment variable SHELL ]
3058 The value of this option shall be a string. The default shall be taken
3060 from the SHELL environment variable. If the SHELL environment variable
3061 is null or empty, the sh (see sh ) utility shall be the default.
3062 shiftwidth, sw
3064 [Default 8]
3065 The value of this option shall give the width in columns of an indenta‐
3067 tion level used during autoindentation and by the shift commands ( <
3068 and >).
3069 showmatch, sm
3071 [Default unset]
3072 The functionality described for the showmatch edit option need not be
3074 supported on block-mode terminals or terminals with insufficient capa‐
3075 bilities.
3076 If showmatch is set, in open or visual mode, when a ')' or '}' is
3078 typed, if the matching '(' or '{' is currently visible on the display,
3079 the matching '(' or '{' shall be flagged moving the cursor to its loca‐
3080 tion for an unspecified amount of time.
3081 showmode
3083 [Default unset]
3084 If showmode is set, in open or visual mode, the current mode that the
3086 editor is in shall be displayed on the last line of the display. Com‐
3087 mand mode and text input mode shall be differentiated; other unspeci‐
3088 fied modes and implementation-defined information may be displayed.
3089 slowopen
3091 [Default unset]
3092 If slowopen is set during open and visual text input modes, the editor
3094 shall not update portions of the display other than those display line
3095 columns that display the characters entered by the user (see Input Mode
3096 Commands in vi ).
3097 tabstop, ts
3099 [Default 8]
3100 The value of this edit option shall specify the column boundary used by
3102 a <tab> in the display (see autoprint, ap and Input Mode Commands in vi
3103 ).
3104 taglength, tl
3106 [Default zero]
3107 The value of this edit option shall specify the maximum number of char‐
3109 acters that are considered significant in the user-specified tag name
3110 and in the tag name from the tags file. If the value is zero, all char‐
3111 acters in both tag names shall be significant.
3112 tags
3114 [Default see text]
3115 The value of this edit option shall be a string of <blank>-delimited
3117 pathnames of files used by the tag command. The default value is
3118 unspecified.
3119 term
3121 [Default from the environment variable TERM ]
3122 The value of this edit option shall be a string. The default shall be
3124 taken from the TERM variable in the environment. If the TERM environ‐
3125 ment variable is empty or null, the default is unspecified. The editor
3126 shall use the value of this edit option to determine the type of the
3127 display device.
3128 The results are unspecified if the user changes the value of the term
3130 edit option after editor initialization.
3131 terse
3133 [Default unset]
3134 If terse is set, error messages may be less verbose. However, except
3136 for this caveat, error messages are unspecified. Furthermore, not all
3137 error messages need change for different settings of this option.
3138 warn
3140 [Default set]
3141 If warn is set, and the contents of the edit buffer have been modified
3143 since they were last completely written, the editor shall write a warn‐
3144 ing message before certain ! commands (see Escape ).
3145 window
3147 [Default see text]
3148 A value used in open and visual mode, by the <control>-B and <con‐
3150 trol>-F commands, and, in visual mode, to specify the number of lines
3151 displayed when the screen is repainted.
3152 If the -w command-line option is not specified, the default value shall
3154 be set to the value of the LINES environment variable. If the LINES
3155 environment variable is empty or null, the default shall be the number
3156 of lines in the display minus 1.
3157 Setting the window edit option to zero or to a value greater than the
3159 number of lines in the display minus 1 (either explicitly or based on
3160 the -w option or the LINES environment variable) shall cause the window
3161 edit option to be set to the number of lines in the display minus 1.
3162 The baud rate of the terminal line may change the default in an imple‐
3164 mentation-defined manner.
3165 wrapmargin, wm
3167 [Default 0]
3168 If the value of this edit option is zero, it shall have no effect.
3170 If not in the POSIX locale, the effect of this edit option is implemen‐
3172 tation-defined.
3173 Otherwise, it shall specify a number of columns from the ending margin
3175 of the terminal.
3176 During open and visual text input modes, for each character for which
3178 any part of the character is displayed in a column that is less than
3179 wrapmargin columns from the ending margin of the display line, the edi‐
3180 tor shall behave as follows:
3181 1. If the character triggering this event is a <blank>, it, and all
3183 immediately preceding <blank>s on the current line entered during
3184 the execution of the current text input command, shall be dis‐
3185 carded, and the editor shall behave as if the user had entered a
3186 single <newline> instead. In addition, if the next user-entered
3187 character is a <space>, it shall be discarded as well.
3188 2. Otherwise, if there are one or more <blank>s on the current line
3190 immediately preceding the last group of inserted non- <blank>s
3191 which was entered during the execution of the current text input
3192 command, the <blank>s shall be replaced as if the user had entered
3193 a single <newline> instead.
3194 If the autoindent edit option is set, and the events described in 1. or
3196 2. are performed, any <blank>s at or after the cursor in the current
3197 line shall be discarded.
3198 The ending margin shall be determined by the system or overridden by
3200 the user, as described for COLUMNS in the ENVIRONMENT VARIABLES section
3201 and the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 8,
3202 Environment Variables.
3203 wrapscan, ws
3205 [Default set]
3206 If wrapscan is set, searches (the ex / or ? addresses, or open and
3208 visual mode /, ?, N, and n commands) shall wrap around the beginning or
3209 end of the edit buffer; when unset, searches shall stop at the begin‐
3210 ning or end of the edit buffer.
3211 writeany, wa
3213 [Default unset]
3214 If writeany is set, some of the checks performed when executing the ex
3216 write commands shall be inhibited, as described in editor option
3217 autowrite.
3218
3220 The following exit values shall be returned:
3221 0 Successful completion.
3223 >0 An error occurred.
3225
3228 When any error is encountered and the standard input is not a terminal
3229 device file, ex shall not write the file or return to command or text
3230 input mode, and shall terminate with a non-zero exit status.
3231 Otherwise, when an unrecoverable error is encountered, it shall be
3233 equivalent to a SIGHUP asynchronous event.
3234 Otherwise, when an error is encountered, the editor shall behave as
3236 specified in Command Line Parsing in ex .
3237 The following sections are informative.
3239
3241 If a SIGSEGV signal is received while ex is saving a file, the file
3242 might not be successfully saved.
3243 The next command can accept more than one file, so usage such as:
3245 next `ls [abc]*`
3248 is valid; it would not be valid for the edit or read commands, for
3250 example, because they expect only one file and unspecified results
3251 occur.
3252
3254 None.
3255
3257 The ex/ vi specification is based on the historical practice found in
3258 the 4 BSD and System V implementations of ex and vi. A freely redis‐
3259 tributable implementation of ex/ vi, which is tracking
3260 IEEE Std 1003.1-2001 fairly closely, and demonstrates the intended
3261 changes between historical implementations and IEEE Std 1003.1-2001,
3262 may be obtained by anonymous FTP from:
3263 ftp://ftp.rdg.opengroup.org/pub/mirrors/nvi
3266 A restricted editor (both the historical red utility and modifications
3268 to ex) were considered and rejected for inclusion. Neither option pro‐
3269 vided the level of security that users might expect.
3270 It is recognized that ex visual mode and related features would be dif‐
3272 ficult, if not impossible, to implement satisfactorily on a block-mode
3273 terminal, or a terminal without any form of cursor addressing; thus, it
3274 is not a mandatory requirement that such features should work on all
3275 terminals. It is the intention, however, that an ex implementation
3276 should provide the full set of capabilities on all terminals capable of
3277 supporting them.
3278 Options
3280 The -c replacement for + command was inspired by the -e option of sed.
3281 Historically, all such commands (see edit and next as well) were exe‐
3282 cuted from the last line of the edit buffer. This meant, for example,
3283 that "+/pattern" would fail unless the wrapscan option was set.
3284 IEEE Std 1003.1-2001 requires conformance to historical practice. His‐
3285 torically, some implementations restricted the ex commands that could
3286 be listed as part of the command line arguments. For consistency,
3287 IEEE Std 1003.1-2001 does not permit these restrictions.
3288 In historical implementations of the editor, the -R option (and the
3290 readonly edit option) only prevented overwriting of files; appending to
3291 files was still permitted, mapping loosely into the csh noclobber vari‐
3292 able. Some implementations, however, have not followed this semantic,
3293 and readonly does not permit appending either. IEEE Std 1003.1-2001
3294 follows the latter practice, believing that it is a more obvious and
3295 intuitive meaning of readonly.
3296 The -s option suppresses all interactive user feedback and is useful
3298 for editing scripts in batch jobs. The list of specific effects is his‐
3299 torical practice. The terminal type "incapable of supporting open and
3300 visual modes" has historically been named "dumb".
3301 The -t option was required because the ctags utility appears in
3303 IEEE Std 1003.1-2001 and the option is available in all historical
3304 implementations of ex.
3305 Historically, the ex and vi utilities accepted a -x option, which did
3307 encryption based on the algorithm found in the historical crypt util‐
3308 ity. The -x option for encryption, and the associated crypt utility,
3309 were omitted because the algorithm used was not specifiable and the
3310 export control laws of some nations make it difficult to export crypto‐
3311 graphic technology. In addition, it did not historically provide the
3312 level of security that users might expect.
3313 Standard Input
3315 An end-of-file condition is not equivalent to an end-of-file character.
3316 A common end-of-file character, <control>-D, is historically an ex com‐
3317 mand.
3318 There was no maximum line length in historical implementations of ex.
3320 Specifically, as it was parsed in chunks, the addresses had a different
3321 maximum length than the filenames. Further, the maximum line buffer
3322 size was declared as BUFSIZ, which was different lengths on different
3323 systems. This version selected the value of {LINE_MAX} to impose a rea‐
3324 sonable restriction on portable usage of ex and to aid test suite writ‐
3325 ers in their development of realistic tests that exercise this limit.
3326 Input Files
3328 It was an explicit decision by the standard developers that a <newline>
3329 be added to any file lacking one. It was believed that this feature of
3330 ex and vi was relied on by users in order to make text files lacking a
3331 trailing <newline> more portable. It is recognized that this will
3332 require a user-specified option or extension for implementations that
3333 permit ex and vi to edit files of type other than text if such files
3334 are not otherwise identified by the system. It was agreed that the
3335 ability to edit files of arbitrary type can be useful, but it was not
3336 considered necessary to mandate that an ex or vi implementation be
3337 required to handle files other than text files.
3338 The paragraph in the INPUT FILES section, "By default, ...", is
3340 intended to close a long-standing security problem in ex and vi; that
3341 of the "modeline" or "modelines" edit option. This feature allows any
3342 line in the first or last five lines of the file containing the strings
3343 "ex:" or "vi:" (and, apparently, "ei:" or "vx:" ) to be a line contain‐
3344 ing editor commands, and ex interprets all the text up to the next ':'
3345 or <newline> as a command. Consider the consequences, for example, of
3346 an unsuspecting user using ex or vi as the editor when replying to a
3347 mail message in which a line such as:
3348 ex:! rm -rf :
3351 appeared in the signature lines. The standard developers believed
3353 strongly that an editor should not by default interpret any lines of a
3354 file. Vendors are strongly urged to delete this feature from their
3355 implementations of ex and vi.
3356 Asynchronous Events
3358 The intention of the phrase "complete write" is that the entire edit
3359 buffer be written to stable storage. The note regarding temporary files
3360 is intended for implementations that use temporary files to back edit
3361 buffers unnamed by the user.
3362 Historically, SIGQUIT was ignored by ex, but was the equivalent of the
3364 Q command in visual mode; that is, it exited visual mode and entered ex
3365 mode. IEEE Std 1003.1-2001 permits, but does not require, this behav‐
3366 ior. Historically, SIGINT was often used by vi users to terminate text
3367 input mode ( <control>-C is often easier to enter than <ESC>). Some
3368 implementations of vi alerted the terminal on this event, and some did
3369 not. IEEE Std 1003.1-2001 requires that SIGINT behave identically to
3370 <ESC>, and that the terminal not be alerted.
3371 Historically, suspending the ex editor during text input mode was simi‐
3373 lar to SIGINT, as completed lines were retained, but any partial line
3374 discarded, and the editor returned to command mode.
3375 IEEE Std 1003.1-2001 is silent on this issue; implementations are
3376 encouraged to follow historical practice, where possible.
3377 Historically, the vi editor did not treat SIGTSTP as an asynchronous
3379 event, and it was therefore impossible to suspend the editor in visual
3380 text input mode. There are two major reasons for this. The first is
3381 that SIGTSTP is a broadcast signal on UNIX systems, and the chain of
3382 events where the shell execs an application that then execs vi usually
3383 caused confusion for the terminal state if SIGTSTP was delivered to the
3384 process group in the default manner. The second was that most implemen‐
3385 tations of the UNIX curses package are not reentrant, and the receipt
3386 of SIGTSTP at the wrong time will cause them to crash.
3387 IEEE Std 1003.1-2001 is silent on this issue; implementations are
3388 encouraged to treat suspension as an asynchronous event if possible.
3389 Historically, modifications to the edit buffer made before SIGINT
3391 interrupted an operation were retained; that is, anywhere from zero to
3392 all of the lines to be modified might have been modified by the time
3393 the SIGINT arrived. These changes were not discarded by the arrival of
3394 SIGINT. IEEE Std 1003.1-2001 permits this behavior, noting that the
3395 undo command is required to be able to undo these partially completed
3396 commands.
3397 The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and
3399 SIGTERM is unspecified because some implementations attempt to save the
3400 edit buffer in a useful state when other signals are received.
3401 Standard Error
3403 For ex/ vi, diagnostic messages are those messages reported as a result
3404 of a failed attempt to invoke ex or vi, such as invalid options or
3405 insufficient resources, or an abnormal termination condition. Diagnos‐
3406 tic messages should not be confused with the error messages generated
3407 by inappropriate or illegal user commands.
3408 Initialization in ex and vi
3410 If an ex command (other than cd, chdir, or source) has a filename argu‐
3411 ment, one or both of the alternate and current pathnames will be set.
3412 Informally, they are set as follows:
3413 1. If the ex command is one that replaces the contents of the edit
3415 buffer, and it succeeds, the current pathname will be set to the
3416 filename argument (the first filename argument in the case of the
3417 next command) and the alternate pathname will be set to the previ‐
3418 ous current pathname, if there was one.
3419 2. In the case of the file read/write forms of the read and write com‐
3421 mands, if there is no current pathname, the current pathname will
3422 be set to the filename argument.
3423 3. Otherwise, the alternate pathname will be set to the filename argu‐
3425 ment.
3426 For example, :edit foo and :recover foo, when successful, set the cur‐
3428 rent pathname, and, if there was a previous current pathname, the
3429 alternate pathname. The commands :write, !command, and :edit set nei‐
3430 ther the current or alternate pathnames. If the :edit foo command were
3431 to fail for some reason, the alternate pathname would be set. The read
3432 and write commands set the alternate pathname to their file argument,
3433 unless the current pathname is not set, in which case they set the cur‐
3434 rent pathname to their file arguments. The alternate pathname was not
3435 historically set by the :source command. IEEE Std 1003.1-2001 requires
3436 conformance to historical practice. Implementations adding commands
3437 that take filenames as arguments are encouraged to set the alternate
3438 pathname as described here.
3439 Historically, ex and vi read the .exrc file in the $HOME directory
3441 twice, if the editor was executed in the $HOME directory.
3442 IEEE Std 1003.1-2001 prohibits this behavior.
3443 Historically, the 4 BSD ex and vi read the $HOME and local .exrc files
3445 if they were owned by the real ID of the user, or the sourceany option
3446 was set, regardless of other considerations. This was a security prob‐
3447 lem because it is possible to put normal UNIX system commands inside a
3448 .exrc file. IEEE Std 1003.1-2001 does not specify the sourceany
3449 option, and historical implementations are encouraged to delete it.
3450 The .exrc files must be owned by the real ID of the user, and not
3452 writable by anyone other than the owner. The appropriate privileges
3453 exception is intended to permit users to acquire special privileges,
3454 but continue to use the .exrc files in their home directories.
3455 System V Release 3.2 and later vi implementations added the option
3457 [no]exrc. The behavior is that local .exrc files are read-only if the
3458 exrc option is set. The default for the exrc option was off, so by
3459 default, local .exrc files were not read. The problem this was
3460 intended to solve was that System V permitted users to give away files,
3461 so there is no possible ownership or writeability test to ensure that
3462 the file is safe. This is still a security problem on systems where
3463 users can give away files, but there is nothing additional that
3464 IEEE Std 1003.1-2001 can do. The implementation-defined exception is
3465 intended to permit groups to have local .exrc files that are shared by
3466 users, by creating pseudo-users to own the shared files.
3467 IEEE Std 1003.1-2001 does not mention system-wide ex and vi start-up
3469 files. While they exist in several implementations of ex and vi, they
3470 are not present in any implementations considered historical practice
3471 by IEEE Std 1003.1-2001. Implementations that have such files should
3472 use them only if they are owned by the real user ID or an appropriate
3473 user (for example, root on UNIX systems) and if they are not writable
3474 by any user other than their owner. System-wide start-up files should
3475 be read before the EXINIT variable, $HOME/.exrc, or local .exrc files
3476 are evaluated.
3477 Historically, any ex command could be entered in the EXINIT variable or
3479 the .exrc file, although ones requiring that the edit buffer already
3480 contain lines of text generally caused historical implementations of
3481 the editor to drop core. IEEE Std 1003.1-2001 requires that any ex com‐
3482 mand be permitted in the EXINIT variable and .exrc files, for simplic‐
3483 ity of specification and consistency, although many of them will obvi‐
3484 ously fail under many circumstances.
3485 The initialization of the contents of the edit buffer uses the phrase
3487 "the effect shall be" with regard to various ex commands. The intent of
3488 this phrase is that edit buffer contents loaded during the initializa‐
3489 tion phase not be lost; that is, loading the edit buffer should fail if
3490 the .exrc file read in the contents of a file and did not subsequently
3491 write the edit buffer. An additional intent of this phrase is to spec‐
3492 ify that the initial current line and column is set as specified for
3493 the individual ex commands.
3494 Historically, the -t option behaved as if the tag search were a + com‐
3496 mand; that is, it was executed from the last line of the file specified
3497 by the tag. This resulted in the search failing if the pattern was a
3498 forward search pattern and the wrapscan edit option was not set.
3499 IEEE Std 1003.1-2001 does not permit this behavior, requiring that the
3500 search for the tag pattern be performed on the entire file, and, if not
3501 found, that the current line be set to a more reasonable location in
3502 the file.
3503 Historically, the empty edit buffer presented for editing when a file
3505 was not specified by the user was unnamed. This is permitted by
3506 IEEE Std 1003.1-2001; however, implementations are encouraged to pro‐
3507 vide users a temporary filename for this buffer because it permits them
3508 the use of ex commands that use the current pathname during temporary
3509 edit sessions.
3510 Historically, the file specified using the -t option was not part of
3512 the current argument list. This practice is permitted by
3513 IEEE Std 1003.1-2001; however, implementations are encouraged to
3514 include its name in the current argument list for consistency.
3515 Historically, the -c command was generally not executed until a file
3517 that already exists was edited. IEEE Std 1003.1-2001 requires confor‐
3518 mance to this historical practice. Commands that could cause the -c
3519 command to be executed include the ex commands edit, next, recover,
3520 rewind, and tag, and the vi commands <control>-^ and <control>-]. His‐
3521 torically, reading a file into an edit buffer did not cause the -c com‐
3522 mand to be executed (even though it might set the current pathname)
3523 with the exception that it did cause the -c command to be executed if:
3524 the editor was in ex mode, the edit buffer had no current pathname, the
3525 edit buffer was empty, and no read commands had yet been attempted. For
3526 consistency and simplicity of specification, IEEE Std 1003.1-2001 does
3527 not permit this behavior.
3528 Historically, the -r option was the same as a normal edit session if
3530 there was no recovery information available for the file. This allowed
3531 users to enter:
3532 vi -r *.c
3535 and recover whatever files were recoverable. In some implementations,
3537 recovery was attempted only on the first file named, and the file was
3538 not entered into the argument list; in others, recovery was attempted
3539 for each file named. In addition, some historical implementations
3540 ignored -r if -t was specified or did not support command line file
3541 arguments with the -t option. For consistency and simplicity of speci‐
3542 fication, IEEE Std 1003.1-2001 disallows these special cases, and
3543 requires that recovery be attempted the first time each file is edited.
3544 Historically, vi initialized the ` and ' marks, but ex did not. This
3546 meant that if the first command in ex mode was visual or if an ex com‐
3547 mand was executed first (for example, vi +10 file), vi was entered
3548 without the marks being initialized. Because the standard developers
3549 believed the marks to be generally useful, and for consistency and sim‐
3550 plicity of specification, IEEE Std 1003.1-2001 requires that they
3551 always be initialized if in open or visual mode, or if in ex mode and
3552 the edit buffer is not empty. Not initializing it in ex mode if the
3553 edit buffer is empty is historical practice; however, it has always
3554 been possible to set (and use) marks in empty edit buffers in open and
3555 visual mode edit sessions.
3556 Addressing
3558 Historically, ex and vi accepted the additional addressing forms '\/'
3559 and '\?' . They were equivalent to "//" and "??", respectively. They
3560 are not required by IEEE Std 1003.1-2001, mostly because nobody can
3561 remember whether they ever did anything different historically.
3562 Historically, ex and vi permitted an address of zero for several com‐
3564 mands, and permitted the % address in empty files for others. For con‐
3565 sistency, IEEE Std 1003.1-2001 requires support for the former in the
3566 few commands where it makes sense, and disallows it otherwise. In addi‐
3567 tion, because IEEE Std 1003.1-2001 requires that % be logically equiva‐
3568 lent to "1,$", it is also supported where it makes sense and disallowed
3569 otherwise.
3570 Historically, the % address could not be followed by further addresses.
3572 For consistency and simplicity of specification, IEEE Std 1003.1-2001
3573 requires that additional addresses be supported.
3574 All of the following are valid addresses:
3576 +++ Three lines after the current line.
3578 /re/- One line before the next occurrence of re.
3580 -2 Two lines before the current line.
3582 3 ---- 2
3584 Line one (note intermediate negative address).
3585 1 2 3 Line six.
3587 Any number of addresses can be provided to commands taking addresses;
3590 for example, "1,2,3,4,5p" prints lines 4 and 5, because two is the
3591 greatest valid number of addresses accepted by the print command. This,
3592 in combination with the semicolon delimiter, permits users to create
3593 commands based on ordered patterns in the file. For example, the com‐
3594 mand 3;/foo/;+2print will display the first line after line 3 that con‐
3595 tains the pattern foo, plus the next two lines. Note that the address
3596 3; must be evaluated before being discarded because the search origin
3597 for the /foo/ command depends on this.
3598 Historically, values could be added to addresses by including them
3600 after one or more <blank>s; for example, 3 - 5p wrote the seventh line
3601 of the file, and /foo/ 5 was the same as /foo/+5. However, only abso‐
3602 lute values could be added; for example, 5 /foo/ was an error.
3603 IEEE Std 1003.1-2001 requires conformance to historical practice.
3604 Address offsets are separately specified from addresses because they
3605 could historically be provided to visual mode search commands.
3606 Historically, any missing addresses defaulted to the current line.
3608 This was true for leading and trailing comma-delimited addresses, and
3609 for trailing semicolon-delimited addresses. For consistency,
3610 IEEE Std 1003.1-2001 requires it for leading semicolon addresses as
3611 well.
3612 Historically, ex and vi accepted the '^' character as both an address
3614 and as a flag offset for commands. In both cases it was identical to
3615 the '-' character. IEEE Std 1003.1-2001 does not require or prohibit
3616 this behavior.
3617 Historically, the enhancements to basic regular expressions could be
3619 used in addressing; for example, '~', '\<', and '\>' .
3620 IEEE Std 1003.1-2001 requires conformance to historical practice; that
3621 is, that regular expression usage be consistent, and that regular
3622 expression enhancements be supported wherever regular expressions are
3623 used.
3624 Command Line Parsing in ex
3626 Historical ex command parsing was even more complex than that described
3627 here. IEEE Std 1003.1-2001 requires the subset of the command parsing
3628 that the standard developers believed was documented and that users
3629 could reasonably be expected to use in a portable fashion, and that was
3630 historically consistent between implementations. (The discarded func‐
3631 tionality is obscure, at best.) Historical implementations will require
3632 changes in order to comply with IEEE Std 1003.1-2001; however, users
3633 are not expected to notice any of these changes. Most of the complexity
3634 in ex parsing is to handle three special termination cases:
3635 1. The !, global, v, and the filter versions of the read and write
3637 commands are delimited by <newline>s (they can contain vertical-
3638 line characters that are usually shell pipes).
3639 2. The ex, edit, next, and visual in open and visual mode commands all
3641 take ex commands, optionally containing vertical-line characters,
3642 as their first arguments.
3643 3. The s command takes a regular expression as its first argument, and
3645 uses the delimiting characters to delimit the command.
3646 Historically, vertical-line characters in the + command argument of the
3648 ex, edit, next, vi, and visual commands, and in the pattern and
3649 replacement parts of the s command, did not delimit the command, and in
3650 the filter cases for read and write, and the !, global, and v commands,
3651 they did not delimit the command at all. For example, the following
3652 commands are all valid:
3653 :edit +25 | s/abc/ABC/ file.c
3656 :s/ | /PIPE/
3657 :read !spell % | columnate
3658 :global/pattern/p | l
3659 :s/a/b/ | s/c/d | set
3660 Historically, empty or <blank> filled lines in .exrc files and sourced
3662 files (as well as EXINIT variables and ex command scripts) were treated
3663 as default commands; that is, print commands. IEEE Std 1003.1-2001
3664 specifically requires that they be ignored when encountered in .exrc
3665 and sourced files to eliminate a common source of new user error.
3666 Historically, ex commands with multiple adjacent (or <blank>-separated)
3668 vertical lines were handled oddly when executed from ex mode. For exam‐
3669 ple, the command ||| <carriage-return>, when the cursor was on line 1,
3670 displayed lines 2, 3, and 5 of the file. In addition, the command |
3671 would only display the line after the next line, instead of the next
3672 two lines. The former worked more logically when executed from vi mode,
3673 and displayed lines 2, 3, and 4. IEEE Std 1003.1-2001 requires the vi
3674 behavior; that is, a single default command and line number increment
3675 for each command separator, and trailing <newline>s after vertical-line
3676 separators are discarded.
3677 Historically, ex permitted a single extra colon as a leading command
3679 character; for example, :g/pattern/:p was a valid command.
3680 IEEE Std 1003.1-2001 generalizes this to require that any number of
3681 leading colon characters be stripped.
3682 Historically, any prefix of the delete command could be followed with‐
3684 out intervening <blank>s by a flag character because in the command
3685 d p, p is interpreted as the buffer p. IEEE Std 1003.1-2001 requires
3686 conformance to historical practice.
3687 Historically, the k command could be followed by the mark name without
3689 intervening <blank>s. IEEE Std 1003.1-2001 requires conformance to
3690 historical practice.
3691 Historically, the s command could be immediately followed by flag and
3693 option characters; for example, s/e/E/|s|sgc3p was a valid command.
3694 However, flag characters could not stand alone; for example, the com‐
3695 mands sp and s l would fail, while the command sgp and s gl would suc‐
3696 ceed. (Obviously, the '#' flag character was used as a delimiter char‐
3697 acter if it followed the command.) Another issue was that option char‐
3698 acters had to precede flag characters even when the command was fully
3699 specified; for example, the command s/e/E/pg would fail, while the com‐
3700 mand s/e/E/gp would succeed. IEEE Std 1003.1-2001 requires conformance
3701 to historical practice.
3702 Historically, the first command name that had a prefix matching the
3704 input from the user was the executed command; for example, ve, ver, and
3705 vers all executed the version command. Commands were in a specific
3706 order, however, so that a matched append, not abbreviate.
3707 IEEE Std 1003.1-2001 requires conformance to historical practice. The
3708 restriction on command search order for implementations with extensions
3709 is to avoid the addition of commands such that the historical prefixes
3710 would fail to work portably.
3711 Historical implementations of ex and vi did not correctly handle multi‐
3713 ple ex commands, separated by vertical-line characters, that entered or
3714 exited visual mode or the editor. Because implementations of vi exist
3715 that do not exhibit this failure mode, IEEE Std 1003.1-2001 does not
3716 permit it.
3717 The requirement that alphabetic command names consist of all following
3719 alphabetic characters up to the next non-alphabetic character means
3720 that alphabetic command names must be separated from their arguments by
3721 one or more non-alphabetic characters, normally a <blank> or '!' char‐
3722 acter, except as specified for the exceptions, the delete, k, and s
3723 commands.
3724 Historically, the repeated execution of the ex default print commands (
3726 <control>-D, eof, <newline>, <carriage-return>) erased any prompting
3727 character and displayed the next lines without scrolling the terminal;
3728 that is, immediately below any previously displayed lines. This pro‐
3729 vided a cleaner presentation of the lines in the file for the user.
3730 IEEE Std 1003.1-2001 does not require this behavior because it may be
3731 impossible in some situations; however, implementations are strongly
3732 encouraged to provide this semantic if possible.
3733 Historically, it was possible to change files in the middle of a com‐
3735 mand, and have the rest of the command executed in the new file; for
3736 example:
3737 :edit +25 file.c | s/abc/ABC/ | 1
3740 was a valid command, and the substitution was attempted in the newly
3742 edited file. IEEE Std 1003.1-2001 requires conformance to historical
3743 practice. The following commands are examples that exercise the ex
3744 parser:
3745 echo 'foo | bar' > file1; echo 'foo/bar' > file2;
3748 vi
3749 :edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\//SLASH/ | wq
3750 Historically, there was no protection in editor implementations to
3752 avoid ex global, v, @, or * commands changing edit buffers during exe‐
3753 cution of their associated commands. Because this would almost invari‐
3754 ably result in catastrophic failure of the editor, and implementations
3755 exist that do exhibit these problems, IEEE Std 1003.1-2001 requires
3756 that changing the edit buffer during a global or v command, or during a
3757 @ or * command for which there will be more than a single execution, be
3758 an error. Implementations supporting multiple edit buffers simultane‐
3759 ously are strongly encouraged to apply the same semantics to switching
3760 between buffers as well.
3761 The ex command quoting required by IEEE Std 1003.1-2001 is a superset
3763 of the quoting in historical implementations of the editor. For exam‐
3764 ple, it was not historically possible to escape a <blank> in a file‐
3765 name; for example, :edit foo\\\ bar would report that too many file‐
3766 names had been entered for the edit command, and there was no method of
3767 escaping a <blank> in the first argument of an edit, ex, next, or vis‐
3768 ual command at all. IEEE Std 1003.1-2001 extends historical practice,
3769 requiring that quoting behavior be made consistent across all ex com‐
3770 mands, except for the map, unmap, abbreviate, and unabbreviate com‐
3771 mands, which historically used <control>-V instead of backslashes for
3772 quoting. For those four commands, IEEE Std 1003.1-2001 requires con‐
3773 formance to historical practice.
3774 Backslash quoting in ex is non-intuitive. Backslash escapes are ignored
3776 unless they escape a special character; for example, when performing
3777 file argument expansion, the string "\\%" is equivalent to '\%', not
3778 "\<current pathname>". This can be confusing for users because back‐
3779 slash is usually one of the characters that causes shell expansion to
3780 be performed, and therefore shell quoting rules must be taken into con‐
3781 sideration. Generally, quoting characters are only considered if they
3782 escape a special character, and a quoting character must be provided
3783 for each layer of parsing for which the character is special. As
3784 another example, only a single backslash is necessary for the '\l'
3785 sequence in substitute replacement patterns, because the character 'l'
3786 is not special to any parsing layer above it.
3787 <control>-V quoting in ex is slightly different from backslash quoting.
3789 In the four commands where <control>-V quoting applies ( abbreviate,
3790 unabbreviate, map, and unmap), any character may be escaped by a <con‐
3791 trol>-V whether it would have a special meaning or not.
3792 IEEE Std 1003.1-2001 requires conformance to historical practice.
3793 Historical implementations of the editor did not require delimiters
3795 within character classes to be escaped; for example, the command
3796 :s/[/]// on the string "xxx/yyy" would delete the '/' from the string.
3797 IEEE Std 1003.1-2001 disallows this historical practice for consistency
3798 and because it places a large burden on implementations by requiring
3799 that knowledge of regular expressions be built into the editor parser.
3800 Historically, quoting <newline>s in ex commands was handled inconsis‐
3802 tently. In most cases, the <newline> always terminated the command,
3803 regardless of any preceding escape character, because backslash charac‐
3804 ters did not escape <newline>s for most ex commands. However, some ex
3805 commands (for example, s, map, and abbreviation) permitted <newline>s
3806 to be escaped (although in the case of map and abbreviation, <con‐
3807 trol>-V characters escaped them instead of backslashes). This was true
3808 in not only the command line, but also .exrc and sourced files. For
3809 example, the command:
3810 map = foo<control-V><newline>bar
3813 would succeed, although it was sometimes difficult to get the <con‐
3815 trol>-V and the inserted <newline> passed to the ex parser. For consis‐
3816 tency and simplicity of specification, IEEE Std 1003.1-2001 requires
3817 that it be possible to escape <newline>s in ex commands at all times,
3818 using backslashes for most ex commands, and using <control>-V charac‐
3819 ters for the map and abbreviation commands. For example, the command
3820 print <newline> list is required to be parsed as the single command
3821 print <newline> list. While this differs from historical practice,
3822 IEEE Std 1003.1-2001 developers believed it unlikely that any script or
3823 user depended on the historical behavior.
3824 Historically, an error in a command specified using the -c option did
3826 not cause the rest of the -c commands to be discarded.
3827 IEEE Std 1003.1-2001 disallows this for consistency with mapped keys,
3828 the @, global, source, and v commands, the EXINIT environment variable,
3829 and the .exrc files.
3830 Input Editing in ex
3832 One of the common uses of the historical ex editor is over slow network
3833 connections. Editors that run in canonical mode can require far less
3834 traffic to and from, and far less processing on, the host machine, as
3835 well as more easily supporting block-mode terminals. For these reasons,
3836 IEEE Std 1003.1-2001 requires that ex be implemented using canonical
3837 mode input processing, as was done historically.
3838 IEEE Std 1003.1-2001 does not require the historical 4 BSD input edit‐
3840 ing characters "word erase" or "literal next". For this reason, it is
3841 unspecified how they are handled by ex, although they must have the
3842 required effect. Implementations that resolve them after the line has
3843 been ended using a <newline> or <control>-M character, and implementa‐
3844 tions that rely on the underlying system terminal support for this pro‐
3845 cessing, are both conforming. Implementations are strongly urged to use
3846 the underlying system functionality, if at all possible, for compati‐
3847 bility with other system text input interfaces.
3848 Historically, when the eof character was used to decrement the autoin‐
3850 dent level, the cursor moved to display the new end of the autoindent
3851 characters, but did not move the cursor to a new line, nor did it erase
3852 the <control>-D character from the line. IEEE Std 1003.1-2001 does not
3853 specify that the cursor remain on the same line or that the rest of the
3854 line is erased; however, implementations are strongly encouraged to
3855 provide the best possible user interface; that is, the cursor should
3856 remain on the same line, and any <control>-D character on the line
3857 should be erased.
3858 IEEE Std 1003.1-2001 does not require the historical 4 BSD input edit‐
3860 ing character "reprint", traditionally <control>-R, which redisplayed
3861 the current input from the user. For this reason, and because the func‐
3862 tionality cannot be implemented after the line has been terminated by
3863 the user, IEEE Std 1003.1-2001 makes no requirements about this func‐
3864 tionality. Implementations are strongly urged to make this historical
3865 functionality available, if possible.
3866 Historically, <control>-Q did not perform a literal next function in
3868 ex, as it did in vi. IEEE Std 1003.1-2001 requires conformance to his‐
3869 torical practice to avoid breaking historical ex scripts and .exrc
3870 files.
3871 eof
3873 Whether the eof character immediately modifies the autoindent charac‐
3874 ters in the prompt is left unspecified so that implementations can con‐
3875 form in the presence of systems that do not support this functionality.
3876 Implementations are encouraged to modify the line and redisplay it
3877 immediately, if possible.
3878 The specification of the handling of the eof character differs from
3880 historical practice only in that eof characters are not discarded if
3881 they follow normal characters in the text input. Historically, they
3882 were always discarded.
3883 Command Descriptions in ex
3885 Historically, several commands (for example, global, v, visual, s,
3886 write, wq, yank, !, <, >, &, and ~) were executable in empty files
3887 (that is, the default address(es) were 0), or permitted explicit
3888 addresses of 0 (for example, 0 was a valid address, or 0,0 was a valid
3889 range). Addresses of 0, or command execution in an empty file, make
3890 sense only for commands that add new text to the edit buffer or write
3891 commands (because users may wish to write empty files).
3892 IEEE Std 1003.1-2001 requires this behavior for such commands and dis‐
3893 allows it otherwise, for consistency and simplicity of specification.
3894 A count to an ex command has been historically corrected to be no
3896 greater than the last line in a file; for example, in a five-line file,
3897 the command 1,6print would fail, but the command 1print300 would suc‐
3898 ceed. IEEE Std 1003.1-2001 requires conformance to historical prac‐
3899 tice.
3900 Historically, the use of flags in ex commands could be obscure. Gen‐
3902 eral historical practice was as described by IEEE Std 1003.1-2001, but
3903 there were some special cases. For instance, the list, number, and
3904 print commands ignored trailing address offsets; for example, 3p +++#
3905 would display line 3, and 3 would be the current line after the execu‐
3906 tion of the command. The open and visual commands ignored both the
3907 trailing offsets and the trailing flags. Also, flags specified to the
3908 open and visual commands interacted badly with the list edit option,
3909 and setting and then unsetting it during the open/visual session would
3910 cause vi to stop displaying lines in the specified format. For consis‐
3911 tency and simplicity of specification, IEEE Std 1003.1-2001 does not
3912 permit any of these exceptions to the general rule.
3913 IEEE Std 1003.1-2001 uses the word copy in several places when dis‐
3915 cussing buffers. This is not intended to imply implementation.
3916 Historically, ex users could not specify numeric buffers because of the
3918 ambiguity this would cause; for example, in the command 3 delete 2, it
3919 is unclear whether 2 is a buffer name or a count. IEEE Std 1003.1-2001
3920 requires conformance to historical practice by default, but does not
3921 preclude extensions.
3922 Historically, the contents of the unnamed buffer were frequently dis‐
3924 carded after commands that did not explicitly affect it; for example,
3925 when using the edit command to switch files. For consistency and sim‐
3926 plicity of specification, IEEE Std 1003.1-2001 does not permit this
3927 behavior.
3928 The ex utility did not historically have access to the numeric buffers,
3930 and, furthermore, deleting lines in ex did not modify their contents.
3931 For example, if, after doing a delete in vi, the user switched to ex,
3932 did another delete, and then switched back to vi, the contents of the
3933 numeric buffers would not have changed. IEEE Std 1003.1-2001 requires
3934 conformance to historical practice. Numeric buffers are described in
3935 the ex utility in order to confine the description of buffers to a sin‐
3936 gle location in IEEE Std 1003.1-2001.
3937 The metacharacters that trigger shell expansion in file arguments match
3939 historical practice, as does the method for doing shell expansion.
3940 Implementations wishing to provide users with the flexibility to alter
3941 the set of metacharacters are encouraged to provide a shellmeta string
3942 edit option.
3943 Historically, ex commands executed from vi refreshed the screen when it
3945 did not strictly need to do so; for example, :!date > /dev/null does
3946 not require a screen refresh because the output of the UNIX date com‐
3947 mand requires only a single line of the screen. IEEE Std 1003.1-2001
3948 requires that the screen be refreshed if it has been overwritten, but
3949 makes no requirements as to how an implementation should make that
3950 determination. Implementations may prompt and refresh the screen
3951 regardless.
3952 Abbreviate
3954 Historical practice was that characters that were entered as part of an
3955 abbreviation replacement were subject to map expansions, the showmatch
3956 edit option, further abbreviation expansions, and so on; that is, they
3957 were logically pushed onto the terminal input queue, and were not a
3958 simple replacement. IEEE Std 1003.1-2001 requires conformance to his‐
3959 torical practice. Historical practice was that whenever a non-word
3960 character (that had not been escaped by a <control>-V) was entered
3961 after a word character, vi would check for abbreviations. The check was
3962 based on the type of the character entered before the word character of
3963 the word/non-word pair that triggered the check. The word character of
3964 the word/non-word pair that triggered the check and all characters
3965 entered before the trigger pair that were of that type were included in
3966 the check, with the exception of <blank>s, which always delimited the
3967 abbreviation.
3968 This means that, for the abbreviation to work, the lhs must end with a
3970 word character, there can be no transitions from word to non-word char‐
3971 acters (or vice versa) other than between the last and next-to-last
3972 characters in the lhs, and there can be no <blank>s in the lhs. In
3973 addition, because of the historical quoting rules, it was impossible to
3974 enter a literal <control>-V in the lhs. IEEE Std 1003.1-2001 requires
3975 conformance to historical practice. Historical implementations did not
3976 inform users when abbreviations that could never be used were entered;
3977 implementations are strongly encouraged to do so.
3978 For example, the following abbreviations will work:
3980 :ab (p REPLACE
3983 :ab p REPLACE
3984 :ab ((p REPLACE
3985 The following abbreviations will not work:
3987 :ab ( REPLACE
3990 :ab (pp REPLACE
3991 Historical practice is that words on the vi colon command line were
3993 subject to abbreviation expansion, including the arguments to the
3994 abbrev (and more interestingly) the unabbrev command. Because there are
3995 implementations that do not do abbreviation expansion for the first
3996 argument to those commands, this is permitted, but not required, by
3997 IEEE Std 1003.1-2001. However, the following sequence:
3998 :ab foo bar
4001 :ab foo baz
4002 resulted in the addition of an abbreviation of "baz" for the string
4004 "bar" in historical ex/ vi, and the sequence:
4005 :ab foo1 bar
4008 :ab foo2 bar
4009 :unabbreviate foo2
4010 deleted the abbreviation "foo1", not "foo2" . These behaviors are not
4012 permitted by IEEE Std 1003.1-2001 because they clearly violate the
4013 expectations of the user.
4014 It was historical practice that <control>-V, not backslash, characters
4016 be interpreted as escaping subsequent characters in the abbreviate com‐
4017 mand. IEEE Std 1003.1-2001 requires conformance to historical practice;
4018 however, it should be noted that an abbreviation containing a <blank>
4019 will never work.
4020 Append
4022 Historically, any text following a vertical-line command separator
4023 after an append, change, or insert command became part of the insert
4024 text. For example, in the command:
4025 :g/pattern/append|stuff1
4028 a line containing the text "stuff1" would be appended to each line
4030 matching pattern. It was also historically valid to enter:
4031 :append|stuff1
4034 stuff2
4035 .
4036 and the text on the ex command line would be appended along with the
4038 text inserted after it. There was an historical bug, however, that the
4039 user had to enter two terminating lines (the '.' lines) to terminate
4040 text input mode in this case. IEEE Std 1003.1-2001 requires confor‐
4041 mance to historical practice, but disallows the historical need for
4042 multiple terminating lines.
4043 Change
4045 See the RATIONALE for the append command. Historical practice for cur‐
4046 sor positioning after the change command when no text is input, is as
4047 described in IEEE Std 1003.1-2001. However, one System V implementation
4048 is known to have been modified such that the cursor is positioned on
4049 the first address specified, and not on the line before the first
4050 address. IEEE Std 1003.1-2001 disallows this modification for consis‐
4051 tency.
4052 Historically, the change command did not support buffer arguments,
4054 although some implementations allow the specification of an optional
4055 buffer. This behavior is neither required nor disallowed by
4056 IEEE Std 1003.1-2001.
4057 Change Directory
4059 A common extension in ex implementations is to use the elements of a
4060 cdpath edit option as prefix directories for path arguments to chdir
4061 that are relative pathnames and that do not have '.' or ".." as their
4062 first component. Elements in the cdpath edit option are colon-sepa‐
4063 rated. The initial value of the cdpath edit option is the value of the
4064 shell CDPATH environment variable. This feature was not included in
4065 IEEE Std 1003.1-2001 because it does not exist in any of the implemen‐
4066 tations considered historical practice.
4067 Copy
4069 Historical implementations of ex permitted copies to lines inside of
4070 the specified range; for example, :2,5copy3 was a valid command.
4071 IEEE Std 1003.1-2001 requires conformance to historical practice.
4072 Delete
4074 IEEE Std 1003.1-2001 requires support for the historical parsing of a
4075 delete command followed by flags, without any intervening <blank>s. For
4076 example:
4077 1dp Deletes the first line and prints the line that was second.
4079 1delep As for 1dp.
4081 1d Deletes the first line, saving it in buffer p.
4083 1d p1l (Pee-one-ell.) Deletes the first line, saving it in buffer p,
4085 and listing the line that was second.
4086 Edit
4089 Historically, any ex command could be entered as a + command argument
4090 to the edit command, although some (for example, insert and append)
4091 were known to confuse historical implementations. For consistency and
4092 simplicity of specification, IEEE Std 1003.1-2001 requires that any
4093 command be supported as an argument to the edit command.
4094 Historically, the command argument was executed with the current line
4096 set to the last line of the file, regardless of whether the edit com‐
4097 mand was executed from visual mode or not. IEEE Std 1003.1-2001
4098 requires conformance to historical practice.
4099 Historically, the + command specified to the edit and next commands was
4101 delimited by the first <blank>, and there was no way to quote them. For
4102 consistency, IEEE Std 1003.1-2001 requires that the usual ex backslash
4103 quoting be provided.
4104 Historically, specifying the + command argument to the edit command
4106 required a filename to be specified as well; for example, :edit +100
4107 would always fail. For consistency and simplicity of specification,
4108 IEEE Std 1003.1-2001 does not permit this usage to fail for that rea‐
4109 son.
4110 Historically, only the cursor position of the last file edited was
4112 remembered by the editor. IEEE Std 1003.1-2001 requires that this be
4113 supported; however, implementations are permitted to remember and
4114 restore the cursor position for any file previously edited.
4115 File
4117 Historical versions of the ex editor file command displayed a current
4118 line and number of lines in the edit buffer of 0 when the file was
4119 empty, while the vi <control>-G command displayed a current line and
4120 number of lines in the edit buffer of 1 in the same situation.
4121 IEEE Std 1003.1-2001 does not permit this discrepancy, instead requir‐
4122 ing that a message be displayed indicating that the file is empty.
4123 Global
4125 The two-pass operation of the global and v commands is not intended to
4126 imply implementation, only the required result of the operation.
4127 The current line and column are set as specified for the individual ex
4129 commands. This requirement is cumulative; that is, the current line and
4130 column must track across all the commands executed by the global or v
4131 commands.
4132 Insert
4134 See the RATIONALE for the append command.
4135 Historically, insert could not be used with an address of zero; that
4137 is, not when the edit buffer was empty. IEEE Std 1003.1-2001 requires
4138 that this command behave consistently with the append command.
4139 Join
4141 The action of the join command in relation to the special characters is
4142 only defined for the POSIX locale because the correct amount of white
4143 space after a period varies; in Japanese none is required, in French
4144 only a single space, and so on.
4145 List
4147 The historical output of the list command was potentially ambiguous.
4148 The standard developers believed correcting this to be more important
4149 than adhering to historical practice, and IEEE Std 1003.1-2001 requires
4150 unambiguous output.
4151 Map
4153 Historically, command mode maps only applied to command names; for
4154 example, if the character 'x' was mapped to 'y', the command fx
4155 searched for the 'x' character, not the 'y' character.
4156 IEEE Std 1003.1-2001 requires this behavior. Historically, entering
4157 <control>-V as the first character of a vi command was an error. Sev‐
4158 eral implementations have extended the semantics of vi such that <con‐
4159 trol>-V means that the subsequent command character is not mapped. This
4160 is permitted, but not required, by IEEE Std 1003.1-2001. Regardless,
4161 using <control>-V to escape the second or later character in a sequence
4162 of characters that might match a map command, or any character in text
4163 input mode, is historical practice, and stops the entered keys from
4164 matching a map. IEEE Std 1003.1-2001 requires conformance to historical
4165 practice.
4166 Historical implementations permitted digits to be used as a map command
4168 lhs, but then ignored the map. IEEE Std 1003.1-2001 requires that the
4169 mapped digits not be ignored.
4170 The historical implementation of the map command did not permit map
4172 commands that were more than a single character in length if the first
4173 character was printable. This behavior is permitted, but not required,
4174 by IEEE Std 1003.1-2001.
4175 Historically, mapped characters were remapped unless the remap edit
4177 option was not set, or the prefix of the mapped characters matched the
4178 mapping characters; for example, in the map:
4179 :map ab abcd
4182 the characters "ab" were used as is and were not remapped, but the
4184 characters "cd" were mapped if appropriate. This can cause infinite
4185 loops in the vi mapping mechanisms. IEEE Std 1003.1-2001 requires con‐
4186 formance to historical practice, and that such loops be interruptible.
4187 Text input maps had the same problems with expanding the lhs for the ex
4189 map! and unmap! command as did the ex abbreviate and unabbreviate com‐
4190 mands. See the RATIONALE for the ex abbreviate command.
4191 IEEE Std 1003.1-2001 requires similar modification of some historical
4192 practice for the map and unmap commands, as described for the abbrevi‐
4193 ate and unabbreviate commands.
4194 Historically, maps that were subsets of other maps behaved differently
4196 depending on the order in which they were defined. For example:
4197 :map! ab short
4200 :map! abc long
4201 would always translate the characters "ab" to "short", regardless of
4203 how fast the characters "abc" were entered. If the entry order was
4204 reversed:
4205 :map! abc long
4208 :map! ab short
4209 the characters "ab" would cause the editor to pause, waiting for the
4211 completing 'c' character, and the characters might never be mapped to
4212 "short" . For consistency and simplicity of specification,
4213 IEEE Std 1003.1-2001 requires that the shortest match be used at all
4214 times.
4215 The length of time the editor spends waiting for the characters to com‐
4217 plete the lhs is unspecified because the timing capabilities of systems
4218 are often inexact and variable, and it may depend on other factors such
4219 as the speed of the connection. The time should be long enough for the
4220 user to be able to complete the sequence, but not long enough for the
4221 user to have to wait. Some implementations of vi have added a keytime
4222 option, which permits users to set the number of 0,1 seconds the editor
4223 waits for the completing characters. Because mapped terminal function
4224 and cursor keys tend to start with an <ESC> character, and <ESC> is the
4225 key ending vi text input mode, maps starting with <ESC> characters are
4226 generally exempted from this timeout period, or, at least timed out
4227 differently.
4228 Mark
4230 Historically, users were able to set the "previous context" marks
4231 explicitly. In addition, the ex commands " and '` and the vi commands
4232 ", ``, `', and '` all referred to the same mark. In addition, the pre‐
4233 vious context marks were not set if the command, with which the address
4234 setting the mark was associated, failed. IEEE Std 1003.1-2001 requires
4235 conformance to historical practice. Historically, if marked lines were
4236 deleted, the mark was also deleted, but would reappear if the change
4237 was undone. IEEE Std 1003.1-2001 requires conformance to historical
4238 practice.
4239 The description of the special events that set the ` and ' marks
4241 matches historical practice. For example, historically the command
4242 /a/,/b/ did not set the ` and ' marks, but the command /a/,/b/delete
4243 did.
4244 Next
4246 Historically, any ex command could be entered as a + command argument
4247 to the next command, although some (for example, insert and append)
4248 were known to confuse historical implementations. IEEE Std 1003.1-2001
4249 requires that any command be permitted and that it behave as specified.
4250 The next command can accept more than one file, so usage such as:
4251 next `ls [abc] `
4254 is valid; it need not be valid for the edit or read commands, for exam‐
4256 ple, because they expect only one filename.
4257 Historically, the next command behaved differently from the :rewind
4259 command in that it ignored the force flag if the autowrite flag was
4260 set. For consistency, IEEE Std 1003.1-2001 does not permit this behav‐
4261 ior.
4262 Historically, the next command positioned the cursor as if the file had
4264 never been edited before, regardless. IEEE Std 1003.1-2001 does not
4265 permit this behavior, for consistency with the edit command.
4266 Implementations wanting to provide a counterpart to the next command
4268 that edited the previous file have used the command prev[ious], which
4269 takes no file argument. IEEE Std 1003.1-2001 does not require this com‐
4270 mand.
4271 Open
4273 Historically, the open command would fail if the open edit option was
4274 not set. IEEE Std 1003.1-2001 does not mention the open edit option and
4275 does not require this behavior. Some historical implementations do not
4276 permit entering open mode from open or visual mode, only from ex mode.
4277 For consistency, IEEE Std 1003.1-2001 does not permit this behavior.
4278 Historically, entering open mode from the command line (that is, vi
4280 +open) resulted in anomalous behaviors; for example, the ex file and
4281 set commands, and the vi command <control>-G did not work. For consis‐
4282 tency, IEEE Std 1003.1-2001 does not permit this behavior.
4283 Historically, the open command only permitted '/' characters to be used
4285 as the search pattern delimiter. For consistency, IEEE Std 1003.1-2001
4286 requires that the search delimiters used by the s, global, and v com‐
4287 mands be accepted as well.
4288 Preserve
4290 The preserve command does not historically cause the file to be consid‐
4291 ered unmodified for the purposes of future commands that may exit the
4292 editor. IEEE Std 1003.1-2001 requires conformance to historical prac‐
4293 tice.
4294 Historical documentation stated that mail was not sent to the user when
4296 preserve was executed; however, historical implementations did send
4297 mail in this case. IEEE Std 1003.1-2001 requires conformance to the
4298 historical implementations.
4299 Print
4301 The writing of NUL by the print command is not specified as a special
4302 case because the standard developers did not want to require ex to sup‐
4303 port NUL characters. Historically, characters were displayed using the
4304 ARPA standard mappings, which are as follows:
4305 1. Printable characters are left alone.
4307 2. Control characters less than \177 are represented as '^' followed
4309 by the character offset from the '@' character in the ASCII map;
4310 for example, \007 is represented as '^G' .
4311 3. \177 is represented as '^' followed by '?' .
4313 The display of characters having their eighth bit set was less stan‐
4315 dard. Existing implementations use hex (0x00), octal (\000), and a
4316 meta-bit display. (The latter displayed bytes that had their eighth bit
4317 set as the two characters "M-" followed by the seven-bit display as
4318 described above.) The latter probably has the best claim to historical
4319 practice because it was used for the -v option of 4 BSD and 4 BSD-
4320 derived versions of the cat utility since 1980.
4321 No specific display format is required by IEEE Std 1003.1-2001.
4323 Explicit dependence on the ASCII character set has been avoided where
4325 possible, hence the use of the phrase an "implementation-defined multi-
4326 character sequence" for the display of non-printable characters in
4327 preference to the historical usage of, for instance, "^I" for the
4328 <tab>. Implementations are encouraged to conform to historical practice
4329 in the absence of any strong reason to diverge.
4330 Historically, all ex commands beginning with the letter 'p' could be
4332 entered using capitalized versions of the commands; for example,
4333 P[rint], Pre[serve], and Pu[t] were all valid command names.
4334 IEEE Std 1003.1-2001 permits, but does not require, this historical
4335 practice because capital forms of the commands are used by some imple‐
4336 mentations for other purposes.
4337 Put
4339 Historically, an ex put command, executed from open or visual mode, was
4340 the same as the open or visual mode P command, if the buffer was named
4341 and was cut in character mode, and the same as the p command if the
4342 buffer was named and cut in line mode. If the unnamed buffer was the
4343 source of the text, the entire line from which the text was taken was
4344 usually put, and the buffer was handled as if in line mode, but it was
4345 possible to get extremely anomalous behavior. In addition, using the Q
4346 command to switch into ex mode, and then doing a put often resulted in
4347 errors as well, such as appending text that was unrelated to the (sup‐
4348 posed) contents of the buffer. For consistency and simplicity of speci‐
4349 fication, IEEE Std 1003.1-2001 does not permit these behaviors. All ex
4350 put commands are required to operate in line mode, and the contents of
4351 the buffers are not altered by changing the mode of the editor.
4352 Read
4354 Historically, an ex read command executed from open or visual mode,
4355 executed in an empty file, left an empty line as the first line of the
4356 file. For consistency and simplicity of specification,
4357 IEEE Std 1003.1-2001 does not permit this behavior. Historically, a
4358 read in open or visual mode from a program left the cursor at the last
4359 line read in, not the first. For consistency, IEEE Std 1003.1-2001 does
4360 not permit this behavior.
4361 Historical implementations of ex were unable to undo read commands that
4363 read from the output of a program. For consistency,
4364 IEEE Std 1003.1-2001 does not permit this behavior.
4365 Historically, the ex and vi message after a successful read or write
4367 command specified "characters", not "bytes". IEEE Std 1003.1-2001
4368 requires that the number of bytes be displayed, not the number of char‐
4369 acters, because it may be difficult in multi-byte implementations to
4370 determine the number of characters read. Implementations are encouraged
4371 to clarify the message displayed to the user.
4372 Historically, reads were not permitted on files other than type regu‐
4374 lar, except that FIFO files could be read (probably only because they
4375 did not exist when ex and vi were originally written). Because the his‐
4376 torical ex evaluated read! and read ! equivalently, there can be no
4377 optional way to force the read. IEEE Std 1003.1-2001 permits, but does
4378 not require, this behavior.
4379 Recover
4381 Some historical implementations of the editor permitted users to
4382 recover the edit buffer contents from a previous edit session, and then
4383 exit without saving those contents (or explicitly discarding them). The
4384 intent of IEEE Std 1003.1-2001 in requiring that the edit buffer be
4385 treated as already modified is to prevent this user error.
4386 Rewind
4388 Historical implementations supported the rewind command when the user
4389 was editing the first file in the list; that is, the file that the
4390 rewind command would edit. IEEE Std 1003.1-2001 requires conformance to
4391 historical practice.
4392 Substitute
4394 Historically, ex accepted an r option to the s command. The effect of
4395 the r option was to use the last regular expression used in any command
4396 as the pattern, the same as the ~ command. The r option is not required
4397 by IEEE Std 1003.1-2001. Historically, the c and g options were tog‐
4398 gled; for example, the command :s/abc/def/ was the same as
4399 s/abc/def/ccccgggg. For simplicity of specification,
4400 IEEE Std 1003.1-2001 does not permit this behavior.
4401 The tilde command is often used to replace the last search RE. For
4403 example, in the sequence:
4404 s/red/blue/
4407 /green
4408 ~
4409 the ~ command is equivalent to:
4411 s/green/blue/
4414 Historically, ex accepted all of the following forms:
4416 s/abc/def/
4419 s/abc/def
4420 s/abc/
4421 s/abc
4422 IEEE Std 1003.1-2001 requires conformance to this historical practice.
4424 The s command presumes that the '^' character only occupies a single
4426 column in the display. Much of the ex and vi specification presumes
4427 that the <space> only occupies a single column in the display. There
4428 are no known character sets for which this is not true.
4429 Historically, the final column position for the substitute commands was
4431 based on previous column movements; a search for a pattern followed by
4432 a substitution would leave the column position unchanged, while a 0
4433 command followed by a substitution would change the column position to
4434 the first non- <blank>. For consistency and simplicity of specifica‐
4435 tion, IEEE Std 1003.1-2001 requires that the final column position
4436 always be set to the first non- <blank>.
4437 Set
4439 Historical implementations redisplayed all of the options for each
4440 occurrence of the all keyword. IEEE Std 1003.1-2001 permits, but does
4441 not require, this behavior.
4442 Tag
4444 No requirement is made as to where ex and vi shall look for the file
4445 referenced by the tag entry. Historical practice has been to look for
4446 the path found in the tags file, based on the current directory. A
4447 useful extension found in some implementations is to look based on the
4448 directory containing the tags file that held the entry, as well. No
4449 requirement is made as to which reference for the tag in the tags file
4450 is used. This is deliberate, in order to permit extensions such as mul‐
4451 tiple entries in a tags file for a tag.
4452 Because users often specify many different tags files, some of which
4454 need not be relevant or exist at any particular time,
4455 IEEE Std 1003.1-2001 requires that error messages about problem tags
4456 files be displayed only if the requested tag is not found, and then,
4457 only once for each time that the tag edit option is changed.
4458 The requirement that the current edit buffer be unmodified is only nec‐
4460 essary if the file indicated by the tag entry is not the same as the
4461 current file (as defined by the current pathname). Historically, the
4462 file would be reloaded if the filename had changed, as well as if the
4463 filename was different from the current pathname. For consistency and
4464 simplicity of specification, IEEE Std 1003.1-2001 does not permit this
4465 behavior, requiring that the name be the only factor in the decision.
4466 Historically, vi only searched for tags in the current file from the
4468 current cursor to the end of the file, and therefore, if the wrapscan
4469 option was not set, tags occurring before the current cursor were not
4470 found. IEEE Std 1003.1-2001 considers this a bug, and implementations
4471 are required to search for the first occurrence in the file, regard‐
4472 less.
4473 Undo
4475 The undo description deliberately uses the word "modified". The undo
4476 command is not intended to undo commands that replace the contents of
4477 the edit buffer, such as edit, next, tag, or recover.
4478 Cursor positioning after the undo command was inconsistent in the his‐
4480 torical vi, sometimes attempting to restore the original cursor posi‐
4481 tion ( global, undo, and v commands), and sometimes, in the presence of
4482 maps, placing the cursor on the last line added or changed instead of
4483 the first. IEEE Std 1003.1-2001 requires a simplified behavior for con‐
4484 sistency and simplicity of specification.
4485 Version
4487 The version command cannot be exactly specified since there is no
4488 widely-accepted definition of what the version information should con‐
4489 tain. Implementations are encouraged to do something reasonably intel‐
4490 ligent.
4491 Write
4493 Historically, the ex and vi message after a successful read or write
4494 command specified "characters", not "bytes". IEEE Std 1003.1-2001
4495 requires that the number of bytes be displayed, not the number of char‐
4496 acters because it may be difficult in multi-byte implementations to
4497 determine the number of characters written. Implementations are encour‐
4498 aged to clarify the message displayed to the user.
4499 Implementation-defined tests are permitted so that implementations can
4501 make additional checks; for example, for locks or file modification
4502 times.
4503 Historically, attempting to append to a nonexistent file caused an
4505 error. It has been left unspecified in IEEE Std 1003.1-2001 to permit
4506 implementations to let the write succeed, so that the append semantics
4507 are similar to those of the historical csh.
4508 Historical vi permitted empty edit buffers to be written. However,
4510 since the way vi got around dealing with "empty" files was to always
4511 have a line in the edit buffer, no matter what, it wrote them as files
4512 of a single, empty line. IEEE Std 1003.1-2001 does not permit this
4513 behavior.
4514 Historically, ex restored standard output and standard error to their
4516 values as of when ex was invoked, before writes to programs were per‐
4517 formed. This could disturb the terminal configuration as well as be a
4518 security issue for some terminals. IEEE Std 1003.1-2001 does not per‐
4519 mit this, requiring that the program output be captured and displayed
4520 as if by the ex print command.
4521 Adjust Window
4523 Historically, the line count was set to the value of the scroll option
4524 if the type character was end-of-file. This feature was broken on most
4525 historical implementations long ago, however, and is not documented
4526 anywhere. For this reason, IEEE Std 1003.1-2001 is resolutely silent.
4527 Historically, the z command was <blank>-sensitive and z + and z - did
4529 different things than z+ and z- because the type could not be distin‐
4530 guished from a flag. (The commands z\fP. and z = were historically
4531 invalid.) IEEE Std 1003.1-2001 requires conformance to this historical
4532 practice.
4533 Historically, the z command was further <blank>-sensitive in that the
4535 count could not be <blank>-delimited; for example, the commands z= 5
4536 and z- 5 were also invalid. Because the count is not ambiguous with
4537 respect to either the type character or the flags, this is not permit‐
4538 ted by IEEE Std 1003.1-2001.
4539 Escape
4541 Historically, ex filter commands only read the standard output of the
4542 commands, letting standard error appear on the terminal as usual. The
4543 vi utility, however, read both standard output and standard error.
4544 IEEE Std 1003.1-2001 requires the latter behavior for both ex and vi,
4545 for consistency.
4546 Shift Left and Shift Right
4548 Historically, it was possible to add shift characters to increase the
4549 effect of the command; for example, <<< outdented (or >>> indented) the
4550 lines 3 levels of indentation instead of the default 1.
4551 IEEE Std 1003.1-2001 requires conformance to historical practice.
4552 <control>-D
4554 Historically, the <control>-D command erased the prompt, providing the
4555 user with an unbroken presentation of lines from the edit buffer. This
4556 is not required by IEEE Std 1003.1-2001; implementations are encouraged
4557 to provide it if possible. Historically, the <control>-D command took,
4558 and then ignored, a count. IEEE Std 1003.1-2001 does not permit this
4559 behavior.
4560 Write Line Number
4562 Historically, the ex = command, when executed in ex mode in an empty
4563 edit buffer, reported 0, and from open or visual mode, reported 1. For
4564 consistency and simplicity of specification, IEEE Std 1003.1-2001 does
4565 not permit this behavior.
4566 Execute
4568 Historically, ex did not correctly handle the inclusion of text input
4569 commands (that is, append, insert, and change) in executed buffers.
4570 IEEE Std 1003.1-2001 does not permit this exclusion for consistency.
4571 Historically, the logical contents of the buffer being executed did not
4573 change if the buffer itself were modified by the commands being exe‐
4574 cuted; that is, buffer execution did not support self-modifying code.
4575 IEEE Std 1003.1-2001 requires conformance to historical practice.
4576 Historically, the @ command took a range of lines, and the @ buffer was
4578 executed once per line, with the current line ( '.' ) set to each spec‐
4579 ified line. IEEE Std 1003.1-2001 requires conformance to historical
4580 practice.
4581 Some historical implementations did not notice if errors occurred dur‐
4583 ing buffer execution. This, coupled with the ability to specify a range
4584 of lines for the ex @ command, makes it trivial to cause them to drop
4585 core. IEEE Std 1003.1-2001 requires that implementations stop buffer
4586 execution if any error occurs, if the specified line doesn't exist, or
4587 if the contents of the edit buffer itself are replaced (for example,
4588 the buffer executes the ex :edit command).
4589 Regular Expressions in ex
4591 Historical practice is that the characters in the replacement part of
4592 the last s command-that is, those matched by entering a '~' in the reg‐
4593 ular expression-were not further expanded by the regular expression
4594 engine. So, if the characters contained the string "a.," they would
4595 match 'a' followed by ".," and not 'a' followed by any character.
4596 IEEE Std 1003.1-2001 requires conformance to historical practice.
4597 Edit Options in ex
4599 The following paragraphs describe the historical behavior of some edit
4600 options that were not, for whatever reason, included in
4601 IEEE Std 1003.1-2001. Implementations are strongly encouraged to only
4602 use these names if the functionality described here is fully supported.
4603 extended
4605 The extended edit option has been used in some implementations
4606 of vi to provide extended regular expressions instead of basic
4607 regular expressions This option was omitted from
4608 IEEE Std 1003.1-2001 because it is not widespread historical
4609 practice.
4610 flash The flash edit option historically caused the screen to flash
4612 instead of beeping on error. This option was omitted from
4613 IEEE Std 1003.1-2001 because it is not found in some historical
4614 implementations.
4615 hardtabs
4617 The hardtabs edit option historically defined the number of col‐
4618 umns between hardware tab settings. This option was omitted from
4619 IEEE Std 1003.1-2001 because it was believed to no longer be
4620 generally useful.
4621 modeline
4623 The modeline (sometimes named modelines) edit option histori‐
4624 cally caused ex or vi to read the five first and last lines of
4625 the file for editor commands. This option is a security problem,
4626 and vendors are strongly encouraged to delete it from historical
4627 implementations.
4628 open The open edit option historically disallowed the ex open and
4630 visual commands. This edit option was omitted because these com‐
4631 mands are required by IEEE Std 1003.1-2001.
4632 optimize
4634 The optimize edit option historically expedited text throughput
4635 by setting the terminal to not do automatic <carriage-return>s
4636 when printing more than one logical line of output. This option
4637 was omitted from IEEE Std 1003.1-2001 because it was intended
4638 for terminals without addressable cursors, which are rarely, if
4639 ever, still used.
4640 ruler The ruler edit option has been used in some implementations of
4642 vi to present a current row/column ruler for the user. This
4643 option was omitted from IEEE Std 1003.1-2001 because it is not
4644 widespread historical practice.
4645 sourceany
4647 The sourceany edit option historically caused ex or vi to source
4648 start-up files that were owned by users other than the user run‐
4649 ning the editor. This option is a security problem, and vendors
4650 are strongly encouraged to remove it from their implementations.
4651 timeout
4653 The timeout edit option historically enabled the (now standard)
4654 feature of only waiting for a short period before returning keys
4655 that could be part of a macro. This feature was omitted from
4656 IEEE Std 1003.1-2001 because its behavior is now standard, it is
4657 not widely useful, and it was rarely documented.
4658 verbose
4660 The verbose edit option has been used in some implementations of
4661 vi to cause vi to output error messages for common errors; for
4662 example, attempting to move the cursor past the beginning or end
4663 of the line instead of only alerting the screen. (The historical
4664 vi only alerted the terminal and presented no message for such
4665 errors. The historical editor option terse did not select when
4666 to present error messages, it only made existing error messages
4667 more or less verbose.) This option was omitted from
4668 IEEE Std 1003.1-2001 because it is not widespread historical
4669 practice; however, implementors are encouraged to use it if they
4670 wish to provide error messages for naive users.
4671 wraplen
4673 The wraplen edit option has been used in some implementations of
4674 vi to specify an automatic margin measured from the left margin
4675 instead of from the right margin. This is useful when multiple
4676 screen sizes are being used to edit a single file. This option
4677 was omitted from IEEE Std 1003.1-2001 because it is not wide‐
4678 spread historical practice; however, implementors are encouraged
4679 to use it if they add this functionality.
4680 autoindent, ai
4683 Historically, the command 0a did not do any autoindentation, regardless
4684 of the current indentation of line 1. IEEE Std 1003.1-2001 requires
4685 that any indentation present in line 1 be used.
4686 autoprint, ap
4688 Historically, the autoprint edit option was not completely consistent
4689 or based solely on modifications to the edit buffer. Exceptions were
4690 the read command (when reading from a file, but not from a filter), the
4691 append, change, insert, global, and v commands, all of which were not
4692 affected by autoprint, and the tag command, which was affected by auto‐
4693 print. IEEE Std 1003.1-2001 requires conformance to historical prac‐
4694 tice.
4695 Historically, the autoprint option only applied to the last of multiple
4697 commands entered using vertical-bar delimiters; for example, delete
4698 <newline> was affected by autoprint, but delete|version <newline> was
4699 not. IEEE Std 1003.1-2001 requires conformance to historical practice.
4700 autowrite, aw
4702 Appending the '!' character to the ex next command to avoid performing
4703 an automatic write was not supported in historical implementations.
4704 IEEE Std 1003.1-2001 requires that the behavior match the other ex com‐
4705 mands for consistency.
4706 ignorecase, ic
4708 Historical implementations of case-insensitive matching (the ignorecase
4709 edit option) lead to counterintuitive situations when uppercase charac‐
4710 ters were used in range expressions. Historically, the process was as
4711 follows:
4712 1. Take a line of text from the edit buffer.
4714 2. Convert uppercase to lowercase in text line.
4716 3. Convert uppercase to lowercase in regular expressions, except in
4718 character class specifications.
4719 4. Match regular expressions against text.
4721 This would mean that, with ignorecase in effect, the text:
4723 The cat sat on the mat
4726 would be matched by
4728 /^the/
4731 but not by:
4733 /^[A-Z]he/
4736 For consistency with other commands implementing regular expressions,
4738 IEEE Std 1003.1-2001 does not permit this behavior.
4739 paragraphs, para
4741 The ISO POSIX-2:1993 standard made the default paragraphs and sections
4742 edit options implementation-defined, arguing they were historically
4743 oriented to the UNIX system troff text formatter, and a "portable user"
4744 could use the {, }, [[, ]], (, and ) commands in open or visual mode
4745 and have the cursor stop in unexpected places. IEEE Std 1003.1-2001
4746 specifies their values in the POSIX locale because the unusual grouping
4747 (they only work when grouped into two characters at a time) means that
4748 they cannot be used for general-purpose movement, regardless.
4749 readonly
4751 Implementations are encouraged to provide the best possible information
4752 to the user as to the read-only status of the file, with the exception
4753 that they should not consider the current special privileges of the
4754 process. This provides users with a safety net because they must force
4755 the overwrite of read-only files, even when running with additional
4756 privileges.
4757 The readonly edit option specification largely conforms to historical
4759 practice. The only difference is that historical implementations did
4760 not notice that the user had set the readonly edit option in cases
4761 where the file was already marked read-only for some reason, and would
4762 therefore reinitialize the readonly edit option the next time the con‐
4763 tents of the edit buffer were replaced. This behavior is disallowed by
4764 IEEE Std 1003.1-2001.
4765 report
4767 The requirement that lines copied to a buffer interact differently than
4768 deleted lines is historical practice. For example, if the report edit
4769 option is set to 3, deleting 3 lines will cause a report to be written,
4770 but 4 lines must be copied before a report is written.
4771 The requirement that the ex global, v, open, undo, and visual commands
4773 present reports based on the total number of lines added or deleted
4774 during the command execution, and that commands executed by the global
4775 and v commands not present reports, is historical practice.
4776 IEEE Std 1003.1-2001 extends historical practice by requiring that buf‐
4777 fer execution be treated similarly. The reasons for this are two-fold.
4778 Historically, only the report by the last command executed from the
4779 buffer would be seen by the user, as each new report would overwrite
4780 the last. In addition, the standard developers believed that buffer
4781 execution had more in common with global and v commands than it did
4782 with other ex commands, and should behave similarly, for consistency
4783 and simplicity of specification.
4784 showmatch, sm
4786 The length of time the cursor spends on the matching character is
4787 unspecified because the timing capabilities of systems are often inex‐
4788 act and variable. The time should be long enough for the user to
4789 notice, but not long enough for the user to become annoyed. Some imple‐
4790 mentations of vi have added a matchtime option that permits users to
4791 set the number of 0,1 second intervals the cursor pauses on the match‐
4792 ing character.
4793 showmode
4795 The showmode option has been used in some historical implementations of
4796 ex and vi to display the current editing mode when in open or visual
4797 mode. The editing modes have generally included "command" and "input",
4798 and sometimes other modes such as "replace" and "change". The string
4799 was usually displayed on the bottom line of the screen at the far
4800 right-hand corner. In addition, a preceding '*' character often
4801 denoted whether the contents of the edit buffer had been modified. The
4802 latter display has sometimes been part of the showmode option, and
4803 sometimes based on another option. This option was not available in the
4804 4 BSD historical implementation of vi, but was viewed as generally use‐
4805 ful, particularly to novice users, and is required by
4806 IEEE Std 1003.1-2001.
4807 The smd shorthand for the showmode option was not present in all his‐
4809 torical implementations of the editor. IEEE Std 1003.1-2001 requires
4810 it, for consistency.
4811 Not all historical implementations of the editor displayed a mode
4813 string for command mode, differentiating command mode from text input
4814 mode by the absence of a mode string. IEEE Std 1003.1-2001 permits this
4815 behavior for consistency with historical practice, but implementations
4816 are encouraged to provide a display string for both modes.
4817 slowopen
4819 Historically the slowopen option was automatically set if the terminal
4820 baud rate was less than 1200 baud, or if the baud rate was 1200 baud
4821 and the redraw option was not set. The slowopen option had two effects.
4822 First, when inserting characters in the middle of a line, characters
4823 after the cursor would not be pushed ahead, but would appear to be
4824 overwritten. Second, when creating a new line of text, lines after the
4825 current line would not be scrolled down, but would appear to be over‐
4826 written. In both cases, ending text input mode would cause the screen
4827 to be refreshed to match the actual contents of the edit buffer.
4828 Finally, terminals that were sufficiently intelligent caused the editor
4829 to ignore the slowopen option. IEEE Std 1003.1-2001 permits most his‐
4830 torical behavior, extending historical practice to require slowopen
4831 behaviors if the edit option is set by the user.
4832 tags
4834 The default path for tags files is left unspecified as implementations
4835 may have their own tags implementations that do not correspond to the
4836 historical ones. The default tags option value should probably at least
4837 include the file ./tags.
4838 term
4840 Historical implementations of ex and vi ignored changes to the term
4841 edit option after the initial terminal information was loaded. This is
4842 permitted by IEEE Std 1003.1-2001; however, implementations are encour‐
4843 aged to permit the user to modify their terminal type at any time.
4844 terse
4846 Historically, the terse edit option optionally provided a shorter, less
4847 descriptive error message, for some error messages. This is permitted,
4848 but not required, by IEEE Std 1003.1-2001. Historically, most common
4849 visual mode errors (for example, trying to move the cursor past the end
4850 of a line) did not result in an error message, but simply alerted the
4851 terminal. Implementations wishing to provide messages for novice users
4852 are urged to do so based on the edit option verbose, and not terse.
4853 window
4855 In historical implementations, the default for the window edit option
4856 was based on the baud rate as follows:
4857 1. If the baud rate was less than 1200, the edit option w300 set the
4859 window value; for example, the line:
4860 set w300=12
4863 would set the window option to 12 if the baud rate was less than 1200.
4865 2. If the baud rate was equal to 1200, the edit option w1200 set the
4867 window value.
4868 3. If the baud rate was greater than 1200, the edit option w9600 set
4870 the window value.
4871 The w300, w1200, and w9600 options do not appear in
4873 IEEE Std 1003.1-2001 because of their dependence on specific baud
4874 rates.
4875 In historical implementations, the size of the window displayed by var‐
4877 ious commands was related to, but not necessarily the same as, the win‐
4878 dow edit option. For example, the size of the window was set by the ex
4879 command visual 10, but it did not change the value of the window edit
4880 option. However, changing the value of the window edit option did
4881 change the number of lines that were displayed when the screen was
4882 repainted. IEEE Std 1003.1-2001 does not permit this behavior in the
4883 interests of consistency and simplicity of specification, and requires
4884 that all commands that change the number of lines that are displayed do
4885 it by setting the value of the window edit option.
4886 wrapmargin, wm
4888 Historically, the wrapmargin option did not affect maps inserting char‐
4889 acters that also had associated counts; for example :map K 5aABC DEF.
4890 Unfortunately, there are widely used maps that depend on this behavior.
4891 For consistency and simplicity of specification, IEEE Std 1003.1-2001
4892 does not permit this behavior.
4893 Historically, wrapmargin was calculated using the column display width
4895 of all characters on the screen. For example, an implementation using
4896 "^I" to represent <tab>s when the list edit option was set, where '^'
4897 and 'I' each took up a single column on the screen, would calculate the
4898 wrapmargin based on a value of 2 for each <tab>. The number edit option
4899 similarly changed the effective length of the line as well.
4900 IEEE Std 1003.1-2001 requires conformance to historical practice.
4901
4903 None.
4904
4906 Command Search and Execution, ctags, ed, sed, sh, stty, vi, the System
4907 Interfaces volume of IEEE Std 1003.1-2001, access()
4908
4910 Portions of this text are reprinted and reproduced in electronic form
4911 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4912 -- Portable Operating System Interface (POSIX), The Open Group Base
4913 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
4914 Electrical and Electronics Engineers, Inc and The Open Group. In the
4915 event of any discrepancy between this version and the original IEEE and
4916 The Open Group Standard, the original IEEE and The Open Group Standard
4917 is the referee document. The original Standard can be obtained online
4918 at http://www.opengroup.org/unix/online.html .
4919IEEE/The Open Group 2003 EX(1P)