1EX(P) POSIX Programmer's Manual EX(P)
2
6 ex - text editor
7
9 ex [-rR][-s | -v][-c command][-t tagstring][-w size][file ...]
10
12 The ex utility is a line-oriented text editor. There are two other
13 modes of the editor-open and visual-in which screen-oriented editing is
14 available. This is described more fully by the ex open and visual com‐
15 mands and in vi .
16 This section uses the term edit buffer to describe the current working
18 text. No specific implementation is implied by this term. All editing
19 changes are performed on the edit buffer, and no changes to it shall
20 affect any file until an editor command writes the file.
21 Certain terminals do not have all the capabilities necessary to support
23 the complete ex definition, such as the full-screen editing commands (
24 visual mode or open mode). When these commands cannot be supported on
25 such terminals, this condition shall not produce an error message such
26 as "not an editor command" or report a syntax error. The implementation
27 may either accept the commands and produce results on the screen that
28 are the result of an unsuccessful attempt to meet the requirements of
29 this volume of IEEE Std 1003.1-2001 or report an error describing the
30 terminal-related deficiency.
31
33 The ex utility shall conform to the Base Definitions volume of
34 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
35 The following options shall be supported:
37 -c command
39 Specify an initial command to be executed in the first edit buf‐
40 fer loaded from an existing file (see the EXTENDED DESCRIPTION
41 section). Implementations may support more than a single -c
42 option. In such implementations, the specified commands shall be
43 executed in the order specified on the command line.
44 -r Recover the named files (see the EXTENDED DESCRIPTION section).
46 Recovery information for a file shall be saved during an editor
47 or system crash (for example, when the editor is terminated by a
48 signal which the editor can catch), or after the use of an ex
49 preserve command.
50 A crash in this context is an unexpected failure of the system or util‐
52 ity that requires restarting the failed system or utility. A system
53 crash implies that any utilities running at the time also crash. In the
54 case of an editor or system crash, the number of changes to the edit
55 buffer (since the most recent preserve command) that will be recovered
56 is unspecified.
57 If no file operands are given and the -t option is not specified, all
59 other options, the EXINIT variable, and any .exrc files shall be
60 ignored; a list of all recoverable files available to the invoking user
61 shall be written, and the editor shall exit normally without further
62 action.
63 -R Set readonly edit option.
65 -s Prepare ex for batch use by taking the following actions:
67 * Suppress writing prompts and informational (but not diagnos‐
69 tic) messages.
70 * Ignore the value of TERM and any implementation default ter‐
72 minal type and assume the terminal is a type incapable of
73 supporting open or visual modes; see the visual command and
74 the description of vi .
75 * Suppress the use of the EXINIT environment variable and the
77 reading of any .exrc file; see the EXTENDED DESCRIPTION sec‐
78 tion.
79 * Suppress autoindentation, ignoring the value of the autoin‐
81 dent edit option.
82 -t tagstring
84 Edit the file containing the specified tagstring; see ctags .
85 The tags feature represented by -t tagstring and the tag command
86 is optional. It shall be provided on any system that also pro‐
87 vides a conforming implementation of ctags; otherwise, the use
88 of -t produces undefined results. On any system, it shall be an
89 error to specify more than a single -t option.
90 -v Begin in visual mode (see vi ).
92 -w size
94 Set the value of the window editor option to size.
95
98 The following operand shall be supported:
99 file A pathname of a file to be edited.
101
104 The standard input consists of a series of commands and input text, as
105 described in the EXTENDED DESCRIPTION section. The implementation may
106 limit each line of standard input to a length of {LINE_MAX}.
107 If the standard input is not a terminal device, it shall be as if the
109 -s option had been specified.
110 If a read from the standard input returns an error, or if the editor
112 detects an end-of-file condition from the standard input, it shall be
113 equivalent to a SIGHUP asynchronous event.
114
116 Input files shall be text files or files that would be text files
117 except for an incomplete last line that is not longer than {LINE_MAX}-1
118 bytes in length and contains no NUL characters. By default, any incom‐
119 plete last line shall be treated as if it had a trailing <newline>. The
120 editing of other forms of files may optionally be allowed by ex imple‐
121 mentations.
122 The .exrc files and source files shall be text files consisting of ex
124 commands; see the EXTENDED DESCRIPTION section.
125 By default, the editor shall read lines from the files to be edited
127 without interpreting any of those lines as any form of editor command.
128
130 The following environment variables shall affect the execution of ex:
131 COLUMNS
133 Override the system-selected horizontal screen size. See the
134 Base Definitions volume of IEEE Std 1003.1-2001, Chapter 8,
135 Environment Variables for valid values and results when it is
136 unset or null.
137 EXINIT Determine a list of ex commands that are executed on editor
139 start-up. See the EXTENDED DESCRIPTION section for more details
140 of the initialization phase.
141 HOME Determine a pathname of a directory that shall be searched for
143 an editor start-up file named .exrc; see the EXTENDED DESCRIP‐
144 TION section.
145 LANG Provide a default value for the internationalization variables
147 that are unset or null. (See the Base Definitions volume of
148 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
149 ables for the precedence of internationalization variables used
150 to determine the values of locale categories.)
151 LC_ALL If set to a non-empty string value, override the values of all
153 the other internationalization variables.
154 LC_COLLATE
156 Determine the locale for the behavior of ranges, equivalence
158 classes, and multi-character collating elements within regular
159 expressions.
160 LC_CTYPE
162 Determine the locale for the interpretation of sequences of
163 bytes of text data as characters (for example, single-byte as
164 opposed to multi-byte characters in arguments and input files),
165 the behavior of character classes within regular expressions,
166 the classification of characters as uppercase or lowercase let‐
167 ters, the case conversion of letters, and the detection of word
168 boundaries.
169 LC_MESSAGES
171 Determine the locale that should be used to affect the format
172 and contents of diagnostic messages written to standard error.
173 LINES Override the system-selected vertical screen size, used as the
175 number of lines in a screenful and the vertical screen size in
176 visual mode. See the Base Definitions volume of
177 IEEE Std 1003.1-2001, Chapter 8, Environment Variables for valid
178 values and results when it is unset or null.
179 NLSPATH
181 Determine the location of message catalogs for the processing of
182 LC_MESSAGES .
183 PATH Determine the search path for the shell command specified in the
185 ex editor commands !, shell, read, and write, and the open and
186 visual mode command !; see the description of command search and
187 execution in Command Search and Execution .
188 SHELL Determine the preferred command line interpreter for use as the
190 default value of the shell edit option.
191 TERM Determine the name of the terminal type. If this variable is
193 unset or null, an unspecified default terminal type shall be
194 used.
195
198 The following term is used in this and following sections to specify
199 command and asynchronous event actions:
200 complete write
202 A complete write is a write of the entire contents of the edit
204 buffer to a file of a type other than a terminal device, or the
205 saving of the edit buffer caused by the user executing the ex
206 preserve command. Writing the contents of the edit buffer to a
207 temporary file that will be removed when the editor exits shall
208 not be considered a complete write.
209 The following actions shall be taken upon receipt of signals:
212 SIGINT If the standard input is not a terminal device, ex shall not
214 write the file or return to command or text input mode, and
215 shall exit with a non-zero exit status.
216 Otherwise, if executing an open or visual text input mode command, ex
218 in receipt of SIGINT shall behave identically to its receipt of the
219 <ESC> character.
220 Otherwise:
222 1. If executing an ex text input mode command, all input lines
224 that have been completely entered shall be resolved into the
225 edit buffer, and any partially entered line shall be dis‐
226 carded.
227 2. If there is a currently executing command, it shall be
229 aborted and a message displayed. Unless otherwise specified
230 by the ex or vi command descriptions, it is unspecified
231 whether any lines modified by the executing command appear
232 modified, or as they were before being modified by the exe‐
233 cuting command, in the buffer.
234 If the currently executing command was a motion command, its
236 associated command shall be discarded.
237 3. If in open or visual command mode, the terminal shall be
239 alerted.
240 4. The editor shall then return to command mode.
242 SIGCONT
244 The screen shall be refreshed if in open or visual mode.
245 SIGHUP If the edit buffer has been modified since the last complete
247 write, ex shall attempt to save the edit buffer so that it can
248 be recovered later using the -r option or the ex recover com‐
249 mand. The editor shall not write the file or return to command
250 or text input mode, and shall terminate with a non-zero exit
251 status.
252 SIGTERM
254 Refer to SIGHUP.
255 The action taken for all other signals is unspecified.
258
260 The standard output shall be used only for writing prompts to the user,
261 for informational messages, and for writing lines from the file.
262
264 The standard error shall be used only for diagnostic messages.
265
267 The output from ex shall be text files.
268
270 Only the ex mode of the editor is described in this section. See vi
271 for additional editing capabilities available in ex.
272 When an error occurs, ex shall write a message. If the terminal sup‐
274 ports a standout mode (such as inverse video), the message shall be
275 written in standout mode. If the terminal does not support a standout
276 mode, and the edit option errorbells is set, an alert action shall pre‐
277 cede the error message.
278 By default, ex shall start in command mode, which shall be indicated by
280 a : prompt; see the prompt command. Text input mode can be entered by
281 the append, insert, or change commands; it can be exited (and command
282 mode re-entered) by typing a period ( '.' ) alone at the beginning of a
283 line.
284 Initialization in ex and vi
286 The following symbols are used in this and following sections to spec‐
287 ify locations in the edit buffer:
288 alternate and current pathnames
290 Two pathnames, named current and alternate, are maintained by
292 the editor. Any ex commands that take filenames as arguments
293 shall set them as follows:
294 1. If a file argument is specified to the ex edit, ex, or
296 recover commands, or if an ex tag command replaces the con‐
297 tents of the edit buffer.
298 a. If the command replaces the contents of the edit buffer,
300 the current pathname shall be set to the file argument
301 or the file indicated by the tag, and the alternate
302 pathname shall be set to the previous value of the cur‐
303 rent pathname.
304 b. Otherwise, the alternate pathname shall be set to the
306 file argument.
307 2. If a file argument is specified to the ex next command:
309 a. If the command replaces the contents of the edit buffer,
311 the current pathname shall be set to the first file
312 argument, and the alternate pathname shall be set to the
313 previous value of the current pathname.
314 3. If a file argument is specified to the ex file command, the
316 current pathname shall be set to the file argument, and the
317 alternate pathname shall be set to the previous value of the
318 current pathname.
319 4. If a file argument is specified to the ex read and write
321 commands (that is, when reading or writing a file, and not
322 to the program named by the shell edit option), or a file
323 argument is specified to the ex xit command:
324 a. If the current pathname has no value, the current path‐
326 name shall be set to the file argument.
327 b. Otherwise, the alternate pathname shall be set to the
329 file argument.
330 If the alternate pathname is set to the previous value of the current
332 pathname when the current pathname had no previous value, then the
333 alternate pathname shall have no value as a result.
334 current line
336 The line of the edit buffer referenced by the cursor. Each com‐
338 mand description specifies the current line after the command
339 has been executed, as the current line value. When the edit buf‐
340 fer contains no lines, the current line shall be zero; see
341 Addressing in ex .
342 current column
344 The current display line column occupied by the cursor. (The
346 columns shall be numbered beginning at 1.) Each command descrip‐
347 tion specifies the current column after the command has been
348 executed, as the current column value. This column is an ideal
349 column that is remembered over the lifetime of the editor. The
350 actual display line column upon which the cursor rests may be
351 different from the current column; see the cursor positioning
352 discussion in Command Descriptions in vi .
353 set to non-<blank>
355 A description for a current column value, meaning that the cur‐
357 rent column shall be set to the last display line column on
358 which is displayed any part of the first non- <blank> of the
359 line. If the line has no non- <blank> non- <newline>s, the cur‐
360 rent column shall be set to the last display line column on
361 which is displayed any part of the last non- <newline> in the
362 line. If the line is empty, the current column shall be set to
363 column position 1.
364 The length of lines in the edit buffer may be limited to {LINE_MAX}
367 bytes. In open and visual mode, the length of lines in the edit buffer
368 may be limited to the number of characters that will fit in the dis‐
369 play. If either limit is exceeded during editing, an error message
370 shall be written. If either limit is exceeded by a line read in from a
371 file, an error message shall be written and the edit session may be
372 terminated.
373 If the editor stops running due to any reason other than a user com‐
375 mand, and the edit buffer has been modified since the last complete
376 write, it shall be equivalent to a SIGHUP asynchronous event. If the
377 system crashes, it shall be equivalent to a SIGHUP asynchronous event.
378 During initialization (before the first file is copied into the edit
380 buffer or any user commands from the terminal are processed) the fol‐
381 lowing shall occur:
382 1. If the environment variable EXINIT is set, the editor shall execute
384 the ex commands contained in that variable.
385 2. If the EXINIT variable is not set, and all of the following are
387 true:
388 a. The HOME environment variable is not null and not empty.
390 b. The file .exrc in the directory referred to by the HOME envi‐
392 ronment variable:
393 1. Exists
395 2. Is owned by the same user ID as the real user ID of the
397 process or the process has appropriate privileges
398 3. Is not writable by anyone other than the owner
400 the editor shall execute the ex commands contained in that file.
402 3. If and only if all of the following are true:
404 a. The current directory is not referred to by the HOME environ‐
406 ment variable.
407 b. A command in the EXINIT environment variable or a command in
409 the .exrc file in the directory referred to by the HOME envi‐
410 ronment variable sets the editor option exrc.
411 c. The .exrc file in the current directory:
413 1. Exists
415 2. Is owned by the same user ID as the real user ID of the
417 process, or by one of a set of implementation-defined user
418 IDs
419 3. Is not writable by anyone other than the owner
421 the editor shall attempt to execute the ex commands contained in that
423 file.
424 Lines in any .exrc file that are blank lines shall be ignored. If any
426 .exrc file exists, but is not read for ownership or permission reasons,
427 it shall be an error.
428 After the EXINIT variable and any .exrc files are processed, the first
430 file specified by the user shall be edited, as follows:
431 1. If the user specified the -t option, the effect shall be as if the
433 ex tag command was entered with the specified argument, with the
434 exception that if tag processing does not result in a file to edit,
435 the effect shall be as described in step 3. below.
436 2. Otherwise, if the user specified any command line file arguments,
438 the effect shall be as if the ex edit command was entered with the
439 first of those arguments as its file argument.
440 3. Otherwise, the effect shall be as if the ex edit command was
442 entered with a nonexistent filename as its file argument. It is
443 unspecified whether this action shall set the current pathname. In
444 an implementation where this action does not set the current path‐
445 name, any editor command using the current pathname shall fail
446 until an editor command sets the current pathname.
447 If the -r option was specified, the first time a file in the initial
449 argument list or a file specified by the -t option is edited, if recov‐
450 ery information has previously been saved about it, that information
451 shall be recovered and the editor shall behave as if the contents of
452 the edit buffer have already been modified. If there are multiple
453 instances of the file to be recovered, the one most recently saved
454 shall be recovered, and an informational message that there are previ‐
455 ous versions of the file that can be recovered shall be written. If no
456 recovery information about a file is available, an informational mes‐
457 sage to this effect shall be written, and the edit shall proceed as
458 usual.
459 If the -c option was specified, the first time a file that already
461 exists (including a file that might not exist but for which recovery
462 information is available, when the -r option is specified) replaces or
463 initializes the contents of the edit buffer, the current line shall be
464 set to the last line of the edit buffer, the current column shall be
465 set to non- <blank>, and the ex commands specified with the -c option
466 shall be executed. In this case, the current line and current column
467 shall not be set as described for the command associated with the
468 replacement or initialization of the edit buffer contents. However, if
469 the -t option or a tag command is associated with this action, the -c
470 option commands shall be executed and then the movement to the tag
471 shall be performed.
472 The current argument list shall initially be set to the filenames spec‐
474 ified by the user on the command line. If no filenames are specified by
475 the user, the current argument list shall be empty. If the -t option
476 was specified, it is unspecified whether any filename resulting from
477 tag processing shall be prepended to the current argument list. In the
478 case where the filename is added as a prefix to the current argument
479 list, the current argument list reference shall be set to that file‐
480 name. In the case where the filename is not added as a prefix to the
481 current argument list, the current argument list reference shall logi‐
482 cally be located before the first of the filenames specified on the
483 command line (for example, a subsequent ex next command shall edit the
484 first filename from the command line). If the -t option was not speci‐
485 fied, the current argument list reference shall be to the first of the
486 filenames on the command line.
487 Addressing in ex
489 Addressing in ex relates to the current line and the current column;
490 the address of a line is its 1-based line number, the address of a col‐
491 umn is its 1-based count from the beginning of the line. Generally, the
492 current line is the last line affected by a command. The current line
493 number is the address of the current line. In each command description,
494 the effect of the command on the current line number and the current
495 column is described.
496 Addresses are constructed as follows:
498 1. The character '.' (period) shall address the current line.
500 2. The character '$' shall address the last line of the edit buffer.
502 3. The positive decimal number n shall address the nth line of the
504 edit buffer.
505 4. The address "'x" refers to the line marked with the mark name char‐
507 acter 'x' , which shall be a lowercase letter from the portable
508 character set or one of the characters '`' or '" . It shall be an
509 error if the line that was marked is not currently present in the
510 edit buffer or the mark has not been set. Lines can be marked with
511 the ex mark or k commands, or the vi m command.
512 5. A regular expression enclosed by slashes ( '/' ) shall address the
514 first line found by searching forwards from the line following the
515 current line toward the end of the edit buffer and stopping at the
516 first line for which the line excluding the terminating <newline>
517 matches the regular expression. As stated in Regular Expressions in
518 ex , an address consisting of a null regular expression delimited
519 by slashes "//" shall address the next line for which the line
520 excluding the terminating <newline> matches the last regular
521 expression encountered. In addition, the second slash can be omit‐
522 ted at the end of a command line. If the wrapscan edit option is
523 set, the search shall wrap around to the beginning of the edit buf‐
524 fer and continue up to and including the current line, so that the
525 entire edit buffer is searched. Within the regular expression, the
526 sequence "\/" shall represent a literal slash instead of the regu‐
527 lar expression delimiter.
528 6. A regular expression enclosed in question marks ( '?' ) shall
530 address the first line found by searching backwards from the line
531 preceding the current line toward the beginning of the edit buffer
532 and stopping at the first line for which the line excluding the
533 terminating <newline> matches the regular expression. An address
534 consisting of a null regular expression delimited by question marks
535 "??" shall address the previous line for which the line excluding
536 the terminating <newline> matches the last regular expression
537 encountered. In addition, the second question mark can be omitted
538 at the end of a command line. If the wrapscan edit option is set,
539 the search shall wrap around from the beginning of the edit buffer
540 to the end of the edit buffer and continue up to and including the
541 current line, so that the entire edit buffer is searched. Within
542 the regular expression, the sequence "\?" shall represent a literal
543 question mark instead of the RE delimiter.
544 7. A plus sign ( '+' ) or a minus sign ( '-' ) followed by a decimal
546 number shall address the current line plus or minus the number. A
547 '+' or '-' not followed by a decimal number shall address the cur‐
548 rent line plus or minus 1.
549 Addresses can be followed by zero or more address offsets, optionally
551 <blank>-separated. Address offsets are constructed as follows:
552 1. A '+' or '-' immediately followed by a decimal number shall add
554 (subtract) the indicated number of lines to (from) the address. A
555 '+' or '-' not followed by a decimal number shall add (subtract) 1
556 to (from) the address.
557 2. A decimal number shall add the indicated number of lines to the
559 address.
560 It shall not be an error for an intermediate address value to be less
562 than zero or greater than the last line in the edit buffer. It shall be
563 an error for the final address value to be less than zero or greater
564 than the last line in the edit buffer.
565 Commands take zero, one, or two addresses; see the descriptions of
567 1addr and 2addr in Command Descriptions in ex . If more than the
568 required number of addresses are provided to a command that requires
569 zero addresses, it shall be an error. Otherwise, if more than the
570 required number of addresses are provided to a command, the addresses
571 specified first shall be evaluated and then discarded until the maximum
572 number of valid addresses remain.
573 Addresses shall be separated from each other by a comma ( ',' ) or a
575 semicolon ( ';' ). If no address is specified before or after a comma
576 or semicolon separator, it shall be as if the address of the current
577 line was specified before or after the separator. In the case of a
578 semicolon separator, the current line ( '.' ) shall be set to the first
579 address, and only then will the next address be calculated. This fea‐
580 ture can be used to determine the starting line for forwards and back‐
581 wards searches (see rules 5. and 6.).
582 A percent sign ( '%' ) shall be equivalent to entering the two
584 addresses "1,$" .
585 Any delimiting <blank>s between addresses, address separators, or
587 address offsets shall be discarded.
588 Command Line Parsing in ex
590 The following symbol is used in this and following sections to describe
591 parsing behavior:
592 escape If a character is referred to as "backslash-escaped" or " <con‐
594 trol>-V-escaped," it shall mean that the character acquired or
595 lost a special meaning by virtue of being preceded, respec‐
596 tively, by a backslash or <control>-V character. Unless other‐
597 wise specified, the escaping character shall be discarded at
598 that time and shall not be further considered for any purpose.
599 Command-line parsing shall be done in the following steps. For each
602 step, characters already evaluated shall be ignored; that is, the
603 phrase "leading character" refers to the next character that has not
604 yet been evaluated.
605 1. Leading colon characters shall be skipped.
607 2. Leading <blank>s shall be skipped.
609 3. If the leading character is a double-quote character, the charac‐
611 ters up to and including the next non-backslash-escaped <newline>
612 shall be discarded, and any subsequent characters shall be parsed
613 as a separate command.
614 4. Leading characters that can be interpreted as addresses shall be
616 evaluated; see Addressing in ex .
617 5. Leading <blank>s shall be skipped.
619 6. If the next character is a vertical-line character or a <newline>:
621 a. If the next character is a <newline>:
623 1. If ex is in open or visual mode, the current line shall be
625 set to the last address specified, if any.
626 2. Otherwise, if the last command was terminated by a verti‐
628 cal-line character, no action shall be taken; for example,
629 the command "||<newline>" shall execute two implied com‐
630 mands, not three.
631 3. Otherwise, step 6.b. shall apply.
633 b. Otherwise, the implied command shall be the print command. The
635 last #, p, and l flags specified to any ex command shall be
636 remembered and shall apply to this implied command. Executing
637 the ex number, print, or list command shall set the remembered
638 flags to #, nothing, and l, respectively, plus any other flags
639 specified for that execution of the number, print, or list com‐
640 mand.
641 If ex is not currently performing a global or v command, and no
643 address or count is specified, the current line shall be incre‐
644 mented by 1 before the command is executed. If incrementing the
645 current line would result in an address past the last line in the
646 edit buffer, the command shall fail, and the increment shall not
647 happen.
648 c. The <newline> or vertical-line character shall be discarded and
650 any subsequent characters shall be parsed as a separate com‐
651 mand.
652 7. The command name shall be comprised of the next character (if the
654 character is not alphabetic), or the next character and any subse‐
655 quent alphabetic characters (if the character is alphabetic), with
656 the following exceptions:
657 a. Commands that consist of any prefix of the characters in the
659 command name delete, followed immediately by any of the charac‐
660 ters 'l' , 'p' , '+' , '-' , or '#' shall be interpreted as a
661 delete command, followed by a <blank>, followed by the charac‐
662 ters that were not part of the prefix of the delete command.
663 The maximum number of characters shall be matched to the com‐
664 mand name delete; for example, "del" shall not be treated as
665 "de" followed by the flag l.
666 b. Commands that consist of the character 'k' , followed by a
668 character that can be used as the name of a mark, shall be
669 equivalent to the mark command followed by a <blank>, followed
670 by the character that followed the 'k' .
671 c. Commands that consist of the character 's' , followed by char‐
673 acters that could be interpreted as valid options to the s com‐
674 mand, shall be the equivalent of the s command, without any
675 pattern or replacement values, followed by a <blank>, followed
676 by the characters after the 's' .
677 8. The command name shall be matched against the possible command
679 names, and a command name that contains a prefix matching the char‐
680 acters specified by the user shall be the executed command. In the
681 case of commands where the characters specified by the user could
682 be ambiguous, the executed command shall be as follows:
683 a append n next t t
685 c change p print u undo
686 ch change pr print un undo
688 e edit r read v v
689 m move re read w write
690 ma mark s s
691 Implementation extensions with names causing similar ambiguities shall
693 not be checked for a match until all possible matches for commands
694 specified by IEEE Std 1003.1-2001 have been checked.
695 9. If the command is a ! command, or if the command is a read command
697 followed by zero or more <blank>s and a !, or if the command is a
698 write command followed by one or more <blank>s and a !, the rest of
699 the command shall include all characters up to a non-backslash-
700 escaped <newline>. The <newline> shall be discarded and any subse‐
701 quent characters shall be parsed as a separate ex command.
702 10. Otherwise, if the command is an edit, ex, or next command, or a
704 visual command while in open or visual mode, the next part of the
705 command shall be parsed as follows:
706 a. Any '!' character immediately following the command shall be
708 skipped and be part of the command.
709 b. Any leading <blank>s shall be skipped and be part of the com‐
711 mand.
712 c. If the next character is a '+' , characters up to the first
714 non-backslash-escaped <newline> or non-backslash-escaped
715 <blank> shall be skipped and be part of the command.
716 d. The rest of the command shall be determined by the steps speci‐
718 fied in paragraph 12.
719 11. Otherwise, if the command is a global, open, s, or v command, the
721 next part of the command shall be parsed as follows:
722 a. Any leading <blank>s shall be skipped and be part of the com‐
724 mand.
725 b. If the next character is not an alphanumeric, double-quote,
727 <newline>, backslash, or vertical-line character:
728 1. The next character shall be used as a command delimiter.
730 2. If the command is a global, open, or v command, characters
732 up to the first non-backslash-escaped <newline>, or first
733 non-backslash-escaped delimiter character, shall be skipped
734 and be part of the command.
735 3. If the command is an s command, characters up to the first
737 non-backslash-escaped <newline>, or second non-backslash-
738 escaped delimiter character, shall be skipped and be part
739 of the command.
740 c. If the command is a global or v command, characters up to the
742 first non-backslash-escaped <newline> shall be skipped and be
743 part of the command.
744 d. Otherwise, the rest of the command shall be determined by the
746 steps specified in paragraph 12.
747 12. Otherwise:
749 a. If the command was a map, unmap, abbreviate, or unabbreviate
751 command, characters up to the first non- <control>-V-escaped
752 <newline>, vertical-line, or double-quote character shall be
753 skipped and be part of the command.
754 b. Otherwise, characters up to the first non-backslash-escaped
756 <newline>, vertical-line, or double-quote character shall be
757 skipped and be part of the command.
758 c. If the command was an append, change, or insert command, and
760 the step 12.b. ended at a vertical-line character, any subse‐
761 quent characters, up to the next non-backslash-escaped <new‐
762 line> shall be used as input text to the command.
763 d. If the command was ended by a double-quote character, all sub‐
765 sequent characters, up to the next non-backslash-escaped <new‐
766 line>, shall be discarded.
767 e. The terminating <newline> or vertical-line character shall be
769 discarded and any subsequent characters shall be parsed as a
770 separate ex command.
771 Command arguments shall be parsed as described by the Synopsis and
773 Description of each individual ex command. This parsing shall not be
774 <blank>-sensitive, except for the ! argument, which must follow the
775 command name without intervening <blank>s, and where it would otherwise
776 be ambiguous. For example, count and flag arguments need not be
777 <blank>-separated because "d22p" is not ambiguous, but file arguments
778 to the ex next command must be separated by one or more <blank>s. Any
779 <blank> in command arguments for the abbreviate, unabbreviate, map, and
780 unmap commands can be <control>-V-escaped, in which case the <blank>
781 shall not be used as an argument delimiter. Any <blank> in the command
782 argument for any other command can be backslash-escaped, in which case
783 that <blank> shall not be used as an argument delimiter.
784 Within command arguments for the abbreviate, unabbreviate, map, and
786 unmap commands, any character can be <control>-V-escaped. All such
787 escaped characters shall be treated literally and shall have no special
788 meaning. Within command arguments for all other ex commands that are
789 not regular expressions or replacement strings, any character that
790 would otherwise have a special meaning can be backslash-escaped.
791 Escaped characters shall be treated literally, without special meaning
792 as shell expansion characters or '!' , '%' , and '#' expansion charac‐
793 ters. See Regular Expressions in ex and Replacement Strings in ex for
794 descriptions of command arguments that are regular expressions or
795 replacement strings.
796 Non-backslash-escaped '%' characters appearing in file arguments to any
798 ex command shall be replaced by the current pathname; unescaped '#'
799 characters shall be replaced by the alternate pathname. It shall be an
800 error if '%' or '#' characters appear unescaped in an argument and
801 their corresponding values are not set.
802 Non-backslash-escaped '!' characters in the arguments to either the ex
804 ! command or the open and visual mode ! command, or in the arguments to
805 the ex read command, where the first non- <blank> after the command
806 name is a '!' character, or in the arguments to the ex write command
807 where the command name is followed by one or more <blank>s and the
808 first non- <blank> after the command name is a '!' character, shall be
809 replaced with the arguments to the last of those three commands as they
810 appeared after all unescaped '%' , '#' , and '!' characters were
811 replaced. It shall be an error if '!' characters appear unescaped in
812 one of these commands and there has been no previous execution of one
813 of these commands.
814 If an error occurs during the parsing or execution of an ex command:
816 * An informational message to this effect shall be written. Execution
818 of the ex command shall stop, and the cursor (for example, the cur‐
819 rent line and column) shall not be further modified.
820 * If the ex command resulted from a map expansion, all characters from
822 that map expansion shall be discarded, except as otherwise specified
823 by the map command.
824 * Otherwise, if the ex command resulted from the processing of an
826 EXINIT environment variable, a .exrc file, a :source command, a -c
827 option, or a + command specified to an ex edit, ex, next, or visual
828 command, no further commands from the source of the commands shall
829 be executed.
830 * Otherwise, if the ex command resulted from the execution of a buffer
832 or a global or v command, no further commands caused by the execu‐
833 tion of the buffer or the global or v command shall be executed.
834 * Otherwise, if the ex command was not terminated by a <newline>, all
836 characters up to and including the next non-backslash-escaped <new‐
837 line> shall be discarded.
838 Input Editing in ex
840 The following symbol is used in this and the following sections to
841 specify command actions:
842 word In the POSIX locale, a word consists of a maximal sequence of
844 letters, digits, and underscores, delimited at both ends by
845 characters other than letters, digits, or underscores, or by the
846 beginning or end of a line or the edit buffer.
847 When accepting input characters from the user, in either ex command
850 mode or ex text input mode, ex shall enable canonical mode input pro‐
851 cessing, as defined in the System Interfaces volume of
852 IEEE Std 1003.1-2001.
853 If in ex text input mode:
855 1. If the number edit option is set, ex shall prompt for input using
857 the line number that would be assigned to the line if it is
858 entered, in the format specified for the ex number command.
859 2. If the autoindent edit option is set, ex shall prompt for input
861 using autoindent characters, as described by the autoindent edit
862 option. autoindent characters shall follow the line number, if any.
863 If in ex command mode:
865 1. If the prompt edit option is set, input shall be prompted for using
867 a single ':' character; otherwise, there shall be no prompt.
868 The input characters in the following sections shall have the following
870 effects on the input line.
871 Scroll
873 Synopsis:
874 eof
877 See the description of the stty eof character in stty .
880 If in ex command mode: If the eof character is the first character
882 entered on the line, the line shall be evaluated as if it contained two
883 characters: a <control>-D and a <newline>.
884 Otherwise, the eof character shall have no special meaning.
886 If in ex text input mode: If the cursor follows an autoindent charac‐
889 ter, the autoindent characters in the line shall be modified so that a
890 part of the next text input character will be displayed on the first
891 column in the line after the previous shiftwidth edit option column
892 boundary, and the user shall be prompted again for input for the same
893 line.
894 Otherwise, if the cursor follows a '0' , which follows an autoindent
896 character, and the '0' was the previous text input character, the '0'
897 and all autoindent characters in the line shall be discarded, and the
898 user shall be prompted again for input for the same line.
899 Otherwise, if the cursor follows a '^' , which follows an autoindent
901 character, and the '^' was the previous text input character, the '^'
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. In addition,
904 the autoindent level for the next input line shall be derived from the
905 same line from which the autoindent level for the current input line
906 was derived.
907 Otherwise, if there are no autoindent or text input characters in the
909 line, the eof character shall be discarded.
910 Otherwise, the eof character shall have no special meaning.
912 <newline>
914 Synopsis:
915 <newline>
918 <control>-J
921 If in ex command mode: Cause the command line to be parsed; <control>-J
924 shall be mapped to the <newline> for this purpose.
925 If in ex text input mode: Terminate the current line. If there are no
927 characters other than autoindent characters on the line, all characters
928 on the line shall be discarded.
929 Prompt for text input on a new line after the current line. If the
931 autoindent edit option is set, an appropriate number of autoindent
932 characters shall be added as a prefix to the line as described by the
933 ex autoindent edit option.
934 <backslash>
936 Synopsis:
937 <backslash>
940 Allow the entry of a subsequent <newline> or <control>-J as a literal
943 character, removing any special meaning that it may have to the editor
944 during text input mode. The backslash character shall be retained and
945 evaluated when the command line is parsed, or retained and included
946 when the input text becomes part of the edit buffer.
947 <control>-V
949 Synopsis:
950 <control>-V
953 Allow the entry of any subsequent character as a literal character,
956 removing any special meaning that it may have to the editor during text
957 input mode. The <control>-V character shall be discarded before the
958 command line is parsed or the input text becomes part of the edit buf‐
959 fer.
960 If the "literal next" functionality is performed by the underlying sys‐
962 tem, it is implementation-defined whether a character other than <con‐
963 trol>-V performs this function.
964 <control>-W
966 Synopsis:
967 <control>-W
970 Discard the <control>-W, and the word previous to it in the input line,
973 including any <blank>s following the word and preceding the <con‐
974 trol>-W. If the "word erase" functionality is performed by the underly‐
975 ing system, it is implementation-defined whether a character other than
976 <control>-W performs this function.
977 Command Descriptions in ex
979 The following symbols are used in this section to represent command
980 modifiers. Some of these modifiers can be omitted, in which case the
981 specified defaults shall be used.
982 1addr A single line address, given in any of the forms described in
984 Addressing in ex ; the default shall be the current line ( '.'
985 ), unless otherwise specified.
986 If the line address is zero, it shall be an error, unless otherwise
988 specified in the following command descriptions.
989 If the edit buffer is empty, and the address is specified with a com‐
991 mand other than =, append, insert, open, put, read, or visual, or the
992 address is not zero, it shall be an error.
993 2addr Two addresses specifying an inclusive range of lines. If no
995 addresses are specified, the default for 2addr shall be the cur‐
996 rent line only ( ".,." ), unless otherwise specified in the fol‐
997 lowing command descriptions. If one address is specified, 2addr
998 shall specify that line only, unless otherwise specified in the
999 following command descriptions.
1000 It shall be an error if the first address is greater than the second
1002 address.
1003 If the edit buffer is empty, and the two addresses are specified with a
1005 command other than the !, write, wq, or xit commands, or either address
1006 is not zero, it shall be an error.
1007 count A positive decimal number. If count is specified, it shall be
1009 equivalent to specifying an additional address to the command,
1010 unless otherwise specified by the following command descrip‐
1011 tions. The additional address shall be equal to the last
1012 address specified to the command (either explicitly or by
1013 default) plus count-1.
1014 If this would result in an address greater than the last line of the
1016 edit buffer, it shall be corrected to equal the last line of the edit
1017 buffer.
1018 flags One or more of the characters '+' , '-' , '#' , 'p' , or 'l'
1020 (ell). The flag characters can be <blank>-separated, and in any
1021 order or combination. The characters '#' , 'p' , and 'l' shall
1022 cause lines to be written in the format specified by the print
1023 command with the specified flags.
1024 The lines to be written are as follows:
1026 1. All edit buffer lines written during the execution of the ex
1028 &, ~, list, number, open, print, s, visual, and z commands
1029 shall be written as specified by flags.
1030 2. After the completion of an ex command with a flag as an
1032 argument, the current line shall be written as specified by
1033 flags, unless the current line was the last line written by
1034 the command.
1035 The characters '+' and '-' cause the value of the current line after
1037 the execution of the ex command to be adjusted by the offset address as
1038 described in Addressing in ex . This adjustment shall occur before the
1039 current line is written as described in 2. above.
1040 The default for flags shall be none.
1042 buffer One of a number of named areas for holding text. The named buf‐
1044 fers are specified by the alphanumeric characters of the POSIX
1045 locale. There shall also be one "unnamed" buffer. When no buffer
1046 is specified for editor commands that use a buffer, the unnamed
1047 buffer shall be used. Commands that store text into buffers
1048 shall store the text as it was before the command took effect,
1049 and shall store text occurring earlier in the file before text
1050 occurring later in the file, regardless of how the text region
1051 was specified. Commands that store text into buffers shall store
1052 the text into the unnamed buffer as well as any specified buf‐
1053 fer.
1054 In ex commands, buffer names are specified as the name by itself. In
1056 open or visual mode commands the name is preceded by a double quote ( '
1057 )' character.
1058 If the specified buffer name is an uppercase character, and the buffer
1060 contents are to be modified, the buffer shall be appended to rather
1061 than being overwritten. If the buffer is not being modified, specifying
1062 the buffer name in lowercase and uppercase shall have identical
1063 results.
1064 There shall also be buffers named by the numbers 1 through 9. In open
1066 and visual mode, if a region of text including characters from more
1067 than a single line is being modified by the vi c or d commands, the
1068 motion character associated with the c or d commands specifies that the
1069 buffer text shall be in line mode, or the commands %, `, /, ?, (, ), N,
1070 n, {, or } are used to define a region of text for the c or d commands,
1071 the contents of buffers 1 through 8 shall be moved into the buffer
1072 named by the next numerically greater value, the contents of buffer 9
1073 shall be discarded, and the region of text shall be copied into buffer
1074 1. This shall be in addition to copying the text into a user-specified
1075 buffer or unnamed buffer, or both. Numeric buffers can be specified as
1076 a source buffer for open and visual mode commands; however, specifying
1077 a numeric buffer as the write target of an open or visual mode command
1078 shall have unspecified results.
1079 The text of each buffer shall have the characteristic of being in
1081 either line or character mode. Appending text to a non-empty buffer
1082 shall set the mode to match the characteristic of the text being
1083 appended. Appending text to a buffer shall cause the creation of at
1084 least one additional line in the buffer. All text stored into buffers
1085 by ex commands shall be in line mode. The ex commands that use buffers
1086 as the source of text specify individually how buffers of different
1087 modes are handled. Each open or visual mode command that uses buffers
1088 for any purpose specifies individually the mode of the text stored into
1089 the buffer and how buffers of different modes are handled.
1090 file Command text used to derive a pathname. The default shall be the
1092 current pathname, as defined previously, in which case, if no
1093 current pathname has yet been established it shall be an error,
1094 except where specifically noted in the individual command
1095 descriptions that follow. If the command text contains any of
1096 the characters '~' , '{' , '[' , '*' , '?' , '$' , '`' , '" , '
1097 ,' and '\' , it shall be subjected to the process of "shell
1098 expansions", as described below; if more than a single pathname
1099 results and the command expects only one, it shall be an error.
1100 The process of shell expansions in the editor shall be done as follows.
1102 The ex utility shall pass two arguments to the program named by the
1103 shell edit option; the first shall be -c, and the second shall be the
1104 string "echo" and the command text as a single argument. The standard
1105 output and standard error of that command shall replace the command
1106 text.
1107 ! A character that can be appended to the command name to modify
1109 its operation, as detailed in the individual command descrip‐
1110 tions. With the exception of the ex read, write, and ! commands,
1111 the '!' character shall only act as a modifier if there are no
1112 <blank>s between it and the command name.
1113 remembered search direction
1115 The vi commands N and n begin searching in a forwards or back‐
1117 wards direction in the edit buffer based on a remembered search
1118 direction, which is initially unset, and is set by the ex
1119 global, v, s, and tag commands, and the vi / and ? commands.
1120 Abbreviate
1123 Synopsis:
1124 ab[breviate][lhs rhs]
1127 If lhs and rhs are not specified, write the current list of abbrevia‐
1130 tions and do nothing more.
1131 Implementations may restrict the set of characters accepted in lhs or
1133 rh, except that printable characters and <blank>s shall not be
1134 restricted. Additional restrictions shall be implementation-defined.
1135 In both lhs and rhs, any character may be escaped with a <control>-V,
1137 in which case the character shall not be used to delimit lhs from rhs,
1138 and the escaping <control>-V shall be discarded.
1139 In open and visual text input mode, if a non-word or <ESC> character
1141 that is not escaped by a <control>-V character is entered after a word
1142 character, a check shall be made for a set of characters matching lhs,
1143 in the text input entered during this command. If it is found, the
1144 effect shall be as if rhs was entered instead of lhs.
1145 The set of characters that are checked is defined as follows:
1147 1. If there are no characters inserted before the word and non-word or
1149 <ESC> characters that triggered the check, the set of characters
1150 shall consist of the word character.
1151 2. If the character inserted before the word and non-word or <ESC>
1153 characters that triggered the check is a word character, the set of
1154 characters shall consist of the characters inserted immediately
1155 before the triggering characters that are word characters, plus the
1156 triggering word character.
1157 3. If the character inserted before the word and non-word or <ESC>
1159 characters that triggered the check is not a word character, the
1160 set of characters shall consist of the characters that were
1161 inserted before the triggering characters that are neither <blank>s
1162 nor word characters, plus the triggering word character.
1163 It is unspecified whether the lhs argument entered for the ex abbrevi‐
1165 ate and unabbreviate commands is replaced in this fashion. Regardless
1166 of whether or not the replacement occurs, the effect of the command
1167 shall be as if the replacement had not occurred.
1168 Current line: Unchanged.
1170 Current column: Unchanged.
1172 Append
1174 Synopsis:
1175 [1addr] a[ppend][!]
1178 Enter ex text input mode; the input text shall be placed after the
1181 specified line. If line zero is specified, the text shall be placed at
1182 the beginning of the edit buffer.
1183 This command shall be affected by the number and autoindent edit
1185 options; following the command name with '!' shall cause the autoindent
1186 edit option setting to be toggled for the duration of this command
1187 only.
1188 Current line: Set to the last input line; if no lines were input, set
1190 to the specified line, or to the first line of the edit buffer if a
1191 line of zero was specified, or zero if the edit buffer is empty.
1192 Current column: Set to non- <blank>.
1194 Arguments
1196 Synopsis:
1197 ar[gs]
1200 Write the current argument list, with the current argument-list entry,
1203 if any, between '[' and ']' characters.
1204 Current line: Unchanged.
1206 Current column: Unchanged.
1208 Change
1210 Synopsis:
1211 [2addr] c[hange][!][count]
1214 Enter ex text input mode; the input text shall replace the specified
1217 lines. The specified lines shall be copied into the unnamed buffer,
1218 which shall become a line mode buffer.
1219 This command shall be affected by the number and autoindent edit
1221 options; following the command name with '!' shall cause the autoindent
1222 edit option setting to be toggled for the duration of this command
1223 only.
1224 Current line: Set to the last input line; if no lines were input, set
1226 to the line before the first address, or to the first line of the edit
1227 buffer if there are no lines preceding the first address, or to zero if
1228 the edit buffer is empty.
1229 Current column: Set to non- <blank>.
1231 Change Directory
1233 Synopsis:
1234 chd[ir][!][directory]cd[!][directory]
1237 Change the current working directory to directory.
1240 If no directory argument is specified, and the HOME environment vari‐
1242 able is set to a non-null and non-empty value, directory shall default
1243 to the value named in the HOME environment variable. If the HOME envi‐
1244 ronment variable is empty or is undefined, the default value of direc‐
1245 tory is implementation-defined.
1246 If no '!' is appended to the command name, and the edit buffer has been
1248 modified since the last complete write, and the current pathname does
1249 not begin with a '/' , it shall be an error.
1250 Current line: Unchanged.
1252 Current column: Unchanged.
1254 Copy
1256 Synopsis:
1257 [2addr] co[py] 1addr [flags]
1260 [2addr] t 1addr [flags]
1261 Copy the specified lines after the specified destination line; line
1264 zero specifies that the lines shall be placed at the beginning of the
1265 edit buffer.
1266 Current line: Set to the last line copied.
1268 Current column: Set to non- <blank>.
1270 Delete
1272 Synopsis:
1273 [2addr] d[elete][buffer][count][flags]
1276 Delete the specified lines into a buffer (defaulting to the unnamed
1279 buffer), which shall become a line-mode buffer.
1280 Flags can immediately follow the command name; see Command Line Parsing
1282 in ex .
1283 Current line: Set to the line following the deleted lines, or to the
1285 last line in the edit buffer if that line is past the end of the edit
1286 buffer, or to zero if the edit buffer is empty.
1287 Current column: Set to non- <blank>.
1289 Edit
1291 Synopsis:
1292 e[dit][!][+command][file]ex[!][+command][file]
1295 If no '!' is appended to the command name, and the edit buffer has been
1298 modified since the last complete write, it shall be an error.
1299 If file is specified, replace the current contents of the edit buffer
1301 with the current contents of file, and set the current pathname to
1302 file. If file is not specified, replace the current contents of the
1303 edit buffer with the current contents of the file named by the current
1304 pathname. If for any reason the current contents of the file cannot be
1305 accessed, the edit buffer shall be empty.
1306 The + command option shall be <blank>-delimited; <blank>s within + com‐
1308 mand can be escaped by preceding them with a backslash character. The +
1309 command shall be interpreted as an ex command immediately after the
1310 contents of the edit buffer have been replaced and the current line and
1311 column have been set.
1312 If the edit buffer is empty:
1314 Current line: Set to 0.
1316 Current column: Set to 1.
1318 Otherwise, if executed while in ex command mode or if the + command
1320 argument is specified:
1321 Current line: Set to the last line of the edit buffer.
1323 Current column: Set to non- <blank>.
1325 Otherwise, if file is omitted or results in the current pathname:
1327 Current line: Set to the first line of the edit buffer.
1329 Current column: Set to non- <blank>.
1331 Otherwise, if file is the same as the last file edited, the line and
1333 column shall be set as follows; if the file was previously edited, the
1334 line and column may be set as follows:
1335 Current line: Set to the last value held when that file was last
1337 edited. If this value is not a valid line in the new edit buffer, set
1338 to the first line of the edit buffer.
1339 Current column: If the current line was set to the last value held when
1341 the file was last edited, set to the last value held when the file was
1342 last edited. Otherwise, or if the last value is not a valid column in
1343 the new edit buffer, set to non- <blank>.
1344 Otherwise:
1346 Current line: Set to the first line of the edit buffer.
1348 Current column: Set to non- <blank>.
1350 File
1352 Synopsis:
1353 f[ile][file]
1356 If a file argument is specified, the alternate pathname shall be set to
1359 the current pathname, and the current pathname shall be set to file.
1360 Write an informational message. If the file has a current pathname, it
1362 shall be included in this message; otherwise, the message shall indi‐
1363 cate that there is no current pathname. If the edit buffer contains
1364 lines, the current line number and the number of lines in the edit buf‐
1365 fer shall be included in this message; otherwise, the message shall
1366 indicate that the edit buffer is empty. If the edit buffer has been
1367 modified since the last complete write, this fact shall be included in
1368 this message. If the readonly edit option is set, this fact shall be
1369 included in this message. The message may contain other unspecified
1370 information.
1371 Current line: Unchanged.
1373 Current column: Unchanged.
1375 Global
1377 Synopsis:
1378 [2addr] g[lobal] /pattern/ [commands]
1381 [2addr] v /pattern/ [commands]
1382 The optional '!' character after the global command shall be the same
1385 as executing the v command.
1386 If pattern is empty (for example, "//" ) or not specified, the last
1388 regular expression used in the editor command shall be used as the pat‐
1389 tern. The pattern can be delimited by slashes (shown in the Synopsis),
1390 as well as any non-alphanumeric or non- <blank> other than backslash,
1391 vertical line, double quote, or <newline>.
1392 If no lines are specified, the lines shall default to the entire file.
1394 The global and v commands are logically two-pass operations. First,
1396 mark the lines within the specified lines for which the line excluding
1397 the terminating <newline> matches ( global) or does not match ( v or
1398 global!) the specified pattern. Second, execute the ex commands given
1399 by commands, with the current line ( '.' ) set to each marked line. If
1400 an error occurs during this process, or the contents of the edit buffer
1401 are replaced (for example, by the ex :edit command) an error message
1402 shall be written and no more commands resulting from the execution of
1403 this command shall be processed.
1404 Multiple ex commands can be specified by entering multiple commands on
1406 a single line using a vertical line to delimit them, or one per line,
1407 by escaping each <newline> with a backslash.
1408 If no commands are specified:
1410 1. If in ex command mode, it shall be as if the print command were
1412 specified.
1413 2. Otherwise, no command shall be executed.
1415 For the append, change, and insert commands, the input text shall be
1417 included as part of the command, and the terminating period can be
1418 omitted if the command ends the list of commands. The open and visual
1419 commands can be specified as one of the commands, in which case each
1420 marked line shall cause the editor to enter open or visual mode. If
1421 open or visual mode is exited using the vi Q command, the current line
1422 shall be set to the next marked line, and open or visual mode reen‐
1423 tered, until the list of marked lines is exhausted.
1424 The global, v, and undo commands cannot be used in commands. Marked
1426 lines may be deleted by commands executed for lines occurring earlier
1427 in the file than the marked lines. In this case, no commands shall be
1428 executed for the deleted lines.
1429 If the remembered search direction is not set, the global and v com‐
1431 mands shall set it to forward.
1432 The autoprint and autoindent edit options shall be inhibited for the
1434 duration of the g or v command.
1435 Current line: If no commands executed, set to the last marked line.
1437 Otherwise, as specified for the executed ex commands.
1438 Current column: If no commands are executed, set to non- <blank>; oth‐
1440 erwise, as specified for the individual ex commands.
1441 Insert
1443 Synopsis:
1444 [1addr] i[nsert][!]
1447 Enter ex text input mode; the input text shall be placed before the
1450 specified line. If the line is zero or 1, the text shall be placed at
1451 the beginning of the edit buffer.
1452 This command shall be affected by the number and autoindent edit
1454 options; following the command name with '!' shall cause the autoindent
1455 edit option setting to be toggled for the duration of this command
1456 only.
1457 Current line: Set to the last input line; if no lines were input, set
1459 to the line before the specified line, or to the first line of the edit
1460 buffer if there are no lines preceding the specified line, or zero if
1461 the edit buffer is empty.
1462 Current column: Set to non- <blank>.
1464 Join
1466 Synopsis:
1467 [2addr] j[oin][!][count][flags]
1470 If count is specified: If no address was specified, the join command
1473 shall behave as if 2addr were the current line and the current line
1474 plus count (.,. + count).
1475 If one address was specified, the join command shall behave as if 2addr
1477 were the specified address and the specified address plus count ( addr,
1478 addr + count).
1479 If two addresses were specified, the join command shall behave as if an
1481 additional address, equal to the last address plus count -1 ( addr1,
1482 addr2, addr2 + count -1), was specified.
1483 If this would result in a second address greater than the last line of
1485 the edit buffer, it shall be corrected to be equal to the last line of
1486 the edit buffer.
1487 If no count is specified: If no address was specified, the join command
1489 shall behave as if 2addr were the current line and the next line (.,.
1490 +1).
1491 If one address was specified, the join command shall behave as if 2addr
1493 were the specified address and the next line ( addr, addr +1).
1494 Join the text from the specified lines together into a single line,
1496 which shall replace the specified lines.
1497 If a '!' character is appended to the command name, the join shall be
1499 without modification of any line, independent of the current locale.
1500 Otherwise, in the POSIX locale, set the current line to the first of
1502 the specified lines, and then, for each subsequent line, proceed as
1503 follows:
1504 1. Discard leading <space>s from the line to be joined.
1506 2. If the line to be joined is now empty, delete it, and skip steps 3
1508 through 5.
1509 3. If the current line ends in a <blank>, or the first character of
1511 the line to be joined is a ')' character, join the lines without
1512 further modification.
1513 4. If the last character of the current line is a '.' , join the lines
1515 with two <space>s between them.
1516 5. Otherwise, join the lines with a single <space> between them.
1518 Current line: Set to the first line specified.
1520 Current column: Set to non- <blank>.
1522 List
1524 Synopsis:
1525 [2addr] l[ist][count][flags]
1528 This command shall be equivalent to the ex command:
1531 [2addr] p[rint][count] l[flags]
1534 See Print .
1536 Map
1538 Synopsis:
1539 map[!][lhs rhs]
1542 If lhs and rhs are not specified:
1545 1. If '!' is specified, write the current list of text input mode
1547 maps.
1548 2. Otherwise, write the current list of command mode maps.
1550 3. Do nothing more.
1552 Implementations may restrict the set of characters accepted in lhs or
1554 rhs, except that printable characters and <blank>s shall not be
1555 restricted. Additional restrictions shall be implementation-defined. In
1556 both lhs and rhs, any character can be escaped with a <control>-V, in
1557 which case the character shall not be used to delimit lhs from rhs, and
1558 the escaping <control>-V shall be discarded.
1559 If the character '!' is appended to the map command name, the mapping
1561 shall be effective during open or visual text input mode rather than
1562 open or visual command mode. This allows lhs to have two different map
1563 definitions at the same time: one for command mode and one for text
1564 input mode.
1565 For command mode mappings: When the lhs is entered as any part of a vi
1567 command in open or visual mode (but not as part of the arguments to the
1568 command), the action shall be as if the corresponding rhs had been
1569 entered.
1570 If any character in the command, other than the first, is escaped using
1572 a <control>-V character, that character shall not be part of a match to
1573 an lhs.
1574 It is unspecified whether implementations shall support map commands
1576 where the lhs is more than a single character in length, where the
1577 first character of the lhs is printable.
1578 If lhs contains more than one character and the first character is '#'
1580 , followed by a sequence of digits corresponding to a numbered function
1581 key, then when this function key is typed it shall be mapped to rhs.
1582 Characters other than digits following a '#' character also represent
1583 the function key named by the characters in the lhs following the '#'
1584 and may be mapped to rhs. It is unspecified how function keys are named
1585 or what function keys are supported.
1586 For text input mode mappings: When the lhs is entered as any part of
1588 text entered in open or visual text input modes, the action shall be as
1589 if the corresponding rhs had been entered.
1590 If any character in the input text is escaped using a <control>-V char‐
1592 acter, that character shall not be part of a match to an lhs.
1593 It is unspecified whether the lhs text entered for subsequent map or
1595 unmap commands is replaced with the rhs text for the purposes of the
1596 screen display; regardless of whether or not the display appears as if
1597 the corresponding rhs text was entered, the effect of the command shall
1598 be as if the lhs text was entered.
1599 If only part of the lhs is entered, it is unspecified how long the edi‐
1601 tor will wait for additional, possibly matching characters before
1602 treating the already entered characters as not matching the lhs.
1603 The rhs characters shall themselves be subject to remapping, unless
1605 otherwise specified by the remap edit option, except that if the char‐
1606 acters in lhs occur as prefix characters in rhs, those characters shall
1607 not be remapped.
1608 On block-mode terminals, the mapping need not occur immediately (for
1610 example, it may occur after the terminal transmits a group of charac‐
1611 ters to the system), but it shall achieve the same results as if it
1612 occurred immediately.
1613 Current line: Unchanged.
1615 Current column: Unchanged.
1617 Mark
1619 Synopsis:
1620 [1addr] ma[rk] character
1623 [1addr] k character
1624 Implementations shall support character values of a single lowercase
1627 letter of the POSIX locale and the characters '`' and '" ; support of
1628 other characters is implementation-defined.
1629 If executing the vi m command, set the specified mark to the current
1631 line and 1-based numbered character referenced by the current column,
1632 if any; otherwise, column position 1.
1633 Otherwise, set the specified mark to the specified line and 1-based
1635 numbered first non- <blank> non- <newline> in the line, if any; other‐
1636 wise, the last non- <newline> in the line, if any; otherwise, column
1637 position 1.
1638 The mark shall remain associated with the line until the mark is reset
1640 or the line is deleted. If a deleted line is restored by a subsequent
1641 undo command, any marks previously associated with the line, which have
1642 not been reset, shall be restored as well. Any use of a mark not asso‐
1643 ciated with a current line in the edit buffer shall be an error.
1644 The marks ` and ' shall be set as described previously, immediately
1646 before the following events occur in the editor:
1647 1. The use of '$' as an ex address
1649 2. The use of a positive decimal number as an ex address
1651 3. The use of a search command as an ex address
1653 4. The use of a mark reference as an ex address
1655 5. The use of the following open and visual mode commands: <con‐
1657 trol>-], %, (, ), [, ], {, }
1658 6. The use of the following open and visual mode commands: ', G, H, L,
1660 M, z if the current line will change as a result of the command
1661 7. The use of the open and visual mode commands: /, ?, N, `, n if the
1663 current line or column will change as a result of the command
1664 8. The use of the ex mode commands: z, undo, global, v
1666 For rules 1., 2., 3., and 4., the ` and ' marks shall not be set if the
1668 ex command is parsed as specified by rule 6.a. in Command Line Parsing
1669 in ex .
1670 For rules 5., 6., and 7., the ` and ' marks shall not be set if the
1672 commands are used as motion commands in open and visual mode.
1673 For rules 1., 2., 3., 4., 5., 6., 7., and 8., the ` and ' marks shall
1675 not be set if the command fails.
1676 The ` and ' marks shall be set as described previously, each time the
1678 contents of the edit buffer are replaced (including the editing of the
1679 initial buffer), if in open or visual mode, or if in ex mode and the
1680 edit buffer is not empty, before any commands or movements (including
1681 commands or movements specified by the -c or -t options or the + com‐
1682 mand argument) are executed on the edit buffer. If in open or visual
1683 mode, the marks shall be set as if executing the vi m command; other‐
1684 wise, as if executing the ex mark command.
1685 When changing from ex mode to open or visual mode, if the ` and ' marks
1687 are not already set, the ` and ' marks shall be set as described previ‐
1688 ously.
1689 Current line: Unchanged.
1691 Current column: Unchanged.
1693 Move
1695 Synopsis:
1696 [2addr] m[ove] 1addr [flags]
1699 Move the specified lines after the specified destination line. A desti‐
1702 nation of line zero specifies that the lines shall be placed at the
1703 beginning of the edit buffer. It shall be an error if the destination
1704 line is within the range of lines to be moved.
1705 Current line: Set to the last of the moved lines.
1707 Current column: Set to non- <blank>.
1709 Next
1711 Synopsis:
1712 n[ext][!][+command][file ...]
1715 If no '!' is appended to the command name, and the edit buffer has been
1718 modified since the last complete write, it shall be an error, unless
1719 the file is successfully written as specified by the autowrite option.
1720 If one or more files is specified:
1722 1. Set the argument list to the specified filenames.
1724 2. Set the current argument list reference to be the first entry in
1726 the argument list.
1727 3. Set the current pathname to the first filename specified.
1729 Otherwise:
1731 1. It shall be an error if there are no more filenames in the argument
1733 list after the filename currently referenced.
1734 2. Set the current pathname and the current argument list reference to
1736 the filename after the filename currently referenced in the argu‐
1737 ment list.
1738 Replace the contents of the edit buffer with the contents of the file
1740 named by the current pathname. If for any reason the contents of the
1741 file cannot be accessed, the edit buffer shall be empty.
1742 This command shall be affected by the autowrite and writeany edit
1744 options.
1745 The + command option shall be <blank>-delimited; <blank>s can be
1747 escaped by preceding them with a backslash character. The + command
1748 shall be interpreted as an ex command immediately after the contents of
1749 the edit buffer have been replaced and the current line and column have
1750 been set.
1751 Current line: Set as described for the edit command.
1753 Current column: Set as described for the edit command.
1755 Number
1757 Synopsis:
1758 [2addr] nu[mber][count][flags]
1761 [2addr] #[count][flags]
1762 These commands shall be equivalent to the ex command:
1765 [2addr] p[rint][count] #[flags]
1768 See Print .
1770 Open
1772 Synopsis:
1773 [1addr] o[pen] /pattern/ [flags]
1776 This command need not be supported on block-mode terminals or terminals
1779 with insufficient capabilities. If standard input, standard output, or
1780 standard error are not terminal devices, the results are unspecified.
1781 Enter open mode.
1783 The trailing delimiter can be omitted from pattern at the end of the
1785 command line. If pattern is empty (for example, "//" ) or not speci‐
1786 fied, the last regular expression used in the editor shall be used as
1787 the pattern. The pattern can be delimited by slashes (shown in the Syn‐
1788 opsis), as well as any alphanumeric, or non- <blank> other than back‐
1789 slash, vertical line, double quote, or <newline>.
1790 Current line: Set to the specified line.
1792 Current column: Set to non- <blank>.
1794 Preserve
1796 Synopsis:
1797 pre[serve]
1800 Save the edit buffer in a form that can later be recovered by using the
1803 -r option or by using the ex recover command. After the file has been
1804 preserved, a mail message shall be sent to the user. This message shall
1805 be readable by invoking the mailx utility. The message shall contain
1806 the name of the file, the time of preservation, and an ex command that
1807 could be used to recover the file. Additional information may be
1808 included in the mail message.
1809 Current line: Unchanged.
1811 Current column: Unchanged.
1813 Print
1815 Synopsis:
1816 [2addr] p[rint][count][flags]
1819 Write the addressed lines. The behavior is unspecified if the number of
1822 columns on the display is less than the number of columns required to
1823 write any single character in the lines being written.
1824 Non-printable characters, except for the <tab>, shall be written as
1826 implementation-defined multi-character sequences.
1827 If the # flag is specified or the number edit option is set, each line
1829 shall be preceded by its line number in the following format:
1830 "%6d ", <line number>
1833 If the l flag is specified or the list edit option is set:
1835 1. The characters listed in the Base Definitions volume of
1837 IEEE Std 1003.1-2001, Table 5-1, Escape Sequences and Associated
1838 Actions shall be written as the corresponding escape sequence.
1839 2. Non-printable characters not in the Base Definitions volume of
1841 IEEE Std 1003.1-2001, Table 5-1, Escape Sequences and Associated
1842 Actions shall be written as one three-digit octal number (with a
1843 preceding backslash) for each byte in the character (most signifi‐
1844 cant byte first). If the size of a byte on the system is greater
1845 than 9 bits, the format used for non-printable characters is imple‐
1846 mentation-defined.
1847 3. The end of each line shall be marked with a '$' , and literal '$'
1849 characters within the line shall be written with a preceding back‐
1850 slash.
1851 Long lines shall be folded; the length at which folding occurs is
1853 unspecified, but should be appropriate for the output terminal, consid‐
1854 ering the number of columns of the terminal.
1855 If a line is folded, and the l flag is not specified and the list edit
1857 option is not set, it is unspecified whether a multi-column character
1858 at the folding position is separated; it shall not be discarded.
1859 Current line: Set to the last written line.
1861 Current column: Unchanged if the current line is unchanged; otherwise,
1863 set to non- <blank>.
1864 Put
1866 Synopsis:
1867 [1addr] pu[t][buffer]
1870 Append text from the specified buffer (by default, the unnamed buffer)
1873 to the specified line; line zero specifies that the text shall be
1874 placed at the beginning of the edit buffer. Each portion of a line in
1875 the buffer shall become a new line in the edit buffer, regardless of
1876 the mode of the buffer.
1877 Current line: Set to the last line entered into the edit buffer.
1879 Current column: Set to non- <blank>.
1881 Quit
1883 Synopsis:
1884 q[uit][!]
1887 If no '!' is appended to the command name:
1890 1. If the edit buffer has been modified since the last complete write,
1892 it shall be an error.
1893 2. If there are filenames in the argument list after the filename cur‐
1895 rently referenced, and the last command was not a quit, wq, xit, or
1896 ZZ (see Exit ) command, it shall be an error.
1897 Otherwise, terminate the editing session.
1899 Read
1901 Synopsis:
1902 [1addr] r[ead][!][file]
1905 If '!' is not the first non- <blank> to follow the command name, a copy
1908 of the specified file shall be appended into the edit buffer after the
1909 specified line; line zero specifies that the copy shall be placed at
1910 the beginning of the edit buffer. The number of lines and bytes read
1911 shall be written. If no file is named, the current pathname shall be
1912 the default. If there is no current pathname, then file shall become
1913 the current pathname. If there is no current pathname or file operand,
1914 it shall be an error. Specifying a file that is not of type regular
1915 shall have unspecified results.
1916 Otherwise, if file is preceded by '!' , the rest of the line after the
1918 '!' shall have '%' , '#' , and '!' characters expanded as described in
1919 Command Line Parsing in ex .
1920 The ex utility shall then pass two arguments to the program named by
1922 the shell edit option; the first shall be -c and the second shall be
1923 the expanded arguments to the read command as a single argument. The
1924 standard input of the program shall be set to the standard input of the
1925 ex program when it was invoked. The standard error and standard output
1926 of the program shall be appended into the edit buffer after the speci‐
1927 fied line.
1928 Each line in the copied file or program output (as delimited by <new‐
1930 line>s or the end of the file or output if it is not immediately pre‐
1931 ceded by a <newline>), shall be a separate line in the edit buffer. Any
1932 occurrences of <carriage-return> and <newline> pairs in the output
1933 shall be treated as single <newline>s.
1934 The special meaning of the '!' following the read command can be over‐
1936 ridden by escaping it with a backslash character.
1937 Current line: If no lines are added to the edit buffer, unchanged.
1939 Otherwise, if in open or visual mode, set to the first line entered
1940 into the edit buffer. Otherwise, set to the last line entered into the
1941 edit buffer.
1942 Current column: Set to non- <blank>.
1944 Recover
1946 Synopsis:
1947 rec[over][!] file
1950 If no '!' is appended to the command name, and the edit buffer has been
1953 modified since the last complete write, it shall be an error.
1954 If no file operand is specified, then the current pathname shall be
1956 used. If there is no current pathname or file operand, it shall be an
1957 error.
1958 If no recovery information has previously been saved about file, the
1960 recover command shall behave identically to the edit command, and an
1961 informational message to this effect shall be written.
1962 Otherwise, set the current pathname to file, and replace the current
1964 contents of the edit buffer with the recovered contents of file. If
1965 there are multiple instances of the file to be recovered, the one most
1966 recently saved shall be recovered, and an informational message that
1967 there are previous versions of the file that can be recovered shall be
1968 written. The editor shall behave as if the contents of the edit buffer
1969 have already been modified.
1970 Current file: Set as described for the edit command.
1972 Current column: Set as described for the edit command.
1974 Rewind
1976 Synopsis:
1977 rew[ind][!]
1980 If no '!' is appended to the command name, and the edit buffer has been
1983 modified since the last complete write, it shall be an error, unless
1984 the file is successfully written as specified by the autowrite option.
1985 If the argument list is empty, it shall be an error.
1987 The current argument list reference and the current pathname shall be
1989 set to the first filename in the argument list.
1990 Replace the contents of the edit buffer with the contents of the file
1992 named by the current pathname. If for any reason the contents of the
1993 file cannot be accessed, the edit buffer shall be empty.
1994 This command shall be affected by the autowrite and writeany edit
1996 options.
1997 Current line: Set as described for the edit command.
1999 Current column: Set as described for the edit command.
2001 Set
2003 Synopsis:
2004 se[t][option[=[value]] ...][nooption ...][option? ...][all]
2007 When no arguments are specified, write the value of the term edit
2010 option and those options whose values have been changed from the
2011 default settings; when the argument all is specified, write all of the
2012 option values.
2013 Giving an option name followed by the character '?' shall cause the
2015 current value of that option to be written. The '?' can be separated
2016 from the option name by zero or more <blank>s. The '?' shall be neces‐
2017 sary only for Boolean valued options. Boolean options can be given val‐
2018 ues by the form set option to turn them on or set no option to turn
2019 them off; string and numeric options can be assigned by the form set
2020 option= value. Any <blank>s in strings can be included as is by preced‐
2021 ing each <blank> with an escaping backslash. More than one option can
2022 be set or listed by a single set command by specifying multiple argu‐
2023 ments, each separated from the next by one or more <blank>s.
2024 See Edit Options in ex for details about specific options.
2026 Current line: Unchanged.
2028 Current column: Unchanged.
2030 Shell
2032 Synopsis:
2033 sh[ell]
2036 Invoke the program named in the shell edit option with the single argu‐
2039 ment -i (interactive mode). Editing shall be resumed when the program
2040 exits.
2041 Current line: Unchanged.
2043 Current column: Unchanged.
2045 Source
2047 Synopsis:
2048 so[urce] file
2051 Read and execute ex commands from file. Lines in the file that are
2054 blank lines shall be ignored.
2055 Current line: As specified for the individual ex commands.
2057 Current column: As specified for the individual ex commands.
2059 Substitute
2061 Synopsis:
2062 [2addr] s[ubstitute][/pattern/repl/[options][count][flags]]
2065 [2addr] &[options][count][flags]]
2067 [2addr] ~[options][count][flags]]
2069 Replace the first instance of the pattern pattern by the string repl on
2072 each specified line. (See Regular Expressions in ex and Replacement
2073 Strings in ex .) Any non-alphabetic, non- <blank> delimiter other than
2074 '\' , '|' , double quote, or <newline> can be used instead of '/' .
2075 Backslash characters can be used to escape delimiters, backslash char‐
2076 acters, and other special characters.
2077 The trailing delimiter can be omitted from pattern or from repl at the
2079 end of the command line. If both pattern and repl are not specified or
2080 are empty (for example, "//" ), the last s command shall be repeated.
2081 If only pattern is not specified or is empty, the last regular expres‐
2082 sion used in the editor shall be used as the pattern. If only repl is
2083 not specified or is empty, the pattern shall be replaced by nothing. If
2084 the entire replacement pattern is '%' , the last replacement pattern to
2085 an s command shall be used.
2086 Entering a <carriage-return> in repl (which requires an escaping back‐
2088 slash in ex mode and an escaping <control>-V in open or vi mode) shall
2089 split the line at that point, creating a new line in the edit buffer.
2090 The <carriage-return> shall be discarded.
2091 If options includes the letter 'g' ( global), all non-overlapping
2093 instances of the pattern in the line shall be replaced.
2094 If options includes the letter 'c' ( confirm), then before each substi‐
2096 tution the line shall be written; the written line shall reflect all
2097 previous substitutions. On the following line, <space>s shall be writ‐
2098 ten beneath the characters from the line that are before the pattern to
2099 be replaced, and '^' characters written beneath the characters included
2100 in the pattern to be replaced. The ex utility shall then wait for a
2101 response from the user. An affirmative response shall cause the substi‐
2102 tution to be done, while any other input shall not make the substitu‐
2103 tion. An affirmative response shall consist of a line with the affirma‐
2104 tive response (as defined by the current locale) at the beginning of
2105 the line. This line shall be subject to editing in the same way as the
2106 ex command line.
2107 If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications
2109 confirmed by the user shall be preserved in the edit buffer after the
2110 interrupt.
2111 If the remembered search direction is not set, the s command shall set
2113 it to forward.
2114 In the second Synopsis, the & command shall repeat the previous substi‐
2116 tution, as if the & command were replaced by:
2117 s/pattern/repl/
2120 where pattern and repl are as specified in the previous s, &, or ~ com‐
2122 mand.
2123 In the third Synopsis, the ~ command shall repeat the previous substi‐
2125 tution, as if the '~' were replaced by:
2126 s/pattern/repl/
2129 where pattern shall be the last regular expression specified to the
2131 editor, and repl shall be from the previous substitution (including &
2132 and ~) command.
2133 These commands shall be affected by the LC_MESSAGES environment vari‐
2135 able.
2136 Current line: Set to the last line in which a substitution occurred,
2138 or, unchanged if no substitution occurred.
2139 Current column: Set to non- <blank>.
2141 Suspend
2143 Synopsis:
2144 su[spend][!]st[op][!]
2147 Allow control to return to the invoking process; ex shall suspend
2150 itself as if it had received the SIGTSTP signal. The suspension shall
2151 occur only if job control is enabled in the invoking shell (see the
2152 description of set -m).
2153 These commands shall be affected by the autowrite and writeany edit
2155 options.
2156 The current susp character (see stty ) shall be equivalent to the sus‐
2158 pend command.
2159 Tag
2161 Synopsis:
2162 ta[g][!] tagstring
2165 The results are unspecified if the format of a tags file is not as
2168 specified by the ctags utility (see ctags ) description.
2169 The tag command shall search for tagstring in the tag files referred to
2171 by the tag edit option, in the order they are specified, until a refer‐
2172 ence to tagstring is found. Files shall be searched from beginning to
2173 end. If no reference is found, it shall be an error and an error mes‐
2174 sage to this effect shall be written. If the reference is not found, or
2175 if an error occurs while processing a file referred to in the tag edit
2176 option, it shall be an error, and an error message shall be written at
2177 the first occurrence of such an error.
2178 Otherwise, if the tags file contained a pattern, the pattern shall be
2180 treated as a regular expression used in the editor; for example, for
2181 the purposes of the s command.
2182 If the tagstring is in a file with a different name than the current
2184 pathname, set the current pathname to the name of that file, and
2185 replace the contents of the edit buffer with the contents of that file.
2186 In this case, if no '!' is appended to the command name, and the edit
2187 buffer has been modified since the last complete write, it shall be an
2188 error, unless the file is successfully written as specified by the
2189 autowrite option.
2190 This command shall be affected by the autowrite, tag, taglength, and
2192 writeany edit options.
2193 Current line: If the tags file contained a line number, set to that
2195 line number. If the line number is larger than the last line in the
2196 edit buffer, an error message shall be written and the current line
2197 shall be set as specified for the edit command.
2198 If the tags file contained a pattern, set to the first occurrence of
2200 the pattern in the file. If no matching pattern is found, an error mes‐
2201 sage shall be written and the current line shall be set as specified
2202 for the edit command.
2203 Current column: If the tags file contained a line-number reference and
2205 that line-number was not larger than the last line in the edit buffer,
2206 or if the tags file contained a pattern and that pattern was found, set
2207 to non- <blank>. Otherwise, set as specified for the edit command.
2208 Unabbreviate
2210 Synopsis:
2211 una[bbrev] lhs
2214 If lhs is not an entry in the current list of abbreviations (see Abbre‐
2217 viate ), it shall be an error. Otherwise, delete lhs from the list of
2218 abbreviations.
2219 Current line: Unchanged.
2221 Current column: Unchanged.
2223 Undo
2225 Synopsis:
2226 u[ndo]
2229 Reverse the changes made by the last command that modified the contents
2232 of the edit buffer, including undo. For this purpose, the global, v,
2233 open, and visual commands, and commands resulting from buffer execu‐
2234 tions and mapped character expansions, are considered single commands.
2235 If no action that can be undone preceded the undo command, it shall be
2237 an error.
2238 If the undo command restores lines that were marked, the mark shall
2240 also be restored unless it was reset subsequent to the deletion of the
2241 lines.
2242 Current line:
2244 1. If lines are added or changed in the file, set to the first line
2246 added or changed.
2247 2. Set to the line before the first line deleted, if it exists.
2249 3. Set to 1 if the edit buffer is not empty.
2251 4. Set to zero.
2253 Current column: Set to non- <blank>.
2255 Unmap
2257 Synopsis:
2258 unm[ap][!] lhs
2261 If '!' is appended to the command name, and if lhs is not an entry in
2264 the list of text input mode map definitions, it shall be an error. Oth‐
2265 erwise, delete lhs from the list of text input mode map definitions.
2266 If no '!' is appended to the command name, and if lhs is not an entry
2268 in the list of command mode map definitions, it shall be an error. Oth‐
2269 erwise, delete lhs from the list of command mode map definitions.
2270 Current line: Unchanged.
2272 Current column: Unchanged.
2274 Version
2276 Synopsis:
2277 ve[rsion]
2280 Write a message containing version information for the editor. The for‐
2283 mat of the message is unspecified.
2284 Current line: Unchanged.
2286 Current column: Unchanged.
2288 Visual
2290 Synopsis:
2291 [1addr] vi[sual][type][count][flags]
2294 If ex is currently in open or visual mode, the Synopsis and behavior of
2297 the visual command shall be the same as the edit command, as specified
2298 by Edit .
2299 Otherwise, this command need not be supported on block-mode terminals
2301 or terminals with insufficient capabilities. If standard input, stan‐
2302 dard output, or standard error are not terminal devices, the results
2303 are unspecified.
2304 If count is specified, the value of the window edit option shall be set
2306 to count (as described in window ). If the '^' type character was also
2307 specified, the window edit option shall be set before being used by the
2308 type character.
2309 Enter visual mode. If type is not specified, it shall be as if a type
2311 of '+' was specified. The type shall cause the following effects:
2312 + Place the beginning of the specified line at the top of the dis‐
2314 play.
2315 - Place the end of the specified line at the bottom of the dis‐
2317 play.
2318 . Place the beginning of the specified line in the middle of the
2320 display.
2321 ^ If the specified line is less than or equal to the value of the
2323 window edit option, set the line to 1; otherwise, decrement the
2324 line by the value of the window edit option minus 1. Place the
2325 beginning of this line as close to the bottom of the displayed
2326 lines as possible, while still displaying the value of the win‐
2327 dow edit option number of lines.
2328 Current line: Set to the specified line.
2331 Current column: Set to non- <blank>.
2333 Write
2335 Synopsis:
2336 [2addr] w[rite][!][>>][file]
2339 [2addr] w[rite][!][file]
2340 [2addr] wq[!][>>][file]
2341 If no lines are specified, the lines shall default to the entire file.
2344 The command wq shall be equivalent to a write command followed by a
2346 quit command; wq! shall be equivalent to write! followed by quit. In
2347 both cases, if the write command fails, the quit shall not be
2348 attempted.
2349 If the command name is not followed by one or more <blank>s, or file is
2351 not preceded by a '!' character, the write shall be to a file.
2352 1. If the >> argument is specified, and the file already exists, the
2354 lines shall be appended to the file instead of replacing its con‐
2355 tents. If the >> argument is specified, and the file does not
2356 already exist, it is unspecified whether the write shall proceed as
2357 if the >> argument had not been specified or if the write shall
2358 fail.
2359 2. If the readonly edit option is set (see readonly ), the write shall
2361 fail.
2362 3. If file is specified, and is not the current pathname, and the file
2364 exists, the write shall fail.
2365 4. If file is not specified, the current pathname shall be used. If
2367 there is no current pathname, the write command shall fail.
2368 5. If the current pathname is used, and the current pathname has been
2370 changed by the file or read commands, and the file exists, the
2371 write shall fail. If the write is successful, subsequent writes
2372 shall not fail for this reason (unless the current pathname is
2373 changed again).
2374 6. If the whole edit buffer is not being written, and the file to be
2376 written exists, the write shall fail.
2377 For rules 1., 2., 4., and 5., the write can be forced by appending the
2379 character '!' to the command name.
2380 For rules 2., 4., and 5., the write can be forced by setting the
2382 writeany edit option.
2383 Additional, implementation-defined tests may cause the write to fail.
2385 If the edit buffer is empty, a file without any contents shall be writ‐
2387 ten.
2388 An informational message shall be written noting the number of lines
2390 and bytes written.
2391 Otherwise, if the command is followed by one or more <blank>s, and the
2393 file is preceded by '!' , the rest of the line after the '!' shall have
2394 '%' , '#' , and '!' characters expanded as described in Command Line
2395 Parsing in ex .
2396 The ex utility shall then pass two arguments to the program named by
2398 the shell edit option; the first shall be -c and the second shall be
2399 the expanded arguments to the write command as a single argument. The
2400 specified lines shall be written to the standard input of the command.
2401 The standard error and standard output of the program, if any, shall be
2402 written as described for the print command. If the last character in
2403 that output is not a <newline>, a <newline> shall be written at the end
2404 of the output.
2405 The special meaning of the '!' following the write command can be over‐
2407 ridden by escaping it with a backslash character.
2408 Current line: Unchanged.
2410 Current column: Unchanged.
2412 Write and Exit
2414 Synopsis:
2415 [2addr] x[it][!][file]
2418 If the edit buffer has not been modified since the last complete write,
2421 xit shall be equivalent to the quit command, or if a '!' is appended to
2422 the command name, to quit!.
2423 Otherwise, xit shall be equivalent to the wq command, or if a '!' is
2425 appended to the command name, to wq!.
2426 Current line: Unchanged.
2428 Current column: Unchanged.
2430 Yank
2432 Synopsis:
2433 [2addr] ya[nk][buffer][count]
2436 Copy the specified lines to the specified buffer (by default, the
2439 unnamed buffer), which shall become a line-mode buffer.
2440 Current line: Unchanged.
2442 Current column: Unchanged.
2444 Adjust Window
2446 Synopsis:
2447 [1addr] z[!][type ...][count][flags]
2450 If no line is specified, the current line shall be the default; if type
2453 is omitted as well, the current line value shall first be incremented
2454 by 1. If incrementing the current line would cause it to be greater
2455 than the last line in the edit buffer, it shall be an error.
2456 If there are <blank>s between the type argument and the preceding z
2458 command name or optional '!' character, it shall be an error.
2459 If count is specified, the value of the window edit option shall be set
2461 to count (as described in window ). If count is omitted, it shall
2462 default to 2 times the value of the scroll edit option, or if ! was
2463 specified, the number of lines in the display minus 1.
2464 If type is omitted, then count lines starting with the specified line
2466 shall be written. Otherwise, count lines starting with the line speci‐
2467 fied by the type argument shall be written.
2468 The type argument shall change the lines to be written. The possible
2470 values of type are as follows:
2471 - The specified line shall be decremented by the following value:
2473 (((number of "-" characters) x count) -1)
2476 If the calculation would result in a number less than 1, it shall be an
2478 error. Write lines from the edit buffer, starting at the new value of
2479 line, until count lines or the last line in the edit buffer has been
2480 written.
2481 + The specified line shall be incremented by the following value:
2483 (((number of "+" characters) -1) x count) +1
2486 If the calculation would result in a number greater than the last line
2488 in the edit buffer, it shall be an error. Write lines from the edit
2489 buffer, starting at the new value of line, until count lines or the
2490 last line in the edit buffer has been written.
2491 =,. If more than a single '.' or '=' is specified, it shall be an
2493 error. The following steps shall be taken:
2494 1. If count is zero, nothing shall be written.
2496 2. Write as many of the N lines before the current line in the
2498 edit buffer as exist. If count or '!' was specified, N shall
2499 be:
2500 (count -1) /2
2503 Otherwise, N shall be:
2505 (count -3) /2
2508 If N is a number less than 3, no lines shall be written.
2510 3. If '=' was specified as the type character, write a line
2512 consisting of the smaller of the number of columns in the
2513 display divided by two, or 40 '-' characters.
2514 4. Write the current line.
2516 5. Repeat step 3.
2518 6. Write as many of the N lines after the current line in the
2520 edit buffer as exist. N shall be defined as in step 2. If N
2521 is a number less than 3, no lines shall be written. If count
2522 is less than 3, no lines shall be written.
2523 ^ The specified line shall be decremented by the following value:
2525 (((number of "^" characters) +1) x count) -1
2528 If the calculation would result in a number less than 1, it shall be an
2530 error. Write lines from the edit buffer, starting at the new value of
2531 line, until count lines or the last line in the edit buffer has been
2532 written.
2533 Current line: Set to the last line written, unless the type is =, in
2536 which case, set to the specified line.
2537 Current column: Set to non- <blank>.
2539 Escape
2541 Synopsis:
2542 ! command
2545 [addr]! command
2546 The contents of the line after the '!' shall have '%' , '#' , and '!'
2549 characters expanded as described in Command Line Parsing in ex . If the
2550 expansion causes the text of the line to change, it shall be redis‐
2551 played, preceded by a single '!' character.
2552 The ex utility shall execute the program named by the shell edit
2554 option. It shall pass two arguments to the program; the first shall be
2555 -c, and the second shall be the expanded arguments to the ! command as
2556 a single argument.
2557 If no lines are specified, the standard input, standard output, and
2559 standard error of the program shall be set to the standard input, stan‐
2560 dard output, and standard error of the ex program when it was invoked.
2561 In addition, a warning message shall be written if the edit buffer has
2562 been modified since the last complete write, and the warn edit option
2563 is set.
2564 If lines are specified, they shall be passed to the program as standard
2566 input, and the standard output and standard error of the program shall
2567 replace those lines in the edit buffer. Each line in the program output
2568 (as delimited by <newline>s or the end of the output if it is not imme‐
2569 diately preceded by a <newline>), shall be a separate line in the edit
2570 buffer. Any occurrences of <carriage-return> and <newline> pairs in the
2571 output shall be treated as single <newline>s. The specified lines shall
2572 be copied into the unnamed buffer before they are replaced, and the
2573 unnamed buffer shall become a line-mode buffer.
2574 If in ex mode, a single '!' character shall be written when the program
2576 completes.
2577 This command shall be affected by the shell and warn edit options. If
2579 no lines are specified, this command shall be affected by the autowrite
2580 and writeany edit options. If lines are specified, this command shall
2581 be affected by the autoprint edit option.
2582 Current line:
2584 1. If no lines are specified, unchanged.
2586 2. Otherwise, set to the last line read in, if any lines are read in.
2588 3. Otherwise, set to the line before the first line of the lines spec‐
2590 ified, if that line exists.
2591 4. Otherwise, set to the first line of the edit buffer if the edit
2593 buffer is not empty.
2594 5. Otherwise, set to zero.
2596 Current column: If no lines are specified, unchanged. Otherwise, set to
2598 non- <blank>.
2599 Shift Left
2601 Synopsis:
2602 [2addr] <[< ...][count][flags]
2605 Shift the specified lines to the start of the line; the number of col‐
2608 umn positions to be shifted shall be the number of command characters
2609 times the value of the shiftwidth edit option. Only leading <blank>s
2610 shall be deleted or changed into other <blank>s in shifting; other
2611 characters shall not be affected.
2612 Lines to be shifted shall be copied into the unnamed buffer, which
2614 shall become a line-mode buffer.
2615 This command shall be affected by the autoprint edit option.
2617 Current line: Set to the last line in the lines specified.
2619 Current column: Set to non- <blank>.
2621 Shift Right
2623 Synopsis:
2624 [2addr] >[> ...][count][flags]
2627 Shift the specified lines away from the start of the line; the number
2630 of column positions to be shifted shall be the number of command char‐
2631 acters times the value of the shiftwidth edit option. The shift shall
2632 be accomplished by adding <blank>s as a prefix to the line or changing
2633 leading <blank>s into other <blank>s. Empty lines shall not be
2634 changed.
2635 Lines to be shifted shall be copied into the unnamed buffer, which
2637 shall become a line-mode buffer.
2638 This command shall be affected by the autoprint edit option.
2640 Current line: Set to the last line in the lines specified.
2642 Current column: Set to non- <blank>.
2644 <control>-D
2646 Synopsis:
2647 <control>-D
2650 Write the next n lines, where n is the minimum of the values of the
2653 scroll edit option and the number of lines after the current line in
2654 the edit buffer. If the current line is the last line of the edit buf‐
2655 fer it shall be an error.
2656 Current line: Set to the last line written.
2658 Current column: Set to non- <blank>.
2660 Write Line Number
2662 Synopsis:
2663 [1addr] = [flags]
2666 If line is not specified, it shall default to the last line in the edit
2669 buffer. Write the line number of the specified line.
2670 Current line: Unchanged.
2672 Current column: Unchanged.
2674 Execute
2676 Synopsis:
2677 [2addr] @ buffer[2addr] * buffer
2680 If no buffer is specified or is specified as '@' or '*' , the last buf‐
2683 fer executed shall be used. If no previous buffer has been executed, it
2684 shall be an error.
2685 For each line specified by the addresses, set the current line ( '.' )
2687 to the specified line, and execute the contents of the named buffer (as
2688 they were at the time the @ command was executed) as ex commands. For
2689 each line of a line-mode buffer, and all but the last line of a charac‐
2690 ter-mode buffer, the ex command parser shall behave as if the line was
2691 terminated by a <newline>.
2692 If an error occurs during this process, or a line specified by the
2694 addresses does not exist when the current line would be set to it, or
2695 more than a single line was specified by the addresses, and the con‐
2696 tents of the edit buffer are replaced (for example, by the ex :edit
2697 command) an error message shall be written, and no more commands
2698 resulting from the execution of this command shall be processed.
2699 Current line: As specified for the individual ex commands.
2701 Current column: As specified for the individual ex commands.
2703 Regular Expressions in ex
2705 The ex utility shall support regular expressions that are a superset of
2706 the basic regular expressions described in the Base Definitions volume
2707 of IEEE Std 1003.1-2001, Section 9.3, Basic Regular Expressions. A null
2708 regular expression ( "//" ) shall be equivalent to the last regular
2709 expression encountered.
2710 Regular expressions can be used in addresses to specify lines and, in
2712 some commands (for example, the substitute command), to specify por‐
2713 tions of a line to be substituted.
2714 The following constructs can be used to enhance the basic regular
2716 expressions:
2717 \< Match the beginning of a word. (See the definition of word at
2719 the beginning of Command Descriptions in ex .)
2720 \> Match the end of a word.
2722 ~ Match the replacement part of the last substitute command. The
2724 tilde ( '~' ) character can be escaped in a regular expression
2725 to become a normal character with no special meaning. The back‐
2726 slash shall be discarded.
2727 When the editor option magic is not set, the only characters with spe‐
2730 cial meanings shall be '^' at the beginning of a pattern, '$' at the
2731 end of a pattern, and '\' . The characters '.' , '*' , '[' , and '~'
2732 shall be treated as ordinary characters unless preceded by a '\' ; when
2733 preceded by a '\' they shall regain their special meaning, or in the
2734 case of backslash, be handled as a single backslash. Backslashes used
2735 to escape other characters shall be discarded.
2736 Replacement Strings in ex
2738 The character '&' ( '\&' if the editor option magic is not set) in the
2739 replacement string shall stand for the text matched by the pattern to
2740 be replaced. The character '~' ( '\~' if magic is not set) shall be
2741 replaced by the replacement part of the previous substitute command.
2742 The sequence '\n' , where n is an integer, shall be replaced by the
2743 text matched by the pattern enclosed in the nth set of parentheses '\('
2744 and '\)' .
2745 The strings '\l' , '\u' , '\L' , and '\U' can be used to modify the
2747 case of elements in the replacement string (using the '\&' or "\"
2748 digit) notation. The string '\l' ( '\u' ) shall cause the character
2749 that follows to be converted to lowercase (uppercase). The string '\L'
2750 ( '\U' ) shall cause all characters subsequent to it to be converted to
2751 lowercase (uppercase) as they are inserted by the substitution until
2752 the string '\e' or '\E' , or the end of the replacement string, is
2753 encountered.
2754 Otherwise, any character following a backslash shall be treated as that
2756 literal character, and the escaping backslash shall be discarded.
2757 An example of case conversion with the s command is as follows:
2759 :p
2762 The cat sat on the mat.
2763 :s/\<.at\>/\u&/gp
2764 The Cat Sat on the Mat.
2765 :s/S\(.*\)M/S\U\1\eM/p
2766 The Cat SAT ON THE Mat.
2767 Edit Options in ex
2769 The ex utility has a number of options that modify its behavior. These
2770 options have default settings, which can be changed using the set com‐
2771 mand.
2772 Options are Boolean unless otherwise specified.
2774 autoindent, ai
2776 [Default unset]
2777 If autoindent is set, each line in input mode shall be indented (using
2779 first as many <tab>s as possible, as determined by the editor option
2780 tabstop, and then using <space>s) to align with another line, as fol‐
2781 lows:
2782 1. If in open or visual mode and the text input is part of a line-ori‐
2784 ented command (see the EXTENDED DESCRIPTION in vi ), align to the
2785 first column.
2786 2. Otherwise, if in open or visual mode, indentation for each line
2788 shall be set as follows:
2789 a. If a line was previously inserted as part of this command, it
2791 shall be set to the indentation of the last inserted line by
2792 default, or as otherwise specified for the <control>-D charac‐
2793 ter in Input Mode Commands in vi .
2794 b. Otherwise, it shall be set to the indentation of the previous
2796 current line, if any; otherwise, to the first column.
2797 3. For the ex a, i, and c commands, indentation for each line shall be
2799 set as follows:
2800 a. If a line was previously inserted as part of this command, it
2802 shall be set to the indentation of the last inserted line by
2803 default, or as otherwise specified for the eof character in
2804 Scroll .
2805 b. Otherwise, if the command is the ex a command, it shall be set
2807 to the line appended after, if any; otherwise to the first col‐
2808 umn.
2809 c. Otherwise, if the command is the ex i command, it shall be set
2811 to the line inserted before, if any; otherwise to the first
2812 column.
2813 d. Otherwise, if the command is the ex c command, it shall be set
2815 to the indentation of the line replaced.
2816 autoprint, ap
2818 [Default set]
2819 If autoprint is set, the current line shall be written after each ex
2821 command that modifies the contents of the current edit buffer, and
2822 after each tag command for which the tag search pattern was found or
2823 tag line number was valid, unless:
2824 1. The command was executed while in open or visual mode.
2826 2. The command was executed as part of a global or v command or @ buf‐
2828 fer execution.
2829 3. The command was the form of the read command that reads a file into
2831 the edit buffer.
2832 4. The command was the append, change, or insert command.
2834 5. The command was not terminated by a <newline>.
2836 6. The current line shall be written by a flag specified to the com‐
2838 mand; for example, delete # shall write the current line as speci‐
2839 fied for the flag modifier to the delete command, and not as speci‐
2840 fied by the autoprint edit option.
2841 autowrite, aw
2843 [Default unset]
2844 If autowrite is set, and the edit buffer has been modified since it was
2846 last completely written to any file, the contents of the edit buffer
2847 shall be written as if the ex write command had been specified without
2848 arguments, before each command affected by the autowrite edit option is
2849 executed. Appending the character '!' to the command name of any of the
2850 ex commands except '!' shall prevent the write. If the write fails, it
2851 shall be an error and the command shall not be executed.
2852 beautify, bf
2854 [Default unset]
2855 If beautify is set, all non-printable characters, other than <tab>s,
2857 <newline>s, and <form-feed>s, shall be discarded from text read in from
2858 files.
2859 directory, dir
2861 [Default implementation-defined]
2862 The value of this option specifies the directory in which the editor
2864 buffer is to be placed. If this directory is not writable by the user,
2865 the editor shall quit.
2866 edcompatible, ed
2868 [Default unset]
2869 Causes the presence of g and c suffixes on substitute commands to be
2871 remembered, and toggled by repeating the suffixes.
2872 errorbells, eb
2874 [Default unset]
2875 If the editor is in ex mode, and the terminal does not support a stand‐
2877 out mode (such as inverse video), and errorbells is set, error messages
2878 shall be preceded by alerting the terminal.
2879 exrc
2881 [Default unset]
2882 If exrc is set, ex shall access any .exrc file in the current direc‐
2884 tory, as described in Initialization in ex and vi . If exrc is not set,
2885 ex shall ignore any .exrc file in the current directory during initial‐
2886 ization, unless the current directory is that named by the HOME envi‐
2887 ronment variable.
2888 ignorecase, ic
2890 [Default unset]
2891 If ignorecase is set, characters that have uppercase and lowercase rep‐
2893 resentations shall have those representations considered as equivalent
2894 for purposes of regular expression comparison.
2895 The ignorecase edit option shall affect all remembered regular expres‐
2897 sions; for example, unsetting the ignorecase edit option shall cause a
2898 subsequent vi n command to search for the last basic regular expression
2899 in a case-sensitive fashion.
2900 list
2902 [Default unset]
2903 If list is set, edit buffer lines written while in ex command mode
2905 shall be written as specified for the print command with the l flag
2906 specified. In open or visual mode, each edit buffer line shall be dis‐
2907 played as specified for the ex print command with the l flag specified.
2908 In open or visual text input mode, when the cursor does not rest on any
2909 character in the line, it shall rest on the '$' marking the end of the
2910 line.
2911 magic
2913 [Default set]
2914 If magic is set, modify the interpretation of characters in regular
2916 expressions and substitution replacement strings (see Regular Expres‐
2917 sions in ex and Replacement Strings in ex ).
2918 mesg
2920 [Default set]
2921 If mesg is set, the permission for others to use the write or talk com‐
2923 mands to write to the terminal shall be turned on while in open or vis‐
2924 ual mode. The shell-level command mesg n shall take precedence over any
2925 setting of the ex mesg option; that is, if mesg y was issued before the
2926 editor started (or in a shell escape), such as:
2927 :!mesg y
2930 the mesg option in ex shall suppress incoming messages, but the mesg
2932 option shall not enable incoming messages if mesg n was issued.
2933 number, nu
2935 [Default unset]
2936 If number is set, edit buffer lines written while in ex command mode
2938 shall be written with line numbers, in the format specified by the
2939 print command with the # flag specified. In ex text input mode, each
2940 line shall be preceded by the line number it will have in the file.
2941 In open or visual mode, each edit buffer line shall be displayed with a
2943 preceding line number, in the format specified by the ex print command
2944 with the # flag specified. This line number shall not be considered
2945 part of the line for the purposes of evaluating the current column;
2946 that is, column position 1 shall be the first column position after the
2947 format specified by the print command.
2948 paragraphs, para
2950 [Default in the POSIX locale IPLPPPQPP LIpplpipbp]
2951 The paragraphs edit option shall define additional paragraph boundaries
2953 for the open and visual mode commands. The paragraphs edit option can
2954 be set to a character string consisting of zero or more character
2955 pairs. It shall be an error to set it to an odd number of characters.
2956 prompt
2958 [Default set]
2959 If prompt is set, ex command mode input shall be prompted for with a
2961 colon ( ':' ); when unset, no prompt shall be written.
2962 readonly
2964 [Default see text]
2965 If the readonly edit option is set, read-only mode shall be enabled
2967 (see Write ). The readonly edit option shall be initialized to set if
2968 either of the following conditions are true:
2969 * The command-line option -R was specified.
2971 * Performing actions equivalent to the access() function called with
2973 the following arguments indicates that the file lacks write permis‐
2974 sion:
2975 1. The current pathname is used as the path argument.
2977 2. The constant W_OK is used as the amode argument.
2979 The readonly edit option may be initialized to set for other, implemen‐
2981 tation-defined reasons. The readonly edit option shall not be initial‐
2982 ized to unset based on any special privileges of the user or process.
2983 The readonly edit option shall be reinitialized each time that the con‐
2984 tents of the edit buffer are replaced (for example, by an edit or next
2985 command) unless the user has explicitly set it, in which case it shall
2986 remain set until the user explicitly unsets it. Once unset, it shall
2987 again be reinitialized each time that the contents of the edit buffer
2988 are replaced.
2989 redraw
2991 [Default unset]
2992 The editor simulates an intelligent terminal on a dumb terminal. (Since
2994 this is likely to require a large amount of output to the terminal, it
2995 is useful only at high transmission speeds.)
2996 remap
2998 [Default set]
2999 If remap is set, map translation shall allow for maps defined in terms
3001 of other maps; translation shall continue until a final product is
3002 obtained. If unset, only a one-step translation shall be done.
3003 report
3005 [Default 5]
3006 The value of this report edit option specifies what number of lines
3008 being added, copied, deleted, or modified in the edit buffer will cause
3009 an informational message to be written to the user. The following con‐
3010 ditions shall cause an informational message. The message shall contain
3011 the number of lines added, copied, deleted, or modified, but is other‐
3012 wise unspecified.
3013 * An ex or vi editor command, other than open, undo, or visual, that
3015 modifies at least the value of the report edit option number of
3016 lines, and which is not part of an ex global or v command, or ex or
3017 vi buffer execution, shall cause an informational message to be
3018 written.
3019 * An ex yank or vi y or Y command, that copies at least the value of
3021 the report edit option plus 1 number of lines, and which is not part
3022 of an ex global or v command, or ex or vi buffer execution, shall
3023 cause an informational message to be written.
3024 * An ex global, v, open, undo, or visual command or ex or vi buffer
3026 execution, that adds or deletes a total of at least the value of the
3027 report edit option number of lines, and which is not part of an ex
3028 global or v command, or ex or vi buffer execution, shall cause an
3029 informational message to be written. (For example, if 3 lines were
3030 added and 8 lines deleted during an ex visual command, 5 would be
3031 the number compared against the report edit option after the command
3032 completed.)
3033 scroll, scr
3035 [Default (number of lines in the display -1)/2]
3036 The value of the scroll edit option shall determine the number of lines
3038 scrolled by the ex <control>-D and z commands. For the vi <control>-D
3039 and <control>-U commands, it shall be the initial number of lines to
3040 scroll when no previous <control>-D or <control>-U command has been
3041 executed.
3042 sections
3044 [Default in the POSIX locale NHSHH HUnhsh]
3045 The sections edit option shall define additional section boundaries for
3047 the open and visual mode commands. The sections edit option can be set
3048 to a character string consisting of zero or more character pairs; it
3049 shall be an error to set it to an odd number of characters.
3050 shell, sh
3052 [Default from the environment variable SHELL ]
3053 The value of this option shall be a string. The default shall be taken
3055 from the SHELL environment variable. If the SHELL environment variable
3056 is null or empty, the sh (see sh ) utility shall be the default.
3057 shiftwidth, sw
3059 [Default 8]
3060 The value of this option shall give the width in columns of an indenta‐
3062 tion level used during autoindentation and by the shift commands ( <
3063 and >).
3064 showmatch, sm
3066 [Default unset]
3067 The functionality described for the showmatch edit option need not be
3069 supported on block-mode terminals or terminals with insufficient capa‐
3070 bilities.
3071 If showmatch is set, in open or visual mode, when a ')' or '}' is
3073 typed, if the matching '(' or '{' is currently visible on the display,
3074 the matching '(' or '{' shall be flagged moving the cursor to its loca‐
3075 tion for an unspecified amount of time.
3076 showmode
3078 [Default unset]
3079 If showmode is set, in open or visual mode, the current mode that the
3081 editor is in shall be displayed on the last line of the display. Com‐
3082 mand mode and text input mode shall be differentiated; other unspeci‐
3083 fied modes and implementation-defined information may be displayed.
3084 slowopen
3086 [Default unset]
3087 If slowopen is set during open and visual text input modes, the editor
3089 shall not update portions of the display other than those display line
3090 columns that display the characters entered by the user (see Input Mode
3091 Commands in vi ).
3092 tabstop, ts
3094 [Default 8]
3095 The value of this edit option shall specify the column boundary used by
3097 a <tab> in the display (see autoprint, ap and Input Mode Commands in vi
3098 ).
3099 taglength, tl
3101 [Default zero]
3102 The value of this edit option shall specify the maximum number of char‐
3104 acters that are considered significant in the user-specified tag name
3105 and in the tag name from the tags file. If the value is zero, all char‐
3106 acters in both tag names shall be significant.
3107 tags
3109 [Default see text]
3110 The value of this edit option shall be a string of <blank>-delimited
3112 pathnames of files used by the tag command. The default value is
3113 unspecified.
3114 term
3116 [Default from the environment variable TERM ]
3117 The value of this edit option shall be a string. The default shall be
3119 taken from the TERM variable in the environment. If the TERM environ‐
3120 ment variable is empty or null, the default is unspecified. The editor
3121 shall use the value of this edit option to determine the type of the
3122 display device.
3123 The results are unspecified if the user changes the value of the term
3125 edit option after editor initialization.
3126 terse
3128 [Default unset]
3129 If terse is set, error messages may be less verbose. However, except
3131 for this caveat, error messages are unspecified. Furthermore, not all
3132 error messages need change for different settings of this option.
3133 warn
3135 [Default set]
3136 If warn is set, and the contents of the edit buffer have been modified
3138 since they were last completely written, the editor shall write a warn‐
3139 ing message before certain ! commands (see Escape ).
3140 window
3142 [Default see text]
3143 A value used in open and visual mode, by the <control>-B and <con‐
3145 trol>-F commands, and, in visual mode, to specify the number of lines
3146 displayed when the screen is repainted.
3147 If the -w command-line option is not specified, the default value shall
3149 be set to the value of the LINES environment variable. If the LINES
3150 environment variable is empty or null, the default shall be the number
3151 of lines in the display minus 1.
3152 Setting the window edit option to zero or to a value greater than the
3154 number of lines in the display minus 1 (either explicitly or based on
3155 the -w option or the LINES environment variable) shall cause the window
3156 edit option to be set to the number of lines in the display minus 1.
3157 The baud rate of the terminal line may change the default in an imple‐
3159 mentation-defined manner.
3160 wrapmargin, wm
3162 [Default 0]
3163 If the value of this edit option is zero, it shall have no effect.
3165 If not in the POSIX locale, the effect of this edit option is implemen‐
3167 tation-defined.
3168 Otherwise, it shall specify a number of columns from the ending margin
3170 of the terminal.
3171 During open and visual text input modes, for each character for which
3173 any part of the character is displayed in a column that is less than
3174 wrapmargin columns from the ending margin of the display line, the edi‐
3175 tor shall behave as follows:
3176 1. If the character triggering this event is a <blank>, it, and all
3178 immediately preceding <blank>s on the current line entered during
3179 the execution of the current text input command, shall be dis‐
3180 carded, and the editor shall behave as if the user had entered a
3181 single <newline> instead. In addition, if the next user-entered
3182 character is a <space>, it shall be discarded as well.
3183 2. Otherwise, if there are one or more <blank>s on the current line
3185 immediately preceding the last group of inserted non- <blank>s
3186 which was entered during the execution of the current text input
3187 command, the <blank>s shall be replaced as if the user had entered
3188 a single <newline> instead.
3189 If the autoindent edit option is set, and the events described in 1. or
3191 2. are performed, any <blank>s at or after the cursor in the current
3192 line shall be discarded.
3193 The ending margin shall be determined by the system or overridden by
3195 the user, as described for COLUMNS in the ENVIRONMENT VARIABLES section
3196 and the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 8,
3197 Environment Variables.
3198 wrapscan, ws
3200 [Default set]
3201 If wrapscan is set, searches (the ex / or ? addresses, or open and
3203 visual mode /, ?, N, and n commands) shall wrap around the beginning or
3204 end of the edit buffer; when unset, searches shall stop at the begin‐
3205 ning or end of the edit buffer.
3206 writeany, wa
3208 [Default unset]
3209 If writeany is set, some of the checks performed when executing the ex
3211 write commands shall be inhibited, as described in editor option
3212 autowrite.
3213
3215 The following exit values shall be returned:
3216 0 Successful completion.
3218 >0 An error occurred.
3220
3223 When any error is encountered and the standard input is not a terminal
3224 device file, ex shall not write the file or return to command or text
3225 input mode, and shall terminate with a non-zero exit status.
3226 Otherwise, when an unrecoverable error is encountered, it shall be
3228 equivalent to a SIGHUP asynchronous event.
3229 Otherwise, when an error is encountered, the editor shall behave as
3231 specified in Command Line Parsing in ex .
3232 The following sections are informative.
3234
3236 If a SIGSEGV signal is received while ex is saving a file, the file
3237 might not be successfully saved.
3238 The next command can accept more than one file, so usage such as:
3240 next `ls [abc]*`
3243 is valid; it would not be valid for the edit or read commands, for
3245 example, because they expect only one file and unspecified results
3246 occur.
3247
3249 None.
3250
3252 The ex/ vi specification is based on the historical practice found in
3253 the 4 BSD and System V implementations of ex and vi. A freely redis‐
3254 tributable implementation of ex/ vi, which is tracking
3255 IEEE Std 1003.1-2001 fairly closely, and demonstrates the intended
3256 changes between historical implementations and IEEE Std 1003.1-2001,
3257 may be obtained by anonymous FTP from:
3258 ftp://ftp.rdg.opengroup.org/pub/mirrors/nvi
3261 A restricted editor (both the historical red utility and modifications
3263 to ex) were considered and rejected for inclusion. Neither option pro‐
3264 vided the level of security that users might expect.
3265 It is recognized that ex visual mode and related features would be dif‐
3267 ficult, if not impossible, to implement satisfactorily on a block-mode
3268 terminal, or a terminal without any form of cursor addressing; thus, it
3269 is not a mandatory requirement that such features should work on all
3270 terminals. It is the intention, however, that an ex implementation
3271 should provide the full set of capabilities on all terminals capable of
3272 supporting them.
3273 Options
3275 The -c replacement for + command was inspired by the -e option of sed.
3276 Historically, all such commands (see edit and next as well) were exe‐
3277 cuted from the last line of the edit buffer. This meant, for example,
3278 that "+/pattern" would fail unless the wrapscan option was set.
3279 IEEE Std 1003.1-2001 requires conformance to historical practice. His‐
3280 torically, some implementations restricted the ex commands that could
3281 be listed as part of the command line arguments. For consistency,
3282 IEEE Std 1003.1-2001 does not permit these restrictions.
3283 In historical implementations of the editor, the -R option (and the
3285 readonly edit option) only prevented overwriting of files; appending to
3286 files was still permitted, mapping loosely into the csh noclobber vari‐
3287 able. Some implementations, however, have not followed this semantic,
3288 and readonly does not permit appending either. IEEE Std 1003.1-2001
3289 follows the latter practice, believing that it is a more obvious and
3290 intuitive meaning of readonly.
3291 The -s option suppresses all interactive user feedback and is useful
3293 for editing scripts in batch jobs. The list of specific effects is his‐
3294 torical practice. The terminal type "incapable of supporting open and
3295 visual modes" has historically been named "dumb".
3296 The -t option was required because the ctags utility appears in
3298 IEEE Std 1003.1-2001 and the option is available in all historical
3299 implementations of ex.
3300 Historically, the ex and vi utilities accepted a -x option, which did
3302 encryption based on the algorithm found in the historical crypt util‐
3303 ity. The -x option for encryption, and the associated crypt utility,
3304 were omitted because the algorithm used was not specifiable and the
3305 export control laws of some nations make it difficult to export crypto‐
3306 graphic technology. In addition, it did not historically provide the
3307 level of security that users might expect.
3308 Standard Input
3310 An end-of-file condition is not equivalent to an end-of-file character.
3311 A common end-of-file character, <control>-D, is historically an ex com‐
3312 mand.
3313 There was no maximum line length in historical implementations of ex.
3315 Specifically, as it was parsed in chunks, the addresses had a different
3316 maximum length than the filenames. Further, the maximum line buffer
3317 size was declared as BUFSIZ, which was different lengths on different
3318 systems. This version selected the value of {LINE_MAX} to impose a rea‐
3319 sonable restriction on portable usage of ex and to aid test suite writ‐
3320 ers in their development of realistic tests that exercise this limit.
3321 Input Files
3323 It was an explicit decision by the standard developers that a <newline>
3324 be added to any file lacking one. It was believed that this feature of
3325 ex and vi was relied on by users in order to make text files lacking a
3326 trailing <newline> more portable. It is recognized that this will
3327 require a user-specified option or extension for implementations that
3328 permit ex and vi to edit files of type other than text if such files
3329 are not otherwise identified by the system. It was agreed that the
3330 ability to edit files of arbitrary type can be useful, but it was not
3331 considered necessary to mandate that an ex or vi implementation be
3332 required to handle files other than text files.
3333 The paragraph in the INPUT FILES section, "By default, ...", is
3335 intended to close a long-standing security problem in ex and vi; that
3336 of the "modeline" or "modelines" edit option. This feature allows any
3337 line in the first or last five lines of the file containing the strings
3338 "ex:" or "vi:" (and, apparently, "ei:" or "vx:" ) to be a line contain‐
3339 ing editor commands, and ex interprets all the text up to the next ':'
3340 or <newline> as a command. Consider the consequences, for example, of
3341 an unsuspecting user using ex or vi as the editor when replying to a
3342 mail message in which a line such as:
3343 ex:! rm -rf :
3346 appeared in the signature lines. The standard developers believed
3348 strongly that an editor should not by default interpret any lines of a
3349 file. Vendors are strongly urged to delete this feature from their
3350 implementations of ex and vi.
3351 Asynchronous Events
3353 The intention of the phrase "complete write" is that the entire edit
3354 buffer be written to stable storage. The note regarding temporary files
3355 is intended for implementations that use temporary files to back edit
3356 buffers unnamed by the user.
3357 Historically, SIGQUIT was ignored by ex, but was the equivalent of the
3359 Q command in visual mode; that is, it exited visual mode and entered ex
3360 mode. IEEE Std 1003.1-2001 permits, but does not require, this behav‐
3361 ior. Historically, SIGINT was often used by vi users to terminate text
3362 input mode ( <control>-C is often easier to enter than <ESC>). Some
3363 implementations of vi alerted the terminal on this event, and some did
3364 not. IEEE Std 1003.1-2001 requires that SIGINT behave identically to
3365 <ESC>, and that the terminal not be alerted.
3366 Historically, suspending the ex editor during text input mode was simi‐
3368 lar to SIGINT, as completed lines were retained, but any partial line
3369 discarded, and the editor returned to command mode.
3370 IEEE Std 1003.1-2001 is silent on this issue; implementations are
3371 encouraged to follow historical practice, where possible.
3372 Historically, the vi editor did not treat SIGTSTP as an asynchronous
3374 event, and it was therefore impossible to suspend the editor in visual
3375 text input mode. There are two major reasons for this. The first is
3376 that SIGTSTP is a broadcast signal on UNIX systems, and the chain of
3377 events where the shell execs an application that then execs vi usually
3378 caused confusion for the terminal state if SIGTSTP was delivered to the
3379 process group in the default manner. The second was that most implemen‐
3380 tations of the UNIX curses package are not reentrant, and the receipt
3381 of SIGTSTP at the wrong time will cause them to crash.
3382 IEEE Std 1003.1-2001 is silent on this issue; implementations are
3383 encouraged to treat suspension as an asynchronous event if possible.
3384 Historically, modifications to the edit buffer made before SIGINT
3386 interrupted an operation were retained; that is, anywhere from zero to
3387 all of the lines to be modified might have been modified by the time
3388 the SIGINT arrived. These changes were not discarded by the arrival of
3389 SIGINT. IEEE Std 1003.1-2001 permits this behavior, noting that the
3390 undo command is required to be able to undo these partially completed
3391 commands.
3392 The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and
3394 SIGTERM is unspecified because some implementations attempt to save the
3395 edit buffer in a useful state when other signals are received.
3396 Standard Error
3398 For ex/ vi, diagnostic messages are those messages reported as a result
3399 of a failed attempt to invoke ex or vi, such as invalid options or
3400 insufficient resources, or an abnormal termination condition. Diagnos‐
3401 tic messages should not be confused with the error messages generated
3402 by inappropriate or illegal user commands.
3403 Initialization in ex and vi
3405 If an ex command (other than cd, chdir, or source) has a filename argu‐
3406 ment, one or both of the alternate and current pathnames will be set.
3407 Informally, they are set as follows:
3408 1. If the ex command is one that replaces the contents of the edit
3410 buffer, and it succeeds, the current pathname will be set to the
3411 filename argument (the first filename argument in the case of the
3412 next command) and the alternate pathname will be set to the previ‐
3413 ous current pathname, if there was one.
3414 2. In the case of the file read/write forms of the read and write com‐
3416 mands, if there is no current pathname, the current pathname will
3417 be set to the filename argument.
3418 3. Otherwise, the alternate pathname will be set to the filename argu‐
3420 ment.
3421 For example, :edit foo and :recover foo, when successful, set the cur‐
3423 rent pathname, and, if there was a previous current pathname, the
3424 alternate pathname. The commands :write, !command, and :edit set nei‐
3425 ther the current or alternate pathnames. If the :edit foo command were
3426 to fail for some reason, the alternate pathname would be set. The read
3427 and write commands set the alternate pathname to their file argument,
3428 unless the current pathname is not set, in which case they set the cur‐
3429 rent pathname to their file arguments. The alternate pathname was not
3430 historically set by the :source command. IEEE Std 1003.1-2001 requires
3431 conformance to historical practice. Implementations adding commands
3432 that take filenames as arguments are encouraged to set the alternate
3433 pathname as described here.
3434 Historically, ex and vi read the .exrc file in the $HOME directory
3436 twice, if the editor was executed in the $HOME directory.
3437 IEEE Std 1003.1-2001 prohibits this behavior.
3438 Historically, the 4 BSD ex and vi read the $HOME and local .exrc files
3440 if they were owned by the real ID of the user, or the sourceany option
3441 was set, regardless of other considerations. This was a security prob‐
3442 lem because it is possible to put normal UNIX system commands inside a
3443 .exrc file. IEEE Std 1003.1-2001 does not specify the sourceany
3444 option, and historical implementations are encouraged to delete it.
3445 The .exrc files must be owned by the real ID of the user, and not
3447 writable by anyone other than the owner. The appropriate privileges
3448 exception is intended to permit users to acquire special privileges,
3449 but continue to use the .exrc files in their home directories.
3450 System V Release 3.2 and later vi implementations added the option
3452 [no]exrc. The behavior is that local .exrc files are read-only if the
3453 exrc option is set. The default for the exrc option was off, so by
3454 default, local .exrc files were not read. The problem this was
3455 intended to solve was that System V permitted users to give away files,
3456 so there is no possible ownership or writeability test to ensure that
3457 the file is safe. This is still a security problem on systems where
3458 users can give away files, but there is nothing additional that
3459 IEEE Std 1003.1-2001 can do. The implementation-defined exception is
3460 intended to permit groups to have local .exrc files that are shared by
3461 users, by creating pseudo-users to own the shared files.
3462 IEEE Std 1003.1-2001 does not mention system-wide ex and vi start-up
3464 files. While they exist in several implementations of ex and vi, they
3465 are not present in any implementations considered historical practice
3466 by IEEE Std 1003.1-2001. Implementations that have such files should
3467 use them only if they are owned by the real user ID or an appropriate
3468 user (for example, root on UNIX systems) and if they are not writable
3469 by any user other than their owner. System-wide start-up files should
3470 be read before the EXINIT variable, $HOME/.exrc, or local .exrc files
3471 are evaluated.
3472 Historically, any ex command could be entered in the EXINIT variable or
3474 the .exrc file, although ones requiring that the edit buffer already
3475 contain lines of text generally caused historical implementations of
3476 the editor to drop core. IEEE Std 1003.1-2001 requires that any ex com‐
3477 mand be permitted in the EXINIT variable and .exrc files, for simplic‐
3478 ity of specification and consistency, although many of them will obvi‐
3479 ously fail under many circumstances.
3480 The initialization of the contents of the edit buffer uses the phrase
3482 "the effect shall be" with regard to various ex commands. The intent of
3483 this phrase is that edit buffer contents loaded during the initializa‐
3484 tion phase not be lost; that is, loading the edit buffer should fail if
3485 the .exrc file read in the contents of a file and did not subsequently
3486 write the edit buffer. An additional intent of this phrase is to spec‐
3487 ify that the initial current line and column is set as specified for
3488 the individual ex commands.
3489 Historically, the -t option behaved as if the tag search were a + com‐
3491 mand; that is, it was executed from the last line of the file specified
3492 by the tag. This resulted in the search failing if the pattern was a
3493 forward search pattern and the wrapscan edit option was not set.
3494 IEEE Std 1003.1-2001 does not permit this behavior, requiring that the
3495 search for the tag pattern be performed on the entire file, and, if not
3496 found, that the current line be set to a more reasonable location in
3497 the file.
3498 Historically, the empty edit buffer presented for editing when a file
3500 was not specified by the user was unnamed. This is permitted by
3501 IEEE Std 1003.1-2001; however, implementations are encouraged to pro‐
3502 vide users a temporary filename for this buffer because it permits them
3503 the use of ex commands that use the current pathname during temporary
3504 edit sessions.
3505 Historically, the file specified using the -t option was not part of
3507 the current argument list. This practice is permitted by
3508 IEEE Std 1003.1-2001; however, implementations are encouraged to
3509 include its name in the current argument list for consistency.
3510 Historically, the -c command was generally not executed until a file
3512 that already exists was edited. IEEE Std 1003.1-2001 requires confor‐
3513 mance to this historical practice. Commands that could cause the -c
3514 command to be executed include the ex commands edit, next, recover,
3515 rewind, and tag, and the vi commands <control>-^ and <control>-]. His‐
3516 torically, reading a file into an edit buffer did not cause the -c com‐
3517 mand to be executed (even though it might set the current pathname)
3518 with the exception that it did cause the -c command to be executed if:
3519 the editor was in ex mode, the edit buffer had no current pathname, the
3520 edit buffer was empty, and no read commands had yet been attempted. For
3521 consistency and simplicity of specification, IEEE Std 1003.1-2001 does
3522 not permit this behavior.
3523 Historically, the -r option was the same as a normal edit session if
3525 there was no recovery information available for the file. This allowed
3526 users to enter:
3527 vi -r *.c
3530 and recover whatever files were recoverable. In some implementations,
3532 recovery was attempted only on the first file named, and the file was
3533 not entered into the argument list; in others, recovery was attempted
3534 for each file named. In addition, some historical implementations
3535 ignored -r if -t was specified or did not support command line file
3536 arguments with the -t option. For consistency and simplicity of speci‐
3537 fication, IEEE Std 1003.1-2001 disallows these special cases, and
3538 requires that recovery be attempted the first time each file is edited.
3539 Historically, vi initialized the ` and ' marks, but ex did not. This
3541 meant that if the first command in ex mode was visual or if an ex com‐
3542 mand was executed first (for example, vi +10 file), vi was entered
3543 without the marks being initialized. Because the standard developers
3544 believed the marks to be generally useful, and for consistency and sim‐
3545 plicity of specification, IEEE Std 1003.1-2001 requires that they
3546 always be initialized if in open or visual mode, or if in ex mode and
3547 the edit buffer is not empty. Not initializing it in ex mode if the
3548 edit buffer is empty is historical practice; however, it has always
3549 been possible to set (and use) marks in empty edit buffers in open and
3550 visual mode edit sessions.
3551 Addressing
3553 Historically, ex and vi accepted the additional addressing forms '\/'
3554 and '\?' . They were equivalent to "//" and "??" , respectively. They
3555 are not required by IEEE Std 1003.1-2001, mostly because nobody can
3556 remember whether they ever did anything different historically.
3557 Historically, ex and vi permitted an address of zero for several com‐
3559 mands, and permitted the % address in empty files for others. For con‐
3560 sistency, IEEE Std 1003.1-2001 requires support for the former in the
3561 few commands where it makes sense, and disallows it otherwise. In addi‐
3562 tion, because IEEE Std 1003.1-2001 requires that % be logically equiva‐
3563 lent to "1,$" , it is also supported where it makes sense and disal‐
3564 lowed otherwise.
3565 Historically, the % address could not be followed by further addresses.
3567 For consistency and simplicity of specification, IEEE Std 1003.1-2001
3568 requires that additional addresses be supported.
3569 All of the following are valid addresses:
3571 +++ Three lines after the current line.
3573 /re/- One line before the next occurrence of re.
3575 -2 Two lines before the current line.
3577 3 ---- 2
3579 Line one (note intermediate negative address).
3580 1 2 3 Line six.
3582 Any number of addresses can be provided to commands taking addresses;
3585 for example, "1,2,3,4,5p" prints lines 4 and 5, because two is the
3586 greatest valid number of addresses accepted by the print command. This,
3587 in combination with the semicolon delimiter, permits users to create
3588 commands based on ordered patterns in the file. For example, the com‐
3589 mand 3;/foo/;+2print will display the first line after line 3 that con‐
3590 tains the pattern foo, plus the next two lines. Note that the address
3591 3; must be evaluated before being discarded because the search origin
3592 for the /foo/ command depends on this.
3593 Historically, values could be added to addresses by including them
3595 after one or more <blank>s; for example, 3 - 5p wrote the seventh line
3596 of the file, and /foo/ 5 was the same as /foo/+5. However, only abso‐
3597 lute values could be added; for example, 5 /foo/ was an error.
3598 IEEE Std 1003.1-2001 requires conformance to historical practice.
3599 Address offsets are separately specified from addresses because they
3600 could historically be provided to visual mode search commands.
3601 Historically, any missing addresses defaulted to the current line.
3603 This was true for leading and trailing comma-delimited addresses, and
3604 for trailing semicolon-delimited addresses. For consistency,
3605 IEEE Std 1003.1-2001 requires it for leading semicolon addresses as
3606 well.
3607 Historically, ex and vi accepted the '^' character as both an address
3609 and as a flag offset for commands. In both cases it was identical to
3610 the '-' character. IEEE Std 1003.1-2001 does not require or prohibit
3611 this behavior.
3612 Historically, the enhancements to basic regular expressions could be
3614 used in addressing; for example, '~' , '\<' , and '\>' .
3615 IEEE Std 1003.1-2001 requires conformance to historical practice; that
3616 is, that regular expression usage be consistent, and that regular
3617 expression enhancements be supported wherever regular expressions are
3618 used.
3619 Command Line Parsing in ex
3621 Historical ex command parsing was even more complex than that described
3622 here. IEEE Std 1003.1-2001 requires the subset of the command parsing
3623 that the standard developers believed was documented and that users
3624 could reasonably be expected to use in a portable fashion, and that was
3625 historically consistent between implementations. (The discarded func‐
3626 tionality is obscure, at best.) Historical implementations will require
3627 changes in order to comply with IEEE Std 1003.1-2001; however, users
3628 are not expected to notice any of these changes. Most of the complexity
3629 in ex parsing is to handle three special termination cases:
3630 1. The !, global, v, and the filter versions of the read and write
3632 commands are delimited by <newline>s (they can contain vertical-
3633 line characters that are usually shell pipes).
3634 2. The ex, edit, next, and visual in open and visual mode commands all
3636 take ex commands, optionally containing vertical-line characters,
3637 as their first arguments.
3638 3. The s command takes a regular expression as its first argument, and
3640 uses the delimiting characters to delimit the command.
3641 Historically, vertical-line characters in the + command argument of the
3643 ex, edit, next, vi, and visual commands, and in the pattern and
3644 replacement parts of the s command, did not delimit the command, and in
3645 the filter cases for read and write, and the !, global, and v commands,
3646 they did not delimit the command at all. For example, the following
3647 commands are all valid:
3648 :edit +25 | s/abc/ABC/ file.c
3651 :s/ | /PIPE/
3652 :read !spell % | columnate
3653 :global/pattern/p | l
3654 :s/a/b/ | s/c/d | set
3655 Historically, empty or <blank> filled lines in .exrc files and sourced
3657 files (as well as EXINIT variables and ex command scripts) were treated
3658 as default commands; that is, print commands. IEEE Std 1003.1-2001
3659 specifically requires that they be ignored when encountered in .exrc
3660 and sourced files to eliminate a common source of new user error.
3661 Historically, ex commands with multiple adjacent (or <blank>-separated)
3663 vertical lines were handled oddly when executed from ex mode. For exam‐
3664 ple, the command ||| <carriage-return>, when the cursor was on line 1,
3665 displayed lines 2, 3, and 5 of the file. In addition, the command |
3666 would only display the line after the next line, instead of the next
3667 two lines. The former worked more logically when executed from vi mode,
3668 and displayed lines 2, 3, and 4. IEEE Std 1003.1-2001 requires the vi
3669 behavior; that is, a single default command and line number increment
3670 for each command separator, and trailing <newline>s after vertical-line
3671 separators are discarded.
3672 Historically, ex permitted a single extra colon as a leading command
3674 character; for example, :g/pattern/:p was a valid command.
3675 IEEE Std 1003.1-2001 generalizes this to require that any number of
3676 leading colon characters be stripped.
3677 Historically, any prefix of the delete command could be followed with‐
3679 out intervening <blank>s by a flag character because in the command
3680 d p, p is interpreted as the buffer p. IEEE Std 1003.1-2001 requires
3681 conformance to historical practice.
3682 Historically, the k command could be followed by the mark name without
3684 intervening <blank>s. IEEE Std 1003.1-2001 requires conformance to
3685 historical practice.
3686 Historically, the s command could be immediately followed by flag and
3688 option characters; for example, s/e/E/|s|sgc3p was a valid command.
3689 However, flag characters could not stand alone; for example, the com‐
3690 mands sp and s l would fail, while the command sgp and s gl would suc‐
3691 ceed. (Obviously, the '#' flag character was used as a delimiter char‐
3692 acter if it followed the command.) Another issue was that option char‐
3693 acters had to precede flag characters even when the command was fully
3694 specified; for example, the command s/e/E/pg would fail, while the com‐
3695 mand s/e/E/gp would succeed. IEEE Std 1003.1-2001 requires conformance
3696 to historical practice.
3697 Historically, the first command name that had a prefix matching the
3699 input from the user was the executed command; for example, ve, ver, and
3700 vers all executed the version command. Commands were in a specific
3701 order, however, so that a matched append, not abbreviate.
3702 IEEE Std 1003.1-2001 requires conformance to historical practice. The
3703 restriction on command search order for implementations with extensions
3704 is to avoid the addition of commands such that the historical prefixes
3705 would fail to work portably.
3706 Historical implementations of ex and vi did not correctly handle multi‐
3708 ple ex commands, separated by vertical-line characters, that entered or
3709 exited visual mode or the editor. Because implementations of vi exist
3710 that do not exhibit this failure mode, IEEE Std 1003.1-2001 does not
3711 permit it.
3712 The requirement that alphabetic command names consist of all following
3714 alphabetic characters up to the next non-alphabetic character means
3715 that alphabetic command names must be separated from their arguments by
3716 one or more non-alphabetic characters, normally a <blank> or '!' char‐
3717 acter, except as specified for the exceptions, the delete, k, and s
3718 commands.
3719 Historically, the repeated execution of the ex default print commands (
3721 <control>-D, eof, <newline>, <carriage-return>) erased any prompting
3722 character and displayed the next lines without scrolling the terminal;
3723 that is, immediately below any previously displayed lines. This pro‐
3724 vided a cleaner presentation of the lines in the file for the user.
3725 IEEE Std 1003.1-2001 does not require this behavior because it may be
3726 impossible in some situations; however, implementations are strongly
3727 encouraged to provide this semantic if possible.
3728 Historically, it was possible to change files in the middle of a com‐
3730 mand, and have the rest of the command executed in the new file; for
3731 example:
3732 :edit +25 file.c | s/abc/ABC/ | 1
3735 was a valid command, and the substitution was attempted in the newly
3737 edited file. IEEE Std 1003.1-2001 requires conformance to historical
3738 practice. The following commands are examples that exercise the ex
3739 parser:
3740 echo 'foo | bar' > file1; echo 'foo/bar' > file2;
3743 vi
3744 :edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\//SLASH/ | wq
3745 Historically, there was no protection in editor implementations to
3747 avoid ex global, v, @, or * commands changing edit buffers during exe‐
3748 cution of their associated commands. Because this would almost invari‐
3749 ably result in catastrophic failure of the editor, and implementations
3750 exist that do exhibit these problems, IEEE Std 1003.1-2001 requires
3751 that changing the edit buffer during a global or v command, or during a
3752 @ or * command for which there will be more than a single execution, be
3753 an error. Implementations supporting multiple edit buffers simultane‐
3754 ously are strongly encouraged to apply the same semantics to switching
3755 between buffers as well.
3756 The ex command quoting required by IEEE Std 1003.1-2001 is a superset
3758 of the quoting in historical implementations of the editor. For exam‐
3759 ple, it was not historically possible to escape a <blank> in a file‐
3760 name; for example, :edit foo\\\ bar would report that too many file‐
3761 names had been entered for the edit command, and there was no method of
3762 escaping a <blank> in the first argument of an edit, ex, next, or vis‐
3763 ual command at all. IEEE Std 1003.1-2001 extends historical practice,
3764 requiring that quoting behavior be made consistent across all ex com‐
3765 mands, except for the map, unmap, abbreviate, and unabbreviate com‐
3766 mands, which historically used <control>-V instead of backslashes for
3767 quoting. For those four commands, IEEE Std 1003.1-2001 requires con‐
3768 formance to historical practice.
3769 Backslash quoting in ex is non-intuitive. Backslash escapes are ignored
3771 unless they escape a special character; for example, when performing
3772 file argument expansion, the string "\\%" is equivalent to '\%' , not
3773 "\<current pathname>". This can be confusing for users because back‐
3774 slash is usually one of the characters that causes shell expansion to
3775 be performed, and therefore shell quoting rules must be taken into con‐
3776 sideration. Generally, quoting characters are only considered if they
3777 escape a special character, and a quoting character must be provided
3778 for each layer of parsing for which the character is special. As
3779 another example, only a single backslash is necessary for the '\l'
3780 sequence in substitute replacement patterns, because the character 'l'
3781 is not special to any parsing layer above it.
3782 <control>-V quoting in ex is slightly different from backslash quoting.
3784 In the four commands where <control>-V quoting applies ( abbreviate,
3785 unabbreviate, map, and unmap), any character may be escaped by a <con‐
3786 trol>-V whether it would have a special meaning or not.
3787 IEEE Std 1003.1-2001 requires conformance to historical practice.
3788 Historical implementations of the editor did not require delimiters
3790 within character classes to be escaped; for example, the command
3791 :s/[/]// on the string "xxx/yyy" would delete the '/' from the string.
3792 IEEE Std 1003.1-2001 disallows this historical practice for consistency
3793 and because it places a large burden on implementations by requiring
3794 that knowledge of regular expressions be built into the editor parser.
3795 Historically, quoting <newline>s in ex commands was handled inconsis‐
3797 tently. In most cases, the <newline> always terminated the command,
3798 regardless of any preceding escape character, because backslash charac‐
3799 ters did not escape <newline>s for most ex commands. However, some ex
3800 commands (for example, s, map, and abbreviation) permitted <newline>s
3801 to be escaped (although in the case of map and abbreviation, <con‐
3802 trol>-V characters escaped them instead of backslashes). This was true
3803 in not only the command line, but also .exrc and sourced files. For
3804 example, the command:
3805 map = foo<control-V><newline>bar
3808 would succeed, although it was sometimes difficult to get the <con‐
3810 trol>-V and the inserted <newline> passed to the ex parser. For consis‐
3811 tency and simplicity of specification, IEEE Std 1003.1-2001 requires
3812 that it be possible to escape <newline>s in ex commands at all times,
3813 using backslashes for most ex commands, and using <control>-V charac‐
3814 ters for the map and abbreviation commands. For example, the command
3815 print <newline> list is required to be parsed as the single command
3816 print <newline> list. While this differs from historical practice,
3817 IEEE Std 1003.1-2001 developers believed it unlikely that any script or
3818 user depended on the historical behavior.
3819 Historically, an error in a command specified using the -c option did
3821 not cause the rest of the -c commands to be discarded.
3822 IEEE Std 1003.1-2001 disallows this for consistency with mapped keys,
3823 the @, global, source, and v commands, the EXINIT environment variable,
3824 and the .exrc files.
3825 Input Editing in ex
3827 One of the common uses of the historical ex editor is over slow network
3828 connections. Editors that run in canonical mode can require far less
3829 traffic to and from, and far less processing on, the host machine, as
3830 well as more easily supporting block-mode terminals. For these reasons,
3831 IEEE Std 1003.1-2001 requires that ex be implemented using canonical
3832 mode input processing, as was done historically.
3833 IEEE Std 1003.1-2001 does not require the historical 4 BSD input edit‐
3835 ing characters "word erase" or "literal next". For this reason, it is
3836 unspecified how they are handled by ex, although they must have the
3837 required effect. Implementations that resolve them after the line has
3838 been ended using a <newline> or <control>-M character, and implementa‐
3839 tions that rely on the underlying system terminal support for this pro‐
3840 cessing, are both conforming. Implementations are strongly urged to use
3841 the underlying system functionality, if at all possible, for compati‐
3842 bility with other system text input interfaces.
3843 Historically, when the eof character was used to decrement the autoin‐
3845 dent level, the cursor moved to display the new end of the autoindent
3846 characters, but did not move the cursor to a new line, nor did it erase
3847 the <control>-D character from the line. IEEE Std 1003.1-2001 does not
3848 specify that the cursor remain on the same line or that the rest of the
3849 line is erased; however, implementations are strongly encouraged to
3850 provide the best possible user interface; that is, the cursor should
3851 remain on the same line, and any <control>-D character on the line
3852 should be erased.
3853 IEEE Std 1003.1-2001 does not require the historical 4 BSD input edit‐
3855 ing character "reprint", traditionally <control>-R, which redisplayed
3856 the current input from the user. For this reason, and because the func‐
3857 tionality cannot be implemented after the line has been terminated by
3858 the user, IEEE Std 1003.1-2001 makes no requirements about this func‐
3859 tionality. Implementations are strongly urged to make this historical
3860 functionality available, if possible.
3861 Historically, <control>-Q did not perform a literal next function in
3863 ex, as it did in vi. IEEE Std 1003.1-2001 requires conformance to his‐
3864 torical practice to avoid breaking historical ex scripts and .exrc
3865 files.
3866 eof
3868 Whether the eof character immediately modifies the autoindent charac‐
3869 ters in the prompt is left unspecified so that implementations can con‐
3870 form in the presence of systems that do not support this functionality.
3871 Implementations are encouraged to modify the line and redisplay it
3872 immediately, if possible.
3873 The specification of the handling of the eof character differs from
3875 historical practice only in that eof characters are not discarded if
3876 they follow normal characters in the text input. Historically, they
3877 were always discarded.
3878 Command Descriptions in ex
3880 Historically, several commands (for example, global, v, visual, s,
3881 write, wq, yank, !, <, >, &, and ~) were executable in empty files
3882 (that is, the default address(es) were 0), or permitted explicit
3883 addresses of 0 (for example, 0 was a valid address, or 0,0 was a valid
3884 range). Addresses of 0, or command execution in an empty file, make
3885 sense only for commands that add new text to the edit buffer or write
3886 commands (because users may wish to write empty files).
3887 IEEE Std 1003.1-2001 requires this behavior for such commands and dis‐
3888 allows it otherwise, for consistency and simplicity of specification.
3889 A count to an ex command has been historically corrected to be no
3891 greater than the last line in a file; for example, in a five-line file,
3892 the command 1,6print would fail, but the command 1print300 would suc‐
3893 ceed. IEEE Std 1003.1-2001 requires conformance to historical prac‐
3894 tice.
3895 Historically, the use of flags in ex commands could be obscure. Gen‐
3897 eral historical practice was as described by IEEE Std 1003.1-2001, but
3898 there were some special cases. For instance, the list, number, and
3899 print commands ignored trailing address offsets; for example, 3p +++#
3900 would display line 3, and 3 would be the current line after the execu‐
3901 tion of the command. The open and visual commands ignored both the
3902 trailing offsets and the trailing flags. Also, flags specified to the
3903 open and visual commands interacted badly with the list edit option,
3904 and setting and then unsetting it during the open/visual session would
3905 cause vi to stop displaying lines in the specified format. For consis‐
3906 tency and simplicity of specification, IEEE Std 1003.1-2001 does not
3907 permit any of these exceptions to the general rule.
3908 IEEE Std 1003.1-2001 uses the word copy in several places when dis‐
3910 cussing buffers. This is not intended to imply implementation.
3911 Historically, ex users could not specify numeric buffers because of the
3913 ambiguity this would cause; for example, in the command 3 delete 2, it
3914 is unclear whether 2 is a buffer name or a count. IEEE Std 1003.1-2001
3915 requires conformance to historical practice by default, but does not
3916 preclude extensions.
3917 Historically, the contents of the unnamed buffer were frequently dis‐
3919 carded after commands that did not explicitly affect it; for example,
3920 when using the edit command to switch files. For consistency and sim‐
3921 plicity of specification, IEEE Std 1003.1-2001 does not permit this
3922 behavior.
3923 The ex utility did not historically have access to the numeric buffers,
3925 and, furthermore, deleting lines in ex did not modify their contents.
3926 For example, if, after doing a delete in vi, the user switched to ex,
3927 did another delete, and then switched back to vi, the contents of the
3928 numeric buffers would not have changed. IEEE Std 1003.1-2001 requires
3929 conformance to historical practice. Numeric buffers are described in
3930 the ex utility in order to confine the description of buffers to a sin‐
3931 gle location in IEEE Std 1003.1-2001.
3932 The metacharacters that trigger shell expansion in file arguments match
3934 historical practice, as does the method for doing shell expansion.
3935 Implementations wishing to provide users with the flexibility to alter
3936 the set of metacharacters are encouraged to provide a shellmeta string
3937 edit option.
3938 Historically, ex commands executed from vi refreshed the screen when it
3940 did not strictly need to do so; for example, :!date > /dev/null does
3941 not require a screen refresh because the output of the UNIX date com‐
3942 mand requires only a single line of the screen. IEEE Std 1003.1-2001
3943 requires that the screen be refreshed if it has been overwritten, but
3944 makes no requirements as to how an implementation should make that
3945 determination. Implementations may prompt and refresh the screen
3946 regardless.
3947 Abbreviate
3949 Historical practice was that characters that were entered as part of an
3950 abbreviation replacement were subject to map expansions, the showmatch
3951 edit option, further abbreviation expansions, and so on; that is, they
3952 were logically pushed onto the terminal input queue, and were not a
3953 simple replacement. IEEE Std 1003.1-2001 requires conformance to his‐
3954 torical practice. Historical practice was that whenever a non-word
3955 character (that had not been escaped by a <control>-V) was entered
3956 after a word character, vi would check for abbreviations. The check was
3957 based on the type of the character entered before the word character of
3958 the word/non-word pair that triggered the check. The word character of
3959 the word/non-word pair that triggered the check and all characters
3960 entered before the trigger pair that were of that type were included in
3961 the check, with the exception of <blank>s, which always delimited the
3962 abbreviation.
3963 This means that, for the abbreviation to work, the lhs must end with a
3965 word character, there can be no transitions from word to non-word char‐
3966 acters (or vice versa) other than between the last and next-to-last
3967 characters in the lhs, and there can be no <blank>s in the lhs. In
3968 addition, because of the historical quoting rules, it was impossible to
3969 enter a literal <control>-V in the lhs. IEEE Std 1003.1-2001 requires
3970 conformance to historical practice. Historical implementations did not
3971 inform users when abbreviations that could never be used were entered;
3972 implementations are strongly encouraged to do so.
3973 For example, the following abbreviations will work:
3975 :ab (p REPLACE
3978 :ab p REPLACE
3979 :ab ((p REPLACE
3980 The following abbreviations will not work:
3982 :ab ( REPLACE
3985 :ab (pp REPLACE
3986 Historical practice is that words on the vi colon command line were
3988 subject to abbreviation expansion, including the arguments to the
3989 abbrev (and more interestingly) the unabbrev command. Because there are
3990 implementations that do not do abbreviation expansion for the first
3991 argument to those commands, this is permitted, but not required, by
3992 IEEE Std 1003.1-2001. However, the following sequence:
3993 :ab foo bar
3996 :ab foo baz
3997 resulted in the addition of an abbreviation of "baz" for the string
3999 "bar" in historical ex/ vi, and the sequence:
4000 :ab foo1 bar
4003 :ab foo2 bar
4004 :unabbreviate foo2
4005 deleted the abbreviation "foo1" , not "foo2" . These behaviors are not
4007 permitted by IEEE Std 1003.1-2001 because they clearly violate the
4008 expectations of the user.
4009 It was historical practice that <control>-V, not backslash, characters
4011 be interpreted as escaping subsequent characters in the abbreviate com‐
4012 mand. IEEE Std 1003.1-2001 requires conformance to historical practice;
4013 however, it should be noted that an abbreviation containing a <blank>
4014 will never work.
4015 Append
4017 Historically, any text following a vertical-line command separator
4018 after an append, change, or insert command became part of the insert
4019 text. For example, in the command:
4020 :g/pattern/append|stuff1
4023 a line containing the text "stuff1" would be appended to each line
4025 matching pattern. It was also historically valid to enter:
4026 :append|stuff1
4029 stuff2
4030 .
4031 and the text on the ex command line would be appended along with the
4033 text inserted after it. There was an historical bug, however, that the
4034 user had to enter two terminating lines (the '.' lines) to terminate
4035 text input mode in this case. IEEE Std 1003.1-2001 requires confor‐
4036 mance to historical practice, but disallows the historical need for
4037 multiple terminating lines.
4038 Change
4040 See the RATIONALE for the append command. Historical practice for cur‐
4041 sor positioning after the change command when no text is input, is as
4042 described in IEEE Std 1003.1-2001. However, one System V implementation
4043 is known to have been modified such that the cursor is positioned on
4044 the first address specified, and not on the line before the first
4045 address. IEEE Std 1003.1-2001 disallows this modification for consis‐
4046 tency.
4047 Historically, the change command did not support buffer arguments,
4049 although some implementations allow the specification of an optional
4050 buffer. This behavior is neither required nor disallowed by
4051 IEEE Std 1003.1-2001.
4052 Change Directory
4054 A common extension in ex implementations is to use the elements of a
4055 cdpath edit option as prefix directories for path arguments to chdir
4056 that are relative pathnames and that do not have '.' or ".." as their
4057 first component. Elements in the cdpath edit option are colon-sepa‐
4058 rated. The initial value of the cdpath edit option is the value of the
4059 shell CDPATH environment variable. This feature was not included in
4060 IEEE Std 1003.1-2001 because it does not exist in any of the implemen‐
4061 tations considered historical practice.
4062 Copy
4064 Historical implementations of ex permitted copies to lines inside of
4065 the specified range; for example, :2,5copy3 was a valid command.
4066 IEEE Std 1003.1-2001 requires conformance to historical practice.
4067 Delete
4069 IEEE Std 1003.1-2001 requires support for the historical parsing of a
4070 delete command followed by flags, without any intervening <blank>s. For
4071 example:
4072 1dp Deletes the first line and prints the line that was second.
4074 1delep As for 1dp.
4076 1d Deletes the first line, saving it in buffer p.
4078 1d p1l (Pee-one-ell.) Deletes the first line, saving it in buffer p,
4080 and listing the line that was second.
4081 Edit
4084 Historically, any ex command could be entered as a + command argument
4085 to the edit command, although some (for example, insert and append)
4086 were known to confuse historical implementations. For consistency and
4087 simplicity of specification, IEEE Std 1003.1-2001 requires that any
4088 command be supported as an argument to the edit command.
4089 Historically, the command argument was executed with the current line
4091 set to the last line of the file, regardless of whether the edit com‐
4092 mand was executed from visual mode or not. IEEE Std 1003.1-2001
4093 requires conformance to historical practice.
4094 Historically, the + command specified to the edit and next commands was
4096 delimited by the first <blank>, and there was no way to quote them. For
4097 consistency, IEEE Std 1003.1-2001 requires that the usual ex backslash
4098 quoting be provided.
4099 Historically, specifying the + command argument to the edit command
4101 required a filename to be specified as well; for example, :edit +100
4102 would always fail. For consistency and simplicity of specification,
4103 IEEE Std 1003.1-2001 does not permit this usage to fail for that rea‐
4104 son.
4105 Historically, only the cursor position of the last file edited was
4107 remembered by the editor. IEEE Std 1003.1-2001 requires that this be
4108 supported; however, implementations are permitted to remember and
4109 restore the cursor position for any file previously edited.
4110 File
4112 Historical versions of the ex editor file command displayed a current
4113 line and number of lines in the edit buffer of 0 when the file was
4114 empty, while the vi <control>-G command displayed a current line and
4115 number of lines in the edit buffer of 1 in the same situation.
4116 IEEE Std 1003.1-2001 does not permit this discrepancy, instead requir‐
4117 ing that a message be displayed indicating that the file is empty.
4118 Global
4120 The two-pass operation of the global and v commands is not intended to
4121 imply implementation, only the required result of the operation.
4122 The current line and column are set as specified for the individual ex
4124 commands. This requirement is cumulative; that is, the current line and
4125 column must track across all the commands executed by the global or v
4126 commands.
4127 Insert
4129 See the RATIONALE for the append command.
4130 Historically, insert could not be used with an address of zero; that
4132 is, not when the edit buffer was empty. IEEE Std 1003.1-2001 requires
4133 that this command behave consistently with the append command.
4134 Join
4136 The action of the join command in relation to the special characters is
4137 only defined for the POSIX locale because the correct amount of white
4138 space after a period varies; in Japanese none is required, in French
4139 only a single space, and so on.
4140 List
4142 The historical output of the list command was potentially ambiguous.
4143 The standard developers believed correcting this to be more important
4144 than adhering to historical practice, and IEEE Std 1003.1-2001 requires
4145 unambiguous output.
4146 Map
4148 Historically, command mode maps only applied to command names; for
4149 example, if the character 'x' was mapped to 'y' , the command fx
4150 searched for the 'x' character, not the 'y' character.
4151 IEEE Std 1003.1-2001 requires this behavior. Historically, entering
4152 <control>-V as the first character of a vi command was an error. Sev‐
4153 eral implementations have extended the semantics of vi such that <con‐
4154 trol>-V means that the subsequent command character is not mapped. This
4155 is permitted, but not required, by IEEE Std 1003.1-2001. Regardless,
4156 using <control>-V to escape the second or later character in a sequence
4157 of characters that might match a map command, or any character in text
4158 input mode, is historical practice, and stops the entered keys from
4159 matching a map. IEEE Std 1003.1-2001 requires conformance to historical
4160 practice.
4161 Historical implementations permitted digits to be used as a map command
4163 lhs, but then ignored the map. IEEE Std 1003.1-2001 requires that the
4164 mapped digits not be ignored.
4165 The historical implementation of the map command did not permit map
4167 commands that were more than a single character in length if the first
4168 character was printable. This behavior is permitted, but not required,
4169 by IEEE Std 1003.1-2001.
4170 Historically, mapped characters were remapped unless the remap edit
4172 option was not set, or the prefix of the mapped characters matched the
4173 mapping characters; for example, in the map:
4174 :map ab abcd
4177 the characters "ab" were used as is and were not remapped, but the
4179 characters "cd" were mapped if appropriate. This can cause infinite
4180 loops in the vi mapping mechanisms. IEEE Std 1003.1-2001 requires con‐
4181 formance to historical practice, and that such loops be interruptible.
4182 Text input maps had the same problems with expanding the lhs for the ex
4184 map! and unmap! command as did the ex abbreviate and unabbreviate com‐
4185 mands. See the RATIONALE for the ex abbreviate command.
4186 IEEE Std 1003.1-2001 requires similar modification of some historical
4187 practice for the map and unmap commands, as described for the abbrevi‐
4188 ate and unabbreviate commands.
4189 Historically, maps that were subsets of other maps behaved differently
4191 depending on the order in which they were defined. For example:
4192 :map! ab short
4195 :map! abc long
4196 would always translate the characters "ab" to "short" , regardless of
4198 how fast the characters "abc" were entered. If the entry order was
4199 reversed:
4200 :map! abc long
4203 :map! ab short
4204 the characters "ab" would cause the editor to pause, waiting for the
4206 completing 'c' character, and the characters might never be mapped to
4207 "short" . For consistency and simplicity of specification,
4208 IEEE Std 1003.1-2001 requires that the shortest match be used at all
4209 times.
4210 The length of time the editor spends waiting for the characters to com‐
4212 plete the lhs is unspecified because the timing capabilities of systems
4213 are often inexact and variable, and it may depend on other factors such
4214 as the speed of the connection. The time should be long enough for the
4215 user to be able to complete the sequence, but not long enough for the
4216 user to have to wait. Some implementations of vi have added a keytime
4217 option, which permits users to set the number of 0,1 seconds the editor
4218 waits for the completing characters. Because mapped terminal function
4219 and cursor keys tend to start with an <ESC> character, and <ESC> is the
4220 key ending vi text input mode, maps starting with <ESC> characters are
4221 generally exempted from this timeout period, or, at least timed out
4222 differently.
4223 Mark
4225 Historically, users were able to set the "previous context" marks
4226 explicitly. In addition, the ex commands " and '` and the vi commands
4227 ", ``, `', and '` all referred to the same mark. In addition, the pre‐
4228 vious context marks were not set if the command, with which the address
4229 setting the mark was associated, failed. IEEE Std 1003.1-2001 requires
4230 conformance to historical practice. Historically, if marked lines were
4231 deleted, the mark was also deleted, but would reappear if the change
4232 was undone. IEEE Std 1003.1-2001 requires conformance to historical
4233 practice.
4234 The description of the special events that set the ` and ' marks
4236 matches historical practice. For example, historically the command
4237 /a/,/b/ did not set the ` and ' marks, but the command /a/,/b/delete
4238 did.
4239 Next
4241 Historically, any ex command could be entered as a + command argument
4242 to the next command, although some (for example, insert and append)
4243 were known to confuse historical implementations. IEEE Std 1003.1-2001
4244 requires that any command be permitted and that it behave as specified.
4245 The next command can accept more than one file, so usage such as:
4246 next `ls [abc] `
4249 is valid; it need not be valid for the edit or read commands, for exam‐
4251 ple, because they expect only one filename.
4252 Historically, the next command behaved differently from the :rewind
4254 command in that it ignored the force flag if the autowrite flag was
4255 set. For consistency, IEEE Std 1003.1-2001 does not permit this behav‐
4256 ior.
4257 Historically, the next command positioned the cursor as if the file had
4259 never been edited before, regardless. IEEE Std 1003.1-2001 does not
4260 permit this behavior, for consistency with the edit command.
4261 Implementations wanting to provide a counterpart to the next command
4263 that edited the previous file have used the command prev[ious], which
4264 takes no file argument. IEEE Std 1003.1-2001 does not require this com‐
4265 mand.
4266 Open
4268 Historically, the open command would fail if the open edit option was
4269 not set. IEEE Std 1003.1-2001 does not mention the open edit option and
4270 does not require this behavior. Some historical implementations do not
4271 permit entering open mode from open or visual mode, only from ex mode.
4272 For consistency, IEEE Std 1003.1-2001 does not permit this behavior.
4273 Historically, entering open mode from the command line (that is, vi
4275 +open) resulted in anomalous behaviors; for example, the ex file and
4276 set commands, and the vi command <control>-G did not work. For consis‐
4277 tency, IEEE Std 1003.1-2001 does not permit this behavior.
4278 Historically, the open command only permitted '/' characters to be used
4280 as the search pattern delimiter. For consistency, IEEE Std 1003.1-2001
4281 requires that the search delimiters used by the s, global, and v com‐
4282 mands be accepted as well.
4283 Preserve
4285 The preserve command does not historically cause the file to be consid‐
4286 ered unmodified for the purposes of future commands that may exit the
4287 editor. IEEE Std 1003.1-2001 requires conformance to historical prac‐
4288 tice.
4289 Historical documentation stated that mail was not sent to the user when
4291 preserve was executed; however, historical implementations did send
4292 mail in this case. IEEE Std 1003.1-2001 requires conformance to the
4293 historical implementations.
4294 Print
4296 The writing of NUL by the print command is not specified as a special
4297 case because the standard developers did not want to require ex to sup‐
4298 port NUL characters. Historically, characters were displayed using the
4299 ARPA standard mappings, which are as follows:
4300 1. Printable characters are left alone.
4302 2. Control characters less than \177 are represented as '^' followed
4304 by the character offset from the '@' character in the ASCII map;
4305 for example, \007 is represented as '^G' .
4306 3. \177 is represented as '^' followed by '?' .
4308 The display of characters having their eighth bit set was less stan‐
4310 dard. Existing implementations use hex (0x00), octal (\000), and a
4311 meta-bit display. (The latter displayed bytes that had their eighth bit
4312 set as the two characters "M-" followed by the seven-bit display as
4313 described above.) The latter probably has the best claim to historical
4314 practice because it was used for the -v option of 4 BSD and 4 BSD-
4315 derived versions of the cat utility since 1980.
4316 No specific display format is required by IEEE Std 1003.1-2001.
4318 Explicit dependence on the ASCII character set has been avoided where
4320 possible, hence the use of the phrase an "implementation-defined multi-
4321 character sequence" for the display of non-printable characters in
4322 preference to the historical usage of, for instance, "^I" for the
4323 <tab>. Implementations are encouraged to conform to historical practice
4324 in the absence of any strong reason to diverge.
4325 Historically, all ex commands beginning with the letter 'p' could be
4327 entered using capitalized versions of the commands; for example,
4328 P[rint], Pre[serve], and Pu[t] were all valid command names.
4329 IEEE Std 1003.1-2001 permits, but does not require, this historical
4330 practice because capital forms of the commands are used by some imple‐
4331 mentations for other purposes.
4332 Put
4334 Historically, an ex put command, executed from open or visual mode, was
4335 the same as the open or visual mode P command, if the buffer was named
4336 and was cut in character mode, and the same as the p command if the
4337 buffer was named and cut in line mode. If the unnamed buffer was the
4338 source of the text, the entire line from which the text was taken was
4339 usually put, and the buffer was handled as if in line mode, but it was
4340 possible to get extremely anomalous behavior. In addition, using the Q
4341 command to switch into ex mode, and then doing a put often resulted in
4342 errors as well, such as appending text that was unrelated to the (sup‐
4343 posed) contents of the buffer. For consistency and simplicity of speci‐
4344 fication, IEEE Std 1003.1-2001 does not permit these behaviors. All ex
4345 put commands are required to operate in line mode, and the contents of
4346 the buffers are not altered by changing the mode of the editor.
4347 Read
4349 Historically, an ex read command executed from open or visual mode,
4350 executed in an empty file, left an empty line as the first line of the
4351 file. For consistency and simplicity of specification,
4352 IEEE Std 1003.1-2001 does not permit this behavior. Historically, a
4353 read in open or visual mode from a program left the cursor at the last
4354 line read in, not the first. For consistency, IEEE Std 1003.1-2001 does
4355 not permit this behavior.
4356 Historical implementations of ex were unable to undo read commands that
4358 read from the output of a program. For consistency,
4359 IEEE Std 1003.1-2001 does not permit this behavior.
4360 Historically, the ex and vi message after a successful read or write
4362 command specified "characters", not "bytes". IEEE Std 1003.1-2001
4363 requires that the number of bytes be displayed, not the number of char‐
4364 acters, because it may be difficult in multi-byte implementations to
4365 determine the number of characters read. Implementations are encouraged
4366 to clarify the message displayed to the user.
4367 Historically, reads were not permitted on files other than type regu‐
4369 lar, except that FIFO files could be read (probably only because they
4370 did not exist when ex and vi were originally written). Because the his‐
4371 torical ex evaluated read! and read ! equivalently, there can be no
4372 optional way to force the read. IEEE Std 1003.1-2001 permits, but does
4373 not require, this behavior.
4374 Recover
4376 Some historical implementations of the editor permitted users to
4377 recover the edit buffer contents from a previous edit session, and then
4378 exit without saving those contents (or explicitly discarding them). The
4379 intent of IEEE Std 1003.1-2001 in requiring that the edit buffer be
4380 treated as already modified is to prevent this user error.
4381 Rewind
4383 Historical implementations supported the rewind command when the user
4384 was editing the first file in the list; that is, the file that the
4385 rewind command would edit. IEEE Std 1003.1-2001 requires conformance to
4386 historical practice.
4387 Substitute
4389 Historically, ex accepted an r option to the s command. The effect of
4390 the r option was to use the last regular expression used in any command
4391 as the pattern, the same as the ~ command. The r option is not required
4392 by IEEE Std 1003.1-2001. Historically, the c and g options were tog‐
4393 gled; for example, the command :s/abc/def/ was the same as
4394 s/abc/def/ccccgggg. For simplicity of specification,
4395 IEEE Std 1003.1-2001 does not permit this behavior.
4396 The tilde command is often used to replace the last search RE. For
4398 example, in the sequence:
4399 s/red/blue/
4402 /green
4403 ~
4404 the ~ command is equivalent to:
4406 s/green/blue/
4409 Historically, ex accepted all of the following forms:
4411 s/abc/def/
4414 s/abc/def
4415 s/abc/
4416 s/abc
4417 IEEE Std 1003.1-2001 requires conformance to this historical practice.
4419 The s command presumes that the '^' character only occupies a single
4421 column in the display. Much of the ex and vi specification presumes
4422 that the <space> only occupies a single column in the display. There
4423 are no known character sets for which this is not true.
4424 Historically, the final column position for the substitute commands was
4426 based on previous column movements; a search for a pattern followed by
4427 a substitution would leave the column position unchanged, while a 0
4428 command followed by a substitution would change the column position to
4429 the first non- <blank>. For consistency and simplicity of specifica‐
4430 tion, IEEE Std 1003.1-2001 requires that the final column position
4431 always be set to the first non- <blank>.
4432 Set
4434 Historical implementations redisplayed all of the options for each
4435 occurrence of the all keyword. IEEE Std 1003.1-2001 permits, but does
4436 not require, this behavior.
4437 Tag
4439 No requirement is made as to where ex and vi shall look for the file
4440 referenced by the tag entry. Historical practice has been to look for
4441 the path found in the tags file, based on the current directory. A
4442 useful extension found in some implementations is to look based on the
4443 directory containing the tags file that held the entry, as well. No
4444 requirement is made as to which reference for the tag in the tags file
4445 is used. This is deliberate, in order to permit extensions such as mul‐
4446 tiple entries in a tags file for a tag.
4447 Because users often specify many different tags files, some of which
4449 need not be relevant or exist at any particular time,
4450 IEEE Std 1003.1-2001 requires that error messages about problem tags
4451 files be displayed only if the requested tag is not found, and then,
4452 only once for each time that the tag edit option is changed.
4453 The requirement that the current edit buffer be unmodified is only nec‐
4455 essary if the file indicated by the tag entry is not the same as the
4456 current file (as defined by the current pathname). Historically, the
4457 file would be reloaded if the filename had changed, as well as if the
4458 filename was different from the current pathname. For consistency and
4459 simplicity of specification, IEEE Std 1003.1-2001 does not permit this
4460 behavior, requiring that the name be the only factor in the decision.
4461 Historically, vi only searched for tags in the current file from the
4463 current cursor to the end of the file, and therefore, if the wrapscan
4464 option was not set, tags occurring before the current cursor were not
4465 found. IEEE Std 1003.1-2001 considers this a bug, and implementations
4466 are required to search for the first occurrence in the file, regard‐
4467 less.
4468 Undo
4470 The undo description deliberately uses the word "modified". The undo
4471 command is not intended to undo commands that replace the contents of
4472 the edit buffer, such as edit, next, tag, or recover.
4473 Cursor positioning after the undo command was inconsistent in the his‐
4475 torical vi, sometimes attempting to restore the original cursor posi‐
4476 tion ( global, undo, and v commands), and sometimes, in the presence of
4477 maps, placing the cursor on the last line added or changed instead of
4478 the first. IEEE Std 1003.1-2001 requires a simplified behavior for con‐
4479 sistency and simplicity of specification.
4480 Version
4482 The version command cannot be exactly specified since there is no
4483 widely-accepted definition of what the version information should con‐
4484 tain. Implementations are encouraged to do something reasonably intel‐
4485 ligent.
4486 Write
4488 Historically, the ex and vi message after a successful read or write
4489 command specified "characters", not "bytes". IEEE Std 1003.1-2001
4490 requires that the number of bytes be displayed, not the number of char‐
4491 acters because it may be difficult in multi-byte implementations to
4492 determine the number of characters written. Implementations are encour‐
4493 aged to clarify the message displayed to the user.
4494 Implementation-defined tests are permitted so that implementations can
4496 make additional checks; for example, for locks or file modification
4497 times.
4498 Historically, attempting to append to a nonexistent file caused an
4500 error. It has been left unspecified in IEEE Std 1003.1-2001 to permit
4501 implementations to let the write succeed, so that the append semantics
4502 are similar to those of the historical csh.
4503 Historical vi permitted empty edit buffers to be written. However,
4505 since the way vi got around dealing with "empty" files was to always
4506 have a line in the edit buffer, no matter what, it wrote them as files
4507 of a single, empty line. IEEE Std 1003.1-2001 does not permit this
4508 behavior.
4509 Historically, ex restored standard output and standard error to their
4511 values as of when ex was invoked, before writes to programs were per‐
4512 formed. This could disturb the terminal configuration as well as be a
4513 security issue for some terminals. IEEE Std 1003.1-2001 does not per‐
4514 mit this, requiring that the program output be captured and displayed
4515 as if by the ex print command.
4516 Adjust Window
4518 Historically, the line count was set to the value of the scroll option
4519 if the type character was end-of-file. This feature was broken on most
4520 historical implementations long ago, however, and is not documented
4521 anywhere. For this reason, IEEE Std 1003.1-2001 is resolutely silent.
4522 Historically, the z command was <blank>-sensitive and z + and z - did
4524 different things than z+ and z- because the type could not be distin‐
4525 guished from a flag. (The commands z . and z = were historically
4526 invalid.) IEEE Std 1003.1-2001 requires conformance to this historical
4527 practice.
4528 Historically, the z command was further <blank>-sensitive in that the
4530 count could not be <blank>-delimited; for example, the commands z= 5
4531 and z- 5 were also invalid. Because the count is not ambiguous with
4532 respect to either the type character or the flags, this is not permit‐
4533 ted by IEEE Std 1003.1-2001.
4534 Escape
4536 Historically, ex filter commands only read the standard output of the
4537 commands, letting standard error appear on the terminal as usual. The
4538 vi utility, however, read both standard output and standard error.
4539 IEEE Std 1003.1-2001 requires the latter behavior for both ex and vi,
4540 for consistency.
4541 Shift Left and Shift Right
4543 Historically, it was possible to add shift characters to increase the
4544 effect of the command; for example, <<< outdented (or >>> indented) the
4545 lines 3 levels of indentation instead of the default 1.
4546 IEEE Std 1003.1-2001 requires conformance to historical practice.
4547 <control>-D
4549 Historically, the <control>-D command erased the prompt, providing the
4550 user with an unbroken presentation of lines from the edit buffer. This
4551 is not required by IEEE Std 1003.1-2001; implementations are encouraged
4552 to provide it if possible. Historically, the <control>-D command took,
4553 and then ignored, a count. IEEE Std 1003.1-2001 does not permit this
4554 behavior.
4555 Write Line Number
4557 Historically, the ex = command, when executed in ex mode in an empty
4558 edit buffer, reported 0, and from open or visual mode, reported 1. For
4559 consistency and simplicity of specification, IEEE Std 1003.1-2001 does
4560 not permit this behavior.
4561 Execute
4563 Historically, ex did not correctly handle the inclusion of text input
4564 commands (that is, append, insert, and change) in executed buffers.
4565 IEEE Std 1003.1-2001 does not permit this exclusion for consistency.
4566 Historically, the logical contents of the buffer being executed did not
4568 change if the buffer itself were modified by the commands being exe‐
4569 cuted; that is, buffer execution did not support self-modifying code.
4570 IEEE Std 1003.1-2001 requires conformance to historical practice.
4571 Historically, the @ command took a range of lines, and the @ buffer was
4573 executed once per line, with the current line ( '.' ) set to each spec‐
4574 ified line. IEEE Std 1003.1-2001 requires conformance to historical
4575 practice.
4576 Some historical implementations did not notice if errors occurred dur‐
4578 ing buffer execution. This, coupled with the ability to specify a range
4579 of lines for the ex @ command, makes it trivial to cause them to drop
4580 core. IEEE Std 1003.1-2001 requires that implementations stop buffer
4581 execution if any error occurs, if the specified line doesn't exist, or
4582 if the contents of the edit buffer itself are replaced (for example,
4583 the buffer executes the ex :edit command).
4584 Regular Expressions in ex
4586 Historical practice is that the characters in the replacement part of
4587 the last s command-that is, those matched by entering a '~' in the reg‐
4588 ular expression-were not further expanded by the regular expression
4589 engine. So, if the characters contained the string "a.," they would
4590 match 'a' followed by ".," and not 'a' followed by any character.
4591 IEEE Std 1003.1-2001 requires conformance to historical practice.
4592 Edit Options in ex
4594 The following paragraphs describe the historical behavior of some edit
4595 options that were not, for whatever reason, included in
4596 IEEE Std 1003.1-2001. Implementations are strongly encouraged to only
4597 use these names if the functionality described here is fully supported.
4598 extended
4600 The extended edit option has been used in some implementations
4601 of vi to provide extended regular expressions instead of basic
4602 regular expressions This option was omitted from
4603 IEEE Std 1003.1-2001 because it is not widespread historical
4604 practice.
4605 flash The flash edit option historically caused the screen to flash
4607 instead of beeping on error. This option was omitted from
4608 IEEE Std 1003.1-2001 because it is not found in some historical
4609 implementations.
4610 hardtabs
4612 The hardtabs edit option historically defined the number of col‐
4613 umns between hardware tab settings. This option was omitted from
4614 IEEE Std 1003.1-2001 because it was believed to no longer be
4615 generally useful.
4616 modeline
4618 The modeline (sometimes named modelines) edit option histori‐
4619 cally caused ex or vi to read the five first and last lines of
4620 the file for editor commands. This option is a security problem,
4621 and vendors are strongly encouraged to delete it from historical
4622 implementations.
4623 open The open edit option historically disallowed the ex open and
4625 visual commands. This edit option was omitted because these com‐
4626 mands are required by IEEE Std 1003.1-2001.
4627 optimize
4629 The optimize edit option historically expedited text throughput
4630 by setting the terminal to not do automatic <carriage-return>s
4631 when printing more than one logical line of output. This option
4632 was omitted from IEEE Std 1003.1-2001 because it was intended
4633 for terminals without addressable cursors, which are rarely, if
4634 ever, still used.
4635 ruler The ruler edit option has been used in some implementations of
4637 vi to present a current row/column ruler for the user. This
4638 option was omitted from IEEE Std 1003.1-2001 because it is not
4639 widespread historical practice.
4640 sourceany
4642 The sourceany edit option historically caused ex or vi to source
4643 start-up files that were owned by users other than the user run‐
4644 ning the editor. This option is a security problem, and vendors
4645 are strongly encouraged to remove it from their implementations.
4646 timeout
4648 The timeout edit option historically enabled the (now standard)
4649 feature of only waiting for a short period before returning keys
4650 that could be part of a macro. This feature was omitted from
4651 IEEE Std 1003.1-2001 because its behavior is now standard, it is
4652 not widely useful, and it was rarely documented.
4653 verbose
4655 The verbose edit option has been used in some implementations of
4656 vi to cause vi to output error messages for common errors; for
4657 example, attempting to move the cursor past the beginning or end
4658 of the line instead of only alerting the screen. (The historical
4659 vi only alerted the terminal and presented no message for such
4660 errors. The historical editor option terse did not select when
4661 to present error messages, it only made existing error messages
4662 more or less verbose.) This option was omitted from
4663 IEEE Std 1003.1-2001 because it is not widespread historical
4664 practice; however, implementors are encouraged to use it if they
4665 wish to provide error messages for naive users.
4666 wraplen
4668 The wraplen edit option has been used in some implementations of
4669 vi to specify an automatic margin measured from the left margin
4670 instead of from the right margin. This is useful when multiple
4671 screen sizes are being used to edit a single file. This option
4672 was omitted from IEEE Std 1003.1-2001 because it is not wide‐
4673 spread historical practice; however, implementors are encouraged
4674 to use it if they add this functionality.
4675 autoindent, ai
4678 Historically, the command 0a did not do any autoindentation, regardless
4679 of the current indentation of line 1. IEEE Std 1003.1-2001 requires
4680 that any indentation present in line 1 be used.
4681 autoprint, ap
4683 Historically, the autoprint edit option was not completely consistent
4684 or based solely on modifications to the edit buffer. Exceptions were
4685 the read command (when reading from a file, but not from a filter), the
4686 append, change, insert, global, and v commands, all of which were not
4687 affected by autoprint, and the tag command, which was affected by auto‐
4688 print. IEEE Std 1003.1-2001 requires conformance to historical prac‐
4689 tice.
4690 Historically, the autoprint option only applied to the last of multiple
4692 commands entered using vertical-bar delimiters; for example, delete
4693 <newline> was affected by autoprint, but delete|version <newline> was
4694 not. IEEE Std 1003.1-2001 requires conformance to historical practice.
4695 autowrite, aw
4697 Appending the '!' character to the ex next command to avoid performing
4698 an automatic write was not supported in historical implementations.
4699 IEEE Std 1003.1-2001 requires that the behavior match the other ex com‐
4700 mands for consistency.
4701 ignorecase, ic
4703 Historical implementations of case-insensitive matching (the ignorecase
4704 edit option) lead to counterintuitive situations when uppercase charac‐
4705 ters were used in range expressions. Historically, the process was as
4706 follows:
4707 1. Take a line of text from the edit buffer.
4709 2. Convert uppercase to lowercase in text line.
4711 3. Convert uppercase to lowercase in regular expressions, except in
4713 character class specifications.
4714 4. Match regular expressions against text.
4716 This would mean that, with ignorecase in effect, the text:
4718 The cat sat on the mat
4721 would be matched by
4723 /^the/
4726 but not by:
4728 /^[A-Z]he/
4731 For consistency with other commands implementing regular expressions,
4733 IEEE Std 1003.1-2001 does not permit this behavior.
4734 paragraphs, para
4736 The ISO POSIX-2:1993 standard made the default paragraphs and sections
4737 edit options implementation-defined, arguing they were historically
4738 oriented to the UNIX system troff text formatter, and a "portable user"
4739 could use the {, }, [[, ]], (, and ) commands in open or visual mode
4740 and have the cursor stop in unexpected places. IEEE Std 1003.1-2001
4741 specifies their values in the POSIX locale because the unusual grouping
4742 (they only work when grouped into two characters at a time) means that
4743 they cannot be used for general-purpose movement, regardless.
4744 readonly
4746 Implementations are encouraged to provide the best possible information
4747 to the user as to the read-only status of the file, with the exception
4748 that they should not consider the current special privileges of the
4749 process. This provides users with a safety net because they must force
4750 the overwrite of read-only files, even when running with additional
4751 privileges.
4752 The readonly edit option specification largely conforms to historical
4754 practice. The only difference is that historical implementations did
4755 not notice that the user had set the readonly edit option in cases
4756 where the file was already marked read-only for some reason, and would
4757 therefore reinitialize the readonly edit option the next time the con‐
4758 tents of the edit buffer were replaced. This behavior is disallowed by
4759 IEEE Std 1003.1-2001.
4760 report
4762 The requirement that lines copied to a buffer interact differently than
4763 deleted lines is historical practice. For example, if the report edit
4764 option is set to 3, deleting 3 lines will cause a report to be written,
4765 but 4 lines must be copied before a report is written.
4766 The requirement that the ex global, v, open, undo, and visual commands
4768 present reports based on the total number of lines added or deleted
4769 during the command execution, and that commands executed by the global
4770 and v commands not present reports, is historical practice.
4771 IEEE Std 1003.1-2001 extends historical practice by requiring that buf‐
4772 fer execution be treated similarly. The reasons for this are two-fold.
4773 Historically, only the report by the last command executed from the
4774 buffer would be seen by the user, as each new report would overwrite
4775 the last. In addition, the standard developers believed that buffer
4776 execution had more in common with global and v commands than it did
4777 with other ex commands, and should behave similarly, for consistency
4778 and simplicity of specification.
4779 showmatch, sm
4781 The length of time the cursor spends on the matching character is
4782 unspecified because the timing capabilities of systems are often inex‐
4783 act and variable. The time should be long enough for the user to
4784 notice, but not long enough for the user to become annoyed. Some imple‐
4785 mentations of vi have added a matchtime option that permits users to
4786 set the number of 0,1 second intervals the cursor pauses on the match‐
4787 ing character.
4788 showmode
4790 The showmode option has been used in some historical implementations of
4791 ex and vi to display the current editing mode when in open or visual
4792 mode. The editing modes have generally included "command" and "input",
4793 and sometimes other modes such as "replace" and "change". The string
4794 was usually displayed on the bottom line of the screen at the far
4795 right-hand corner. In addition, a preceding '*' character often
4796 denoted whether the contents of the edit buffer had been modified. The
4797 latter display has sometimes been part of the showmode option, and
4798 sometimes based on another option. This option was not available in the
4799 4 BSD historical implementation of vi, but was viewed as generally use‐
4800 ful, particularly to novice users, and is required by
4801 IEEE Std 1003.1-2001.
4802 The smd shorthand for the showmode option was not present in all his‐
4804 torical implementations of the editor. IEEE Std 1003.1-2001 requires
4805 it, for consistency.
4806 Not all historical implementations of the editor displayed a mode
4808 string for command mode, differentiating command mode from text input
4809 mode by the absence of a mode string. IEEE Std 1003.1-2001 permits this
4810 behavior for consistency with historical practice, but implementations
4811 are encouraged to provide a display string for both modes.
4812 slowopen
4814 Historically the slowopen option was automatically set if the terminal
4815 baud rate was less than 1200 baud, or if the baud rate was 1200 baud
4816 and the redraw option was not set. The slowopen option had two effects.
4817 First, when inserting characters in the middle of a line, characters
4818 after the cursor would not be pushed ahead, but would appear to be
4819 overwritten. Second, when creating a new line of text, lines after the
4820 current line would not be scrolled down, but would appear to be over‐
4821 written. In both cases, ending text input mode would cause the screen
4822 to be refreshed to match the actual contents of the edit buffer.
4823 Finally, terminals that were sufficiently intelligent caused the editor
4824 to ignore the slowopen option. IEEE Std 1003.1-2001 permits most his‐
4825 torical behavior, extending historical practice to require slowopen
4826 behaviors if the edit option is set by the user.
4827 tags
4829 The default path for tags files is left unspecified as implementations
4830 may have their own tags implementations that do not correspond to the
4831 historical ones. The default tags option value should probably at least
4832 include the file ./tags.
4833 term
4835 Historical implementations of ex and vi ignored changes to the term
4836 edit option after the initial terminal information was loaded. This is
4837 permitted by IEEE Std 1003.1-2001; however, implementations are encour‐
4838 aged to permit the user to modify their terminal type at any time.
4839 terse
4841 Historically, the terse edit option optionally provided a shorter, less
4842 descriptive error message, for some error messages. This is permitted,
4843 but not required, by IEEE Std 1003.1-2001. Historically, most common
4844 visual mode errors (for example, trying to move the cursor past the end
4845 of a line) did not result in an error message, but simply alerted the
4846 terminal. Implementations wishing to provide messages for novice users
4847 are urged to do so based on the edit option verbose, and not terse.
4848 window
4850 In historical implementations, the default for the window edit option
4851 was based on the baud rate as follows:
4852 1. If the baud rate was less than 1200, the edit option w300 set the
4854 window value; for example, the line:
4855 set w300=12
4858 would set the window option to 12 if the baud rate was less than 1200.
4860 2. If the baud rate was equal to 1200, the edit option w1200 set the
4862 window value.
4863 3. If the baud rate was greater than 1200, the edit option w9600 set
4865 the window value.
4866 The w300, w1200, and w9600 options do not appear in
4868 IEEE Std 1003.1-2001 because of their dependence on specific baud
4869 rates.
4870 In historical implementations, the size of the window displayed by var‐
4872 ious commands was related to, but not necessarily the same as, the win‐
4873 dow edit option. For example, the size of the window was set by the ex
4874 command visual 10, but it did not change the value of the window edit
4875 option. However, changing the value of the window edit option did
4876 change the number of lines that were displayed when the screen was
4877 repainted. IEEE Std 1003.1-2001 does not permit this behavior in the
4878 interests of consistency and simplicity of specification, and requires
4879 that all commands that change the number of lines that are displayed do
4880 it by setting the value of the window edit option.
4881 wrapmargin, wm
4883 Historically, the wrapmargin option did not affect maps inserting char‐
4884 acters that also had associated counts; for example :map K 5aABC DEF.
4885 Unfortunately, there are widely used maps that depend on this behavior.
4886 For consistency and simplicity of specification, IEEE Std 1003.1-2001
4887 does not permit this behavior.
4888 Historically, wrapmargin was calculated using the column display width
4890 of all characters on the screen. For example, an implementation using
4891 "^I" to represent <tab>s when the list edit option was set, where '^'
4892 and 'I' each took up a single column on the screen, would calculate the
4893 wrapmargin based on a value of 2 for each <tab>. The number edit option
4894 similarly changed the effective length of the line as well.
4895 IEEE Std 1003.1-2001 requires conformance to historical practice.
4896
4898 None.
4899
4901 Command Search and Execution , ctags , ed , sed , sh , stty , vi , the
4902 System Interfaces volume of IEEE Std 1003.1-2001, access()
4903
4905 Portions of this text are reprinted and reproduced in electronic form
4906 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4907 -- Portable Operating System Interface (POSIX), The Open Group Base
4908 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
4909 Electrical and Electronics Engineers, Inc and The Open Group. In the
4910 event of any discrepancy between this version and the original IEEE and
4911 The Open Group Standard, the original IEEE and The Open Group Standard
4912 is the referee document. The original Standard can be obtained online
4913 at http://www.opengroup.org/unix/online.html .
4914IEEE/The Open Group 2003 EX(P)