1EX(1P) POSIX Programmer's Manual EX(1P)
2
3
4
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 ex — text editor
13
15 ex [-rR] [-s|-v] [-c command] [-t tagstring] [-w size] [file...]
16
18 The ex utility is a line-oriented text editor. There are two other
19 modes of the editor—open and visual—in which screen-oriented editing is
20 available. This is described more fully by the ex open and visual com‐
21 mands and in vi.
22
23 If an operand is '-', the results are unspecified.
24
25 This section uses the term edit buffer to describe the current working
26 text. No specific implementation is implied by this term. All editing
27 changes are performed on the edit buffer, and no changes to it shall
28 affect any file until an editor command writes the file.
29
30 Certain terminals do not have all the capabilities necessary to support
31 the complete ex definition, such as the full-screen editing commands
32 (visual mode or open mode). When these commands cannot be supported on
33 such terminals, this condition shall not produce an error message such
34 as ``not an editor command'' or report a syntax error. The implementa‐
35 tion may either accept the commands and produce results on the screen
36 that are the result of an unsuccessful attempt to meet the requirements
37 of this volume of POSIX.1‐2017 or report an error describing the termi‐
38 nal-related deficiency.
39
41 The ex utility shall conform to the Base Definitions volume of
42 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines, except for the
43 unspecified usage of '-', and that '+' may be recognized as an option
44 delimiter as well as '-'.
45
46 The following options shall be supported:
47
48 -c command
49 Specify an initial command to be executed in the first edit
50 buffer loaded from an existing file (see the EXTENDED
51 DESCRIPTION section). Implementations may support more than
52 a single -c option. In such implementations, the specified
53 commands shall be executed in the order specified on the com‐
54 mand line.
55
56 -r Recover the named files (see the EXTENDED DESCRIPTION sec‐
57 tion). Recovery information for a file shall be saved during
58 an editor or system crash (for example, when the editor is
59 terminated by a signal which the editor can catch), or after
60 the use of an ex preserve command.
61
62 A crash in this context is an unexpected failure of the sys‐
63 tem or utility that requires restarting the failed system or
64 utility. A system crash implies that any utilities running at
65 the time also crash. In the case of an editor or system
66 crash, the number of changes to the edit buffer (since the
67 most recent preserve command) that will be recovered is
68 unspecified.
69
70 If no file operands are given and the -t option is not speci‐
71 fied, all other options, the EXINIT variable, and any .exrc
72 files shall be ignored; a list of all recoverable files
73 available to the invoking user shall be written, and the edi‐
74 tor shall exit normally without further action.
75
76 -R Set readonly edit option.
77
78 -s Prepare ex for batch use by taking the following actions:
79
80 * Suppress writing prompts and informational (but not diag‐
81 nostic) messages.
82
83 * Ignore the value of TERM and any implementation default
84 terminal type and assume the terminal is a type incapable
85 of supporting open or visual modes; see the visual com‐
86 mand and the description of vi.
87
88 * Suppress the use of the EXINIT environment variable and
89 the reading of any .exrc file; see the EXTENDED DESCRIP‐
90 TION section.
91
92 * Suppress autoindentation, ignoring the value of the
93 autoindent edit option.
94
95 -t tagstring
96 Edit the file containing the specified tagstring; see ctags.
97 The tags feature represented by -t tagstring and the tag com‐
98 mand is optional. It shall be provided on any system that
99 also provides a conforming implementation of ctags; other‐
100 wise, the use of -t produces undefined results. On any sys‐
101 tem, it shall be an error to specify more than a single -t
102 option.
103
104 -v Begin in visual mode (see vi).
105
106 -w size Set the value of the window editor option to size.
107
109 The following operand shall be supported:
110
111 file A pathname of a file to be edited.
112
114 The standard input consists of a series of commands and input text, as
115 described in the EXTENDED DESCRIPTION section. The implementation may
116 limit each line of standard input to a length of {LINE_MAX}.
117
118 If the standard input is not a terminal device, it shall be as if the
119 -s option had been specified.
120
121 If a read from the standard input returns an error, or if the editor
122 detects an end-of-file condition from the standard input, it shall be
123 equivalent to a SIGHUP asynchronous event.
124
126 Input files shall be text files or files that would be text files
127 except for an incomplete last line that is not longer than {LINE_MAX}-1
128 bytes in length and contains no NUL characters. By default, any incom‐
129 plete last line shall be treated as if it had a trailing <newline>.
130 The editing of other forms of files may optionally be allowed by ex
131 implementations.
132
133 The .exrc files and source files shall be text files consisting of ex
134 commands; see the EXTENDED DESCRIPTION section.
135
136 By default, the editor shall read lines from the files to be edited
137 without interpreting any of those lines as any form of editor command.
138
140 The following environment variables shall affect the execution of ex:
141
142 COLUMNS Override the system-selected horizontal screen size. See the
143 Base Definitions volume of POSIX.1‐2017, Chapter 8, Environ‐
144 ment Variables for valid values and results when it is unset
145 or null.
146
147 EXINIT Determine a list of ex commands that are executed on editor
148 start-up. See the EXTENDED DESCRIPTION section for more
149 details of the initialization phase.
150
151 HOME Determine a pathname of a directory that shall be searched
152 for an editor start-up file named .exrc; see the EXTENDED
153 DESCRIPTION section.
154
155 LANG Provide a default value for the internationalization vari‐
156 ables that are unset or null. (See the Base Definitions vol‐
157 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
158 ables for the precedence of internationalization variables
159 used to determine the values of locale categories.)
160
161 LC_ALL If set to a non-empty string value, override the values of
162 all the other internationalization variables.
163
164 LC_COLLATE
165 Determine the locale for the behavior of ranges, equivalence
166 classes, and multi-character collating elements within regu‐
167 lar expressions.
168
169 LC_CTYPE Determine the locale for the interpretation of sequences of
170 bytes of text data as characters (for example, single-byte as
171 opposed to multi-byte characters in arguments and input
172 files), the behavior of character classes within regular
173 expressions, the classification of characters as uppercase or
174 lowercase letters, the case conversion of letters, and the
175 detection of word boundaries.
176
177 LC_MESSAGES
178 Determine the locale that should be used to affect the format
179 and contents of diagnostic messages written to standard
180 error.
181
182 LINES Override the system-selected vertical screen size, used as
183 the number of lines in a screenful and the vertical screen
184 size in visual mode. See the Base Definitions volume of
185 POSIX.1‐2017, Chapter 8, Environment Variables for valid val‐
186 ues and results when it is unset or null.
187
188 NLSPATH Determine the location of message catalogs for the processing
189 of LC_MESSAGES.
190
191 PATH Determine the search path for the shell command specified in
192 the ex editor commands !, shell, read, and write, and the
193 open and visual mode command !; see the description of com‐
194 mand search and execution in Section 2.9.1.1, Command Search
195 and Execution.
196
197 SHELL Determine the preferred command line interpreter for use as
198 the default value of the shell edit option.
199
200 TERM Determine the name of the terminal type. If this variable is
201 unset or null, an unspecified default terminal type shall be
202 used.
203
205 The following term is used in this and following sections to specify
206 command and asynchronous event actions:
207
208 complete write
209 A complete write is a write of the entire contents of the
210 edit buffer to a file of a type other than a terminal device,
211 or the saving of the edit buffer caused by the user executing
212 the ex preserve command. Writing the contents of the edit
213 buffer to a temporary file that will be removed when the edi‐
214 tor exits shall not be considered a complete write.
215
216 The following actions shall be taken upon receipt of signals:
217
218 SIGINT If the standard input is not a terminal device, ex shall not
219 write the file or return to command or text input mode, and
220 shall exit with a non-zero exit status.
221
222 Otherwise, if executing an open or visual text input mode
223 command, ex in receipt of SIGINT shall behave identically to
224 its receipt of the <ESC> character.
225
226 Otherwise:
227
228 1. If executing an ex text input mode command, all input
229 lines that have been completely entered shall be resolved
230 into the edit buffer, and any partially entered line
231 shall be discarded.
232
233 2. If there is a currently executing command, it shall be
234 aborted and a message displayed. Unless otherwise speci‐
235 fied by the ex or vi command descriptions, it is unspeci‐
236 fied whether any lines modified by the executing command
237 appear modified, or as they were before being modified by
238 the executing command, in the buffer.
239
240 If the currently executing command was a motion command,
241 its associated command shall be discarded.
242
243 3. If in open or visual command mode, the terminal shall be
244 alerted.
245
246 4. The editor shall then return to command mode.
247
248 SIGCONT The screen shall be refreshed if in open or visual mode.
249
250 SIGHUP If the edit buffer has been modified since the last complete
251 write, ex shall attempt to save the edit buffer so that it
252 can be recovered later using the -r option or the ex recover
253 command. The editor shall not write the file or return to
254 command or text input mode, and shall terminate with a non-
255 zero exit status.
256
257 SIGTERM Refer to SIGHUP.
258
259 The action taken for all other signals is unspecified.
260
262 The standard output shall be used only for writing prompts to the user,
263 for informational messages, and for writing lines from the file.
264
266 The standard error shall be used only for diagnostic messages.
267
269 The output from ex shall be text files.
270
272 Only the ex mode of the editor is described in this section. See vi for
273 additional editing capabilities available in ex.
274
275 When an error occurs, ex shall write a message. If the terminal sup‐
276 ports a standout mode (such as inverse video), the message shall be
277 written in standout mode. If the terminal does not support a standout
278 mode, and the edit option errorbells is set, an alert action shall pre‐
279 cede the error message.
280
281 By default, ex shall start in command mode, which shall be indicated by
282 a : prompt; see the prompt command. Text input mode can be entered by
283 the append, insert, or change commands; it can be exited (and command
284 mode re-entered) by typing a <period> ('.') alone at the beginning of
285 a line.
286
287 Initialization in ex and vi
288 The following symbols are used in this and following sections to spec‐
289 ify locations in the edit buffer:
290
291 alternate and current pathnames
292 Two pathnames, named current and alternate, are maintained by the
293 editor. Any ex commands that take filenames as arguments shall
294 set them as follows:
295
296 1. If a file argument is specified to the ex edit, ex, or
297 recover commands, or if an ex tag command replaces the con‐
298 tents of the edit buffer.
299
300 a. If the command replaces the contents of the edit buffer,
301 the current pathname shall be set to the file argument or
302 the file indicated by the tag, and the alternate pathname
303 shall be set to the previous value of the current path‐
304 name.
305
306 b. Otherwise, the alternate pathname shall be set to the
307 file argument.
308
309 2. If a file argument is specified to the ex next command:
310
311 a. If the command replaces the contents of the edit buffer,
312 the current pathname shall be set to the first file argu‐
313 ment, and the alternate pathname shall be set to the pre‐
314 vious value of the current pathname.
315
316 3. If a file argument is specified to the ex file command, the
317 current pathname shall be set to the file argument, and the
318 alternate pathname shall be set to the previous value of the
319 current pathname.
320
321 4. If a file argument is specified to the ex read and write com‐
322 mands (that is, when reading or writing a file, and not to
323 the program named by the shell edit option), or a file argu‐
324 ment is specified to the ex xit command:
325
326 a. If the current pathname has no value, the current path‐
327 name shall be set to the file argument.
328
329 b. Otherwise, the alternate pathname shall be set to the
330 file argument.
331
332 If the alternate pathname is set to the previous value of the
333 current pathname when the current pathname had no previous value,
334 then the alternate pathname shall have no value as a result.
335
336 current line
337 The line of the edit buffer referenced by the cursor. Each com‐
338 mand description specifies the current line after the command has
339 been executed, as the current line value. When the edit buffer
340 contains no lines, the current line shall be zero; see Addressing
341 in ex.
342
343 current column
344 The current display line column occupied by the cursor. (The col‐
345 umns shall be numbered beginning at 1.) Each command description
346 specifies the current column after the command has been executed,
347 as the current column value. This column is an ideal column that
348 is remembered over the lifetime of the editor. The actual display
349 line column upon which the cursor rests may be different from the
350 current column; see the cursor positioning discussion in Command
351 Descriptions in vi.
352
353 set to non-<blank>
354 A description for a current column value, meaning that the cur‐
355 rent column shall be set to the last display line column on which
356 is displayed any part of the first non-<blank> of the line. If
357 the line has no non-<blank> non-<newline> characters, the current
358 column shall be set to the last display line column on which is
359 displayed any part of the last non-<newline> character in the
360 line. If the line is empty, the current column shall be set to
361 column position 1.
362
363 The length of lines in the edit buffer may be limited to {LINE_MAX}
364 bytes. In open and visual mode, the length of lines in the edit buffer
365 may be limited to the number of characters that will fit in the dis‐
366 play. If either limit is exceeded during editing, an error message
367 shall be written. If either limit is exceeded by a line read in from a
368 file, an error message shall be written and the edit session may be
369 terminated.
370
371 If the editor stops running due to any reason other than a user com‐
372 mand, and the edit buffer has been modified since the last complete
373 write, it shall be equivalent to a SIGHUP asynchronous event. If the
374 system crashes, it shall be equivalent to a SIGHUP asynchronous event.
375
376 During initialization (before the first file is copied into the edit
377 buffer or any user commands from the terminal are processed) the fol‐
378 lowing shall occur:
379
380 1. If the environment variable EXINIT is set, the editor shall execute
381 the ex commands contained in that variable.
382
383 2. If the EXINIT variable is not set, and all of the following are
384 true:
385
386 a. The HOME environment variable is not null and not empty.
387
388 b. The file .exrc in the directory referred to by the HOME envi‐
389 ronment variable:
390
391 i. Exists
392
393 ii. Is owned by the same user ID as the real user ID of the
394 process or the process has appropriate privileges
395
396 iii. Is not writable by anyone other than the owner
397
398 the editor shall execute the ex commands contained in that file.
399
400 3. If and only if all of the following are true:
401
402 a. The current directory is not referred to by the HOME environ‐
403 ment variable.
404
405 b. A command in the EXINIT environment variable or a command in
406 the .exrc file in the directory referred to by the HOME envi‐
407 ronment variable sets the editor option exrc.
408
409 c. The .exrc file in the current directory:
410
411 i. Exists
412
413 ii. Is owned by the same user ID as the real user ID of the
414 process, or by one of a set of implementation-defined user
415 IDs
416
417 iii. Is not writable by anyone other than the owner
418
419 the editor shall attempt to execute the ex commands contained in
420 that file.
421
422 Lines in any .exrc file that are blank lines shall be ignored. If any
423 .exrc file exists, but is not read for ownership or permission reasons,
424 it shall be an error.
425
426 After the EXINIT variable and any .exrc files are processed, the first
427 file specified by the user shall be edited, as follows:
428
429 1. If the user specified the -t option, the effect shall be as if the
430 ex tag command was entered with the specified argument, with the
431 exception that if tag processing does not result in a file to edit,
432 the effect shall be as described in step 3. below.
433
434 2. Otherwise, if the user specified any command line file arguments,
435 the effect shall be as if the ex edit command was entered with the
436 first of those arguments as its file argument.
437
438 3. Otherwise, the effect shall be as if the ex edit command was
439 entered with a nonexistent filename as its file argument. It is
440 unspecified whether this action shall set the current pathname. In
441 an implementation where this action does not set the current path‐
442 name, any editor command using the current pathname shall fail
443 until an editor command sets the current pathname.
444
445 If the -r option was specified, the first time a file in the initial
446 argument list or a file specified by the -t option is edited, if recov‐
447 ery information has previously been saved about it, that information
448 shall be recovered and the editor shall behave as if the contents of
449 the edit buffer have already been modified. If there are multiple
450 instances of the file to be recovered, the one most recently saved
451 shall be recovered, and an informational message that there are previ‐
452 ous versions of the file that can be recovered shall be written. If no
453 recovery information about a file is available, an informational mes‐
454 sage to this effect shall be written, and the edit shall proceed as
455 usual.
456
457 If the -c option was specified, the first time a file that already
458 exists (including a file that might not exist but for which recovery
459 information is available, when the -r option is specified) replaces or
460 initializes the contents of the edit buffer, the current line shall be
461 set to the last line of the edit buffer, the current column shall be
462 set to non-<blank>, and the ex commands specified with the -c option
463 shall be executed. In this case, the current line and current column
464 shall not be set as described for the command associated with the
465 replacement or initialization of the edit buffer contents. However, if
466 the -t option or a tag command is associated with this action, the -c
467 option commands shall be executed and then the movement to the tag
468 shall be performed.
469
470 The current argument list shall initially be set to the filenames spec‐
471 ified by the user on the command line. If no filenames are specified by
472 the user, the current argument list shall be empty. If the -t option
473 was specified, it is unspecified whether any filename resulting from
474 tag processing shall be prepended to the current argument list. In the
475 case where the filename is added as a prefix to the current argument
476 list, the current argument list reference shall be set to that file‐
477 name. In the case where the filename is not added as a prefix to the
478 current argument list, the current argument list reference shall logi‐
479 cally be located before the first of the filenames specified on the
480 command line (for example, a subsequent ex next command shall edit the
481 first filename from the command line). If the -t option was not speci‐
482 fied, the current argument list reference shall be to the first of the
483 filenames on the command line.
484
485 Addressing in ex
486 Addressing in ex relates to the current line and the current column;
487 the address of a line is its 1-based line number, the address of a col‐
488 umn is its 1-based count from the beginning of the line. Generally, the
489 current line is the last line affected by a command. The current line
490 number is the address of the current line. In each command description,
491 the effect of the command on the current line number and the current
492 column is described.
493
494 Addresses are constructed as follows:
495
496 1. The character '.' (period) shall address the current line.
497
498 2. The character '$' shall address the last line of the edit buffer.
499
500 3. The positive decimal number n shall address the nth line of the
501 edit buffer.
502
503 4. The address "'x" refers to the line marked with the mark name char‐
504 acter 'x', which shall be a lowercase letter from the portable
505 character set, the backquote character, or the single-quote charac‐
506 ter. It shall be an error if the line that was marked is not cur‐
507 rently present in the edit buffer or the mark has not been set.
508 Lines can be marked with the ex mark or k commands, or the vi m
509 command.
510
511 5. A regular expression enclosed by <slash> characters ('/') shall
512 address the first line found by searching forwards from the line
513 following the current line toward the end of the edit buffer and
514 stopping at the first line for which the line excluding the termi‐
515 nating <newline> matches the regular expression. As stated in Regu‐
516 lar Expressions in ex, an address consisting of a null regular
517 expression delimited by <slash> characters ("//") shall address the
518 next line for which the line excluding the terminating <newline>
519 matches the last regular expression encountered. In addition, the
520 second <slash> can be omitted at the end of a command line. If the
521 wrapscan edit option is set, the search shall wrap around to the
522 beginning of the edit buffer and continue up to and including the
523 current line, so that the entire edit buffer is searched. Within
524 the regular expression, the sequence "\/" shall represent a literal
525 <slash> instead of the regular expression delimiter.
526
527 6. A regular expression enclosed in <question-mark> characters ('?')
528 shall address the first line found by searching backwards from the
529 line preceding the current line toward the beginning of the edit
530 buffer and stopping at the first line for which the line excluding
531 the terminating <newline> matches the regular expression. An
532 address consisting of a null regular expression delimited by <ques‐
533 tion-mark> characters ("??") shall address the previous line for
534 which the line excluding the terminating <newline> matches the last
535 regular expression encountered. In addition, the second <question-
536 mark> can be omitted at the end of a command line. If the wrapscan
537 edit option is set, the search shall wrap around from the beginning
538 of the edit buffer to the end of the edit buffer and continue up to
539 and including the current line, so that the entire edit buffer is
540 searched. Within the regular expression, the sequence "\?" shall
541 represent a literal <question-mark> instead of the RE delimiter.
542
543 7. A <plus-sign> ('+') or a <hyphen-minus> ('-') followed by a decimal
544 number shall address the current line plus or minus the number. A
545 '+' or '-' not followed by a decimal number shall address the cur‐
546 rent line plus or minus 1.
547
548 Addresses can be followed by zero or more address offsets, optionally
549 <blank>-separated. Address offsets are constructed as follows:
550
551 1. A '+' or '-' immediately followed by a decimal number shall add
552 (subtract) the indicated number of lines to (from) the address. A
553 '+' or '-' not followed by a decimal number shall add (subtract) 1
554 to (from) the address.
555
556 2. A decimal number shall add the indicated number of lines to the
557 address.
558
559 It shall not be an error for an intermediate address value to be less
560 than zero or greater than the last line in the edit buffer. It shall be
561 an error for the final address value to be less than zero or greater
562 than the last line in the edit buffer.
563
564 Commands take zero, one, or two addresses; see the descriptions of
565 1addr and 2addr in Command Descriptions in ex. If more than the
566 required number of addresses are provided to a command that requires
567 zero addresses, it shall be an error. Otherwise, if more than the
568 required number of addresses are provided to a command, the addresses
569 specified first shall be evaluated and then discarded until the maximum
570 number of valid addresses remain.
571
572 Addresses shall be separated from each other by a <comma> (',') or a
573 <semicolon> (';'). If no address is specified before or after a
574 <comma> or <semicolon> separator, it shall be as if the address of the
575 current line was specified before or after the separator. In the case
576 of a <semicolon> separator, the current line ('.') shall be set to the
577 first address, and only then will the next address be calculated. This
578 feature can be used to determine the starting line for forwards and
579 backwards searches (see rules 5. and 6.).
580
581 A <percent-sign> ('%') shall be equivalent to entering the two
582 addresses "1,$".
583
584 Any delimiting <blank> characters between addresses, address separa‐
585 tors, or address offsets shall be discarded.
586
587 Command Line Parsing in ex
588 The following symbol is used in this and following sections to describe
589 parsing behavior:
590
591 escape If a character is referred to as ``<backslash>-escaped'' or
592 ``<control>‐V-escaped'', it shall mean that the character
593 acquired or lost a special meaning by virtue of being pre‐
594 ceded, respectively, by a <backslash> or <control>‐V charac‐
595 ter. Unless otherwise specified, the escaping character shall
596 be discarded at that time and shall not be further considered
597 for any purpose.
598
599 Command-line parsing shall be done in the following steps. For each
600 step, characters already evaluated shall be ignored; that is, the
601 phrase ``leading character'' refers to the next character that has not
602 yet been evaluated.
603
604 1. Leading <colon> characters shall be skipped.
605
606 2. Leading <blank> characters shall be skipped.
607
608 3. If the leading character is a double-quote character, the charac‐
609 ters up to and including the next non-<backslash>-escaped <newline>
610 shall be discarded, and any subsequent characters shall be parsed
611 as a separate command.
612
613 4. Leading characters that can be interpreted as addresses shall be
614 evaluated; see Addressing in ex.
615
616 5. Leading <blank> characters shall be skipped.
617
618 6. If the next character is a <vertical-line> character or a <new‐
619 line>:
620
621 a. If the next character is a <newline>:
622
623 i. If ex is in open or visual mode, the current line shall be
624 set to the last address specified, if any.
625
626 ii. Otherwise, if the last command was terminated by a <verti‐
627 cal-line> character, no action shall be taken; for exam‐
628 ple, the command "||<newline>" shall execute two implied
629 commands, not three.
630
631 iii. Otherwise, step 6.b. shall apply.
632
633 b. Otherwise, the implied command shall be the print command. The
634 last #, p, and l flags specified to any ex command shall be
635 remembered and shall apply to this implied command. Executing
636 the ex number, print, or list command shall set the remembered
637 flags to #, nothing, and l, respectively, plus any other flags
638 specified for that execution of the number, print, or list com‐
639 mand.
640
641 If ex is not currently performing a global or v command, and no
642 address or count is specified, the current line shall be incre‐
643 mented by 1 before the command is executed. If incrementing the
644 current line would result in an address past the last line in
645 the edit buffer, the command shall fail, and the increment
646 shall not happen.
647
648 c. The <newline> or <vertical-line> character shall be discarded
649 and any subsequent characters shall be parsed as a separate
650 command.
651
652 7. The command name shall be comprised of the next character (if the
653 character is not alphabetic), or the next character and any subse‐
654 quent alphabetic characters (if the character is alphabetic), with
655 the following exceptions:
656
657 a. Commands that consist of any prefix of the characters in the
658 command name delete, followed immediately by any of the charac‐
659 ters 'l', 'p', '+', '-', or '#' shall be interpreted as a
660 delete command, followed by a <blank>, followed by the charac‐
661 ters that were not part of the prefix of the delete command.
662 The maximum number of characters shall be matched to the com‐
663 mand name delete; for example, "del" shall not be treated as
664 "de" followed by the flag l.
665
666 b. Commands that consist of the character 'k', followed by a char‐
667 acter that can be used as the name of a mark, shall be equiva‐
668 lent to the mark command followed by a <blank>, followed by the
669 character that followed the 'k'.
670
671 c. Commands that consist of the character 's', followed by charac‐
672 ters that could be interpreted as valid options to the s com‐
673 mand, shall be the equivalent of the s command, without any
674 pattern or replacement values, followed by a <blank>, followed
675 by the characters after the 's'.
676
677 8. The command name shall be matched against the possible command
678 names, and a command name that contains a prefix matching the char‐
679 acters specified by the user shall be the executed command. In the
680 case of commands where the characters specified by the user could
681 be ambiguous, the executed command shall be as follows:
682
683 ┌───┬────────┬┬───┬───────┬┬───┬───────┐
684 │a │ append ││n │ next ││t │ t │
685 │c │ change ││p │ print ││u │ undo │
686 │ch │ change ││pr │ print ││un │ undo │
687 │e │ edit ││r │ read ││v │ v │
688 │m │ move ││re │ read ││w │ write │
689 │ma │ mark ││s │ s ││ │ │
690 └───┴────────┴┴───┴───────┴┴───┴───────┘
691 Implementation extensions with names causing similar ambiguities
692 shall not be checked for a match until all possible matches for
693 commands specified by POSIX.1‐2008 have been checked.
694
695 9. If the command is a ! command, or if the command is a read command
696 followed by zero or more <blank> characters and a !, or if the com‐
697 mand is a write command followed by one or more <blank> characters
698 and a !, the rest of the command shall include all characters up to
699 a non-<backslash>-escaped <newline>. The <newline> shall be dis‐
700 carded and any subsequent characters shall be parsed as a separate
701 ex command.
702
703 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
707 a. Any '!' character immediately following the command shall be
708 skipped and be part of the command.
709
710 b. Any leading <blank> characters shall be skipped and be part of
711 the command.
712
713 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
717 d. The rest of the command shall be determined by the steps speci‐
718 fied in paragraph 12.
719
720 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
723 a. Any leading <blank> characters shall be skipped and be part of
724 the command.
725
726 b. If the next character is not an alphanumeric, double-quote,
727 <newline>, <backslash>, or <vertical-line> character:
728
729 i. The next character shall be used as a command delimiter.
730
731 ii. If the command is a global, open, or v command, characters
732 up to the first non-<backslash>-escaped <newline>, or
733 first non-<backslash>-escaped delimiter character, shall
734 be skipped and be part of the command.
735
736 iii. If the command is an s command, characters up to the first
737 non-<backslash>-escaped <newline>, or second non-<back‐
738 slash>-escaped delimiter character, shall be skipped and
739 be part of the command.
740
741 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
745 d. Otherwise, the rest of the command shall be determined by the
746 steps specified in paragraph 12.
747
748 12. Otherwise:
749
750 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
755 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
759 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
764 d. If the command was ended by a double-quote character, all sub‐
765 sequent characters, up to the next non-<backslash>-escaped
766 <newline>, shall be discarded.
767
768 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
772 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> characters, and where it would
776 otherwise be ambiguous. For example, count and flag arguments need not
777 be <blank>-separated because "d22p" is not ambiguous, but file argu‐
778 ments to the ex next command must be separated by one or more <blank>
779 characters. Any <blank> in command arguments for the abbreviate, unab‐
780 breviate, map, and unmap commands can be <control>‐V-escaped, in which
781 case the <blank> shall not be used as an argument delimiter. Any
782 <blank> in the command argument for any other command can be <back‐
783 slash>-escaped, in which case that <blank> shall not be used as an
784 argument delimiter.
785
786 Within command arguments for the abbreviate, unabbreviate, map, and
787 unmap commands, any character can be <control>‐V-escaped. All such
788 escaped characters shall be treated literally and shall have no special
789 meaning. Within command arguments for all other ex commands that are
790 not regular expressions or replacement strings, any character that
791 would otherwise have a special meaning can be <backslash>-escaped.
792 Escaped characters shall be treated literally, without special meaning
793 as shell expansion characters or '!', '%', and '#' expansion charac‐
794 ters. See Regular Expressions in ex and Replacement Strings in ex for
795 descriptions of command arguments that are regular expressions or
796 replacement strings.
797
798 Non-<backslash>-escaped '%' characters appearing in file arguments to
799 any ex command shall be replaced by the current pathname; unescaped '#'
800 characters shall be replaced by the alternate pathname. It shall be an
801 error if '%' or '#' characters appear unescaped in an argument and
802 their corresponding values are not set.
803
804 Non-<backslash>-escaped '!' characters in the arguments to either the
805 ex ! command or the open and visual mode ! command, or in the argu‐
806 ments to the ex read command, where the first non-<blank> after the
807 command name is a '!' character, or in the arguments to the ex write
808 command where the command name is followed by one or more <blank> char‐
809 acters and the first non-<blank> after the command name is a '!' char‐
810 acter, shall be replaced with the arguments to the last of those three
811 commands as they appeared after all unescaped '%', '#', and '!' char‐
812 acters were replaced. It shall be an error if '!' characters appear
813 unescaped in one of these commands and there has been no previous exe‐
814 cution of one of these commands.
815
816 If an error occurs during the parsing or execution of an ex command:
817
818 * An informational message to this effect shall be written. Execution
819 of the ex command shall stop, and the cursor (for example, the cur‐
820 rent line and column) shall not be further modified.
821
822 * If the ex command resulted from a map expansion, all characters
823 from that map expansion shall be discarded, except as otherwise
824 specified by the map command.
825
826 * Otherwise, if the ex command resulted from the processing of an
827 EXINIT environment variable, a .exrc file, a :source command, a -c
828 option, or a +command specified to an ex edit, ex, next, or visual
829 command, no further commands from the source of the commands shall
830 be executed.
831
832 * Otherwise, if the ex command resulted from the execution of a buf‐
833 fer or a global or v command, no further commands caused by the
834 execution of the buffer or the global or v command shall be exe‐
835 cuted.
836
837 * Otherwise, if the ex command was not terminated by a <newline>, all
838 characters up to and including the next non-<backslash>-escaped
839 <newline> shall be discarded.
840
841 Input Editing in ex
842 The following symbol is used in this and the following sections to
843 specify command actions:
844
845 word In the POSIX locale, a word consists of a maximal sequence of
846 letters, digits, and underscores, delimited at both ends by
847 characters other than letters, digits, or underscores, or by
848 the beginning or end of a line or the edit buffer.
849
850 When accepting input characters from the user, in either ex command
851 mode or ex text input mode, ex shall enable canonical mode input pro‐
852 cessing, as defined in the System Interfaces volume of POSIX.1‐2017.
853
854 If in ex text input mode:
855
856 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
860 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
863 any.
864
865 If in ex command mode:
866
867 1. If the prompt edit option is set, input shall be prompted for using
868 a single ':' character; otherwise, there shall be no prompt.
869
870 The input characters in the following sections shall have the following
871 effects on the input line.
872
873 Scroll
874 Synopsis:
875
876 eof
877
878 See the description of the stty eof character in stty.
879
880 If in ex command mode:
881
882 If the eof character is the first character entered on the line,
883 the line shall be evaluated as if it contained two characters: a
884 <control>‐D and a <newline>.
885
886 Otherwise, the eof character shall have no special meaning.
887
888 If in ex text input mode:
889
890 If the cursor follows an autoindent character, the autoindent
891 characters in the line shall be modified so that a part of the
892 next text input character will be displayed on the first column
893 in the line after the previous shiftwidth edit option column
894 boundary, and the user shall be prompted again for input for the
895 same line.
896
897 Otherwise, if the cursor follows a '0', which follows an autoin‐
898 dent character, and the '0' was the previous text input charac‐
899 ter, the '0' and all autoindent characters in the line shall be
900 discarded, and the user shall be prompted again for input for
901 the same line.
902
903 Otherwise, if the cursor follows a '^', which follows an autoin‐
904 dent character, and the '^' was the previous text input charac‐
905 ter, the '^' and all autoindent characters in the line shall be
906 discarded, and the user shall be prompted again for input for
907 the same line. In addition, the autoindent level for the next
908 input line shall be derived from the same line from which the
909 autoindent level for the current input line was derived.
910
911 Otherwise, if there are no autoindent or text input characters
912 in the line, the eof character shall be discarded.
913
914 Otherwise, the eof character shall have no special meaning.
915
916 <newline>
917 Synopsis:
918
919 <newline>
920 <control>-J
921
922 If in ex command mode:
923
924 Cause the command line to be parsed; <control>‐J shall be mapped
925 to the <newline> for this purpose.
926
927 If in ex text input mode:
928
929 Terminate the current line. If there are no characters other
930 than autoindent characters on the line, all characters on the
931 line shall be discarded.
932
933 Prompt for text input on a new line after the current line. If
934 the autoindent edit option is set, an appropriate number of
935 autoindent characters shall be added as a prefix to the line as
936 described by the ex autoindent edit option.
937
938 <backslash>
939 Synopsis:
940
941 <backslash>
942
943 Allow the entry of a subsequent <newline> or <control>‐J as a literal
944 character, removing any special meaning that it may have to the editor
945 during text input mode. The <backslash> character shall be retained and
946 evaluated when the command line is parsed, or retained and included
947 when the input text becomes part of the edit buffer.
948
949 <control>‐V
950 Synopsis:
951
952 <control>-V
953
954 Allow the entry of any subsequent character as a literal character,
955 removing any special meaning that it may have to the editor during text
956 input mode. The <control>‐V character shall be discarded before the
957 command line is parsed or the input text becomes part of the edit buf‐
958 fer.
959
960 If the ``literal next'' functionality is performed by the underlying
961 system, it is implementation-defined whether a character other than
962 <control>‐V performs this function.
963
964 <control>‐W
965 Synopsis:
966
967 <control>-W
968
969 Discard the <control>‐W, and the word previous to it in the input line,
970 including any <blank> characters following the word and preceding the
971 <control>‐W. If the ``word erase'' functionality is performed by the
972 underlying system, it is implementation-defined whether a character
973 other than <control>‐W performs this function.
974
975 Command Descriptions in ex
976 The following symbols are used in this section to represent command
977 modifiers. Some of these modifiers can be omitted, in which case the
978 specified defaults shall be used.
979
980 1addr A single line address, given in any of the forms described in
981 Addressing in ex; the default shall be the current line
982 ('.'), unless otherwise specified.
983
984 If the line address is zero, it shall be an error, unless
985 otherwise specified in the following command descriptions.
986
987 If the edit buffer is empty, and the address is specified
988 with a command other than =, append, insert, open, put, read,
989 or visual, or the address is not zero, it shall be an error.
990
991 2addr Two addresses specifying an inclusive range of lines. If no
992 addresses are specified, the default for 2addr shall be the
993 current line only (".,."), unless otherwise specified in the
994 following command descriptions. If one address is specified,
995 2addr shall specify that line only, unless otherwise speci‐
996 fied in the following command descriptions.
997
998 It shall be an error if the first address is greater than the
999 second address.
1000
1001 If the edit buffer is empty, and the two addresses are speci‐
1002 fied with a command other than the !, write, wq, or xit com‐
1003 mands, or either address is not zero, it shall be an error.
1004
1005 count A positive decimal number. If count is specified, it shall be
1006 equivalent to specifying an additional address to the com‐
1007 mand, unless otherwise specified by the following command
1008 descriptions. The additional address shall be equal to the
1009 last address specified to the command (either explicitly or
1010 by default) plus count-1.
1011
1012 If this would result in an address greater than the last line
1013 of the edit buffer, it shall be corrected to equal the last
1014 line of the edit buffer.
1015
1016 flags One or more of the characters '+', '-', '#', 'p', or 'l'
1017 (ell). The flag characters can be <blank>-separated, and in
1018 any order or combination. The characters '#', 'p', and 'l'
1019 shall cause lines to be written in the format specified by
1020 the print command with the specified flags.
1021
1022 The lines to be written are as follows:
1023
1024 1. All edit buffer lines written during the execution of the
1025 ex &, ~, list, number, open, print, s, visual, and z com‐
1026 mands shall be written as specified by flags.
1027
1028 2. After the completion of an ex command with a flag as an
1029 argument, the current line shall be written as specified
1030 by flags, unless the current line was the last line writ‐
1031 ten by the command.
1032
1033 The characters '+' and '-' cause the value of the current
1034 line after the execution of the ex command to be adjusted by
1035 the offset address as described in Addressing in ex. This
1036 adjustment shall occur before the current line is written as
1037 described in 2. above.
1038
1039 The default for flags shall be none.
1040
1041 buffer One of a number of named areas for holding text. The named
1042 buffers are specified by the alphanumeric characters of the
1043 POSIX locale. There shall also be one ``unnamed'' buffer.
1044 When no buffer is specified for editor commands that use a
1045 buffer, the unnamed buffer shall be used. Commands that
1046 store text into buffers shall store the text as it was before
1047 the command took effect, and shall store text occurring ear‐
1048 lier in the file before text occurring later in the file,
1049 regardless of how the text region was specified. Commands
1050 that store text into buffers shall store the text into the
1051 unnamed buffer as well as any specified buffer.
1052
1053 In ex commands, buffer names are specified as the name by
1054 itself. In open or visual mode commands the name is preceded
1055 by a double-quote ('"') character.
1056
1057 If the specified buffer name is an uppercase character, and
1058 the buffer contents are to be modified, the buffer shall be
1059 appended to rather than being overwritten. If the buffer is
1060 not being modified, specifying the buffer name in lowercase
1061 and uppercase shall have identical results.
1062
1063 There shall also be buffers named by the numbers 1 through 9.
1064 In open and visual mode, if a region of text including char‐
1065 acters from more than a single line is being modified by the
1066 vi c or d commands, the motion character associated with the
1067 c or d commands specifies that the buffer text shall be in
1068 line mode, or the commands %, `, /, ?, (, ), N, n, {, or }
1069 are used to define a region of text for the c or d commands,
1070 the contents of buffers 1 through 8 shall be moved into the
1071 buffer named by the next numerically greater value, the con‐
1072 tents of buffer 9 shall be discarded, and the region of text
1073 shall be copied into buffer 1. This shall be in addition to
1074 copying the text into a user-specified buffer or unnamed buf‐
1075 fer, or both. Numeric buffers can be specified as a source
1076 buffer for open and visual mode commands; however, specifying
1077 a numeric buffer as the write target of an open or visual
1078 mode command shall have unspecified results.
1079
1080 The text of each buffer shall have the characteristic of
1081 being in either line or character mode. Appending text to a
1082 non-empty buffer shall set the mode to match the characteris‐
1083 tic of the text being appended. Appending text to a buffer
1084 shall cause the creation of at least one additional line in
1085 the buffer. All text stored into buffers by ex commands shall
1086 be in line mode. The ex commands that use buffers as the
1087 source of text specify individually how buffers of different
1088 modes are handled. Each open or visual mode command that uses
1089 buffers for any purpose specifies individually the mode of
1090 the text stored into the buffer and how buffers of different
1091 modes are handled.
1092
1093 file Command text used to derive a pathname. The default shall be
1094 the current pathname, as defined previously, in which case,
1095 if no current pathname has yet been established it shall be
1096 an error, except where specifically noted in the individual
1097 command descriptions that follow. If the command text con‐
1098 tains any of the characters '~', '{', '[', '*', '?', '$',
1099 '"', backquote, single-quote, and <backslash>, it shall be
1100 subjected to the process of ``shell expansions'', as
1101 described below; if more than a single pathname results and
1102 the command expects only one, it shall be an error.
1103
1104 The process of shell expansions in the editor shall be done
1105 as follows. The ex utility shall pass two arguments to the
1106 program named by the shell edit option; the first shall be
1107 -c, and the second shall be the string "echo" and the command
1108 text as a single argument. The standard output and standard
1109 error of that command shall replace the command text.
1110
1111 ! A character that can be appended to the command name to mod‐
1112 ify its operation, as detailed in the individual command
1113 descriptions. With the exception of the ex read, write, and !
1114 commands, the '!' character shall only act as a modifier if
1115 there are no <blank> characters between it and the command
1116 name.
1117
1118 remembered search direction
1119 The vi commands N and n begin searching in a forwards or
1120 backwards direction in the edit buffer based on a remembered
1121 search direction, which is initially unset, and is set by the
1122 ex global, v, s, and tag commands, and the vi / and ? com‐
1123 mands.
1124
1125 Abbreviate
1126 Synopsis:
1127
1128 ab[breviate][lhs rhs]
1129
1130 If lhs and rhs are not specified, write the current list of abbrevia‐
1131 tions and do nothing more.
1132
1133 Implementations may restrict the set of characters accepted in lhs or
1134 rhs, except that printable characters and <blank> characters shall not
1135 be restricted. Additional restrictions shall be implementation-defined.
1136
1137 In both lhs and rhs, any character may be escaped with a <control>‐V,
1138 in which case the character shall not be used to delimit lhs from rhs,
1139 and the escaping <control>‐V shall be discarded.
1140
1141 In open and visual text input mode, if a non-word or <ESC> character
1142 that is not escaped by a <control>‐V character is entered after a word
1143 character, a check shall be made for a set of characters matching lhs,
1144 in the text input entered during this command. If it is found, the
1145 effect shall be as if rhs was entered instead of lhs.
1146
1147 The set of characters that are checked is defined as follows:
1148
1149 1. If there are no characters inserted before the word and non-word or
1150 <ESC> characters that triggered the check, the set of characters
1151 shall consist of the word character.
1152
1153 2. If the character inserted before the word and non-word or <ESC>
1154 characters that triggered the check is a word character, the set of
1155 characters shall consist of the characters inserted immediately
1156 before the triggering characters that are word characters, plus the
1157 triggering word character.
1158
1159 3. If the character inserted before the word and non-word or <ESC>
1160 characters that triggered the check is not a word character, the
1161 set of characters shall consist of the characters that were
1162 inserted before the triggering characters that are neither <blank>
1163 characters nor word characters, plus the triggering word character.
1164
1165 It is unspecified whether the lhs argument entered for the ex abbrevi‐
1166 ate and unabbreviate commands is replaced in this fashion. Regardless
1167 of whether or not the replacement occurs, the effect of the command
1168 shall be as if the replacement had not occurred.
1169
1170 Current line: Unchanged.
1171
1172 Current column: Unchanged.
1173
1174 Append
1175 Synopsis:
1176
1177 [1addr] a[ppend][!]
1178
1179 Enter ex text input mode; the input text shall be placed after the
1180 specified line. If line zero is specified, the text shall be placed at
1181 the beginning of the edit buffer.
1182
1183 This command shall be affected by the number and autoindent edit
1184 options; following the command name with '!' shall cause the autoin‐
1185 dent edit option setting to be toggled for the duration of this command
1186 only.
1187
1188 Current line: Set to the last input line; if no lines were input, set
1189 to the specified line, or to the first line of the edit buffer if a
1190 line of zero was specified, or zero if the edit buffer is empty.
1191
1192 Current column: Set to non-<blank>.
1193
1194 Arguments
1195 Synopsis:
1196
1197 ar[gs]
1198
1199 Write the current argument list, with the current argument-list entry,
1200 if any, between '[' and ']' characters.
1201
1202 Current line: Unchanged.
1203
1204 Current column: Unchanged.
1205
1206 Change
1207 Synopsis:
1208
1209 [2addr] c[hange][!][count]
1210
1211 Enter ex text input mode; the input text shall replace the specified
1212 lines. The specified lines shall be copied into the unnamed buffer,
1213 which shall become a line mode buffer.
1214
1215 This command shall be affected by the number and autoindent edit
1216 options; following the command name with '!' shall cause the autoin‐
1217 dent edit option setting to be toggled for the duration of this command
1218 only.
1219
1220 Current line: Set to the last input line; if no lines were input, set
1221 to the line before the first address, or to the first line of the edit
1222 buffer if there are no lines preceding the first address, or to zero if
1223 the edit buffer is empty.
1224
1225 Current column: Set to non-<blank>.
1226
1227 Change Directory
1228 Synopsis:
1229
1230 chd[ir][!][directory]
1231 cd[!][directory]
1232
1233 Change the current working directory to directory.
1234
1235 If no directory argument is specified, and the HOME environment vari‐
1236 able is set to a non-null and non-empty value, directory shall default
1237 to the value named in the HOME environment variable. If the HOME envi‐
1238 ronment variable is empty or is undefined, the default value of direc‐
1239 tory is implementation-defined.
1240
1241 If no '!' is appended to the command name, and the edit buffer has
1242 been modified since the last complete write, and the current pathname
1243 does not begin with a '/', it shall be an error.
1244
1245 Current line: Unchanged.
1246
1247 Current column: Unchanged.
1248
1249 Copy
1250 Synopsis:
1251
1252 [2addr] co[py] 1addr [flags]
1253 [2addr] t 1addr [flags]
1254
1255 Copy the specified lines after the specified destination line; line
1256 zero specifies that the lines shall be placed at the beginning of the
1257 edit buffer.
1258
1259 Current line: Set to the last line copied.
1260
1261 Current column: Set to non-<blank>.
1262
1263 Delete
1264 Synopsis:
1265
1266 [2addr] d[elete][buffer][count][flags]
1267
1268 Delete the specified lines into a buffer (defaulting to the unnamed
1269 buffer), which shall become a line-mode buffer.
1270
1271 Flags can immediately follow the command name; see Command Line Parsing
1272 in ex.
1273
1274 Current line: Set to the line following the deleted lines, or to the
1275 last line in the edit buffer if that line is past the end of the edit
1276 buffer, or to zero if the edit buffer is empty.
1277
1278 Current column: Set to non-<blank>.
1279
1280 Edit
1281 Synopsis:
1282
1283 e[dit][!][+command][file]
1284 ex[!][+command][file]
1285
1286 If no '!' is appended to the command name, and the edit buffer has
1287 been modified since the last complete write, it shall be an error.
1288
1289 If file is specified, replace the current contents of the edit buffer
1290 with the current contents of file, and set the current pathname to
1291 file. If file is not specified, replace the current contents of the
1292 edit buffer with the current contents of the file named by the current
1293 pathname. If for any reason the current contents of the file cannot be
1294 accessed, the edit buffer shall be empty.
1295
1296 The +command option shall be <blank>-delimited; <blank> characters
1297 within the +command can be escaped by preceding them with a <backslash>
1298 character. The +command shall be interpreted as an ex command immedi‐
1299 ately after the contents of the edit buffer have been replaced and the
1300 current line and column have been set.
1301
1302 If the edit buffer is empty:
1303
1304 Current line: Set to 0.
1305
1306 Current column: Set to 1.
1307
1308 Otherwise, if executed while in ex command mode or if the +command
1309 argument is specified:
1310
1311 Current line: Set to the last line of the edit buffer.
1312
1313 Current column: Set to non-<blank>.
1314
1315 Otherwise, if file is omitted or results in the current pathname:
1316
1317 Current line: Set to the first line of the edit buffer.
1318
1319 Current column: Set to non-<blank>.
1320
1321 Otherwise, if file is the same as the last file edited, the line and
1322 column shall be set as follows; if the file was previously edited, the
1323 line and column may be set as follows:
1324
1325 Current line: Set to the last value held when that file was last
1326 edited. If this value is not a valid line in the new edit buffer, set
1327 to the first line of the edit buffer.
1328
1329 Current column: If the current line was set to the last value held when
1330 the file was last edited, set to the last value held when the file was
1331 last edited. Otherwise, or if the last value is not a valid column in
1332 the new edit buffer, set to non-<blank>.
1333
1334 Otherwise:
1335
1336 Current line: Set to the first line of the edit buffer.
1337
1338 Current column: Set to non-<blank>.
1339
1340 File
1341 Synopsis:
1342
1343 f[ile][file]
1344
1345 If a file argument is specified, the alternate pathname shall be set to
1346 the current pathname, and the current pathname shall be set to file.
1347
1348 Write an informational message. If the file has a current pathname, it
1349 shall be included in this message; otherwise, the message shall indi‐
1350 cate that there is no current pathname. If the edit buffer contains
1351 lines, the current line number and the number of lines in the edit buf‐
1352 fer shall be included in this message; otherwise, the message shall
1353 indicate that the edit buffer is empty. If the edit buffer has been
1354 modified since the last complete write, this fact shall be included in
1355 this message. If the readonly edit option is set, this fact shall be
1356 included in this message. The message may contain other unspecified
1357 information.
1358
1359 Current line: Unchanged.
1360
1361 Current column: Unchanged.
1362
1363 Global
1364 Synopsis:
1365
1366 [2addr] g[lobal] /pattern/ [commands]
1367 [2addr] v /pattern/ [commands]
1368
1369 The optional '!' character after the global command shall be the same
1370 as executing the v command.
1371
1372 If pattern is empty (for example, "//") or not specified, the last reg‐
1373 ular expression used in the editor command shall be used as the pat‐
1374 tern. The pattern can be delimited by <slash> characters (shown in the
1375 Synopsis), as well as any non-alphanumeric or non-<blank> other than
1376 <backslash>, <vertical-line>, <newline>, or double-quote.
1377
1378 If no lines are specified, the lines shall default to the entire file.
1379
1380 The global and v commands are logically two-pass operations. First,
1381 mark the lines within the specified lines for which the line excluding
1382 the terminating <newline> matches (global) or does not match (v or
1383 global!) the specified pattern. Second, execute the ex commands given
1384 by commands, with the current line ('.') set to each marked line. If
1385 an error occurs during this process, or the contents of the edit buffer
1386 are replaced (for example, by the ex :edit command) an error message
1387 shall be written and no more commands resulting from the execution of
1388 this command shall be processed.
1389
1390 Multiple ex commands can be specified by entering multiple commands on
1391 a single line using a <vertical-line> to delimit them, or one per line,
1392 by escaping each <newline> with a <backslash>.
1393
1394 If no commands are specified:
1395
1396 1. If in ex command mode, it shall be as if the print command were
1397 specified.
1398
1399 2. Otherwise, no command shall be executed.
1400
1401 For the append, change, and insert commands, the input text shall be
1402 included as part of the command, and the terminating <period> can be
1403 omitted if the command ends the list of commands. The open and visual
1404 commands can be specified as one of the commands, in which case each
1405 marked line shall cause the editor to enter open or visual mode. If
1406 open or visual mode is exited using the vi Q command, the current line
1407 shall be set to the next marked line, and open or visual mode reen‐
1408 tered, until the list of marked lines is exhausted.
1409
1410 The global, v, and undo commands cannot be used in commands. Marked
1411 lines may be deleted by commands executed for lines occurring earlier
1412 in the file than the marked lines. In this case, no commands shall be
1413 executed for the deleted lines.
1414
1415 If the remembered search direction is not set, the global and v com‐
1416 mands shall set it to forward.
1417
1418 The autoprint and autoindent edit options shall be inhibited for the
1419 duration of the g or v command.
1420
1421 Current line: If no commands executed, set to the last marked line.
1422 Otherwise, as specified for the executed ex commands.
1423
1424 Current column: If no commands are executed, set to non-<blank>; other‐
1425 wise, as specified for the individual ex commands.
1426
1427 Insert
1428 Synopsis:
1429
1430 [1addr] i[nsert][!]
1431
1432 Enter ex text input mode; the input text shall be placed before the
1433 specified line. If the line is zero or 1, the text shall be placed at
1434 the beginning of the edit buffer.
1435
1436 This command shall be affected by the number and autoindent edit
1437 options; following the command name with '!' shall cause the autoin‐
1438 dent edit option setting to be toggled for the duration of this command
1439 only.
1440
1441 Current line: Set to the last input line; if no lines were input, set
1442 to the line before the specified line, or to the first line of the edit
1443 buffer if there are no lines preceding the specified line, or zero if
1444 the edit buffer is empty.
1445
1446 Current column: Set to non-<blank>.
1447
1448 Join
1449 Synopsis:
1450
1451 [2addr] j[oin][!][count][flags]
1452
1453 If count is specified:
1454
1455 If no address was specified, the join command shall behave as if
1456 2addr were the current line and the current line plus count (.,.
1457 + count).
1458
1459 If one address was specified, the join command shall behave as
1460 if 2addr were the specified address and the specified address
1461 plus count (addr,addr + count).
1462
1463 If two addresses were specified, the join command shall behave
1464 as if an additional address, equal to the last address plus
1465 count -1 (addr1,addr2,addr2 + count -1), was specified.
1466
1467 If this would result in a second address greater than the last
1468 line of the edit buffer, it shall be corrected to be equal to
1469 the last line of the edit buffer.
1470
1471 If no count is specified:
1472
1473 If no address was specified, the join command shall behave as if
1474 2addr were the current line and the next line (.,. +1).
1475
1476 If one address was specified, the join command shall behave as
1477 if 2addr were the specified address and the next line (addr,addr
1478 +1).
1479
1480 Join the text from the specified lines together into a single line,
1481 which shall replace the specified lines.
1482
1483 If a '!' character is appended to the command name, the join shall be
1484 without modification of any line, independent of the current locale.
1485
1486 Otherwise, in the POSIX locale, set the current line to the first of
1487 the specified lines, and then, for each subsequent line, proceed as
1488 follows:
1489
1490 1. Discard leading <space> characters from the line to be joined.
1491
1492 2. If the line to be joined is now empty, delete it, and skip steps 3
1493 through 5.
1494
1495 3. If the current line ends in a <blank>, or the first character of
1496 the line to be joined is a ')' character, join the lines without
1497 further modification.
1498
1499 4. If the last character of the current line is a '.', join the lines
1500 with two <space> characters between them.
1501
1502 5. Otherwise, join the lines with a single <space> between them.
1503
1504 Current line: Set to the first line specified.
1505
1506 Current column: Set to non-<blank>.
1507
1508 List
1509 Synopsis:
1510
1511 [2addr] l[ist][count][flags]
1512
1513 This command shall be equivalent to the ex command:
1514
1515
1516 [2addr] p[rint][count] l[flags]
1517
1518 See Print.
1519
1520 Map
1521 Synopsis:
1522
1523 map[!][lhs rhs]
1524
1525 If lhs and rhs are not specified:
1526
1527 1. If '!' is specified, write the current list of text input mode
1528 maps.
1529
1530 2. Otherwise, write the current list of command mode maps.
1531
1532 3. Do nothing more.
1533
1534 Implementations may restrict the set of characters accepted in lhs or
1535 rhs, except that printable characters and <blank> characters shall not
1536 be restricted. Additional restrictions shall be implementation-defined.
1537 In both lhs and rhs, any character can be escaped with a <control>‐V,
1538 in which case the character shall not be used to delimit lhs from rhs,
1539 and the escaping <control>‐V shall be discarded.
1540
1541 If the character '!' is appended to the map command name, the mapping
1542 shall be effective during open or visual text input mode rather than
1543 open or visual command mode. This allows lhs to have two different map
1544 definitions at the same time: one for command mode and one for text
1545 input mode.
1546
1547 For command mode mappings:
1548
1549 When the lhs is entered as any part of a vi command in open or
1550 visual mode (but not as part of the arguments to the command),
1551 the action shall be as if the corresponding rhs had been
1552 entered.
1553
1554 If any character in the command, other than the first, is
1555 escaped using a <control>‐V character, that character shall not
1556 be part of a match to an lhs.
1557
1558 It is unspecified whether implementations shall support map com‐
1559 mands where the lhs is more than a single character in length,
1560 where the first character of the lhs is printable.
1561
1562 If lhs contains more than one character and the first character
1563 is '#', followed by a sequence of digits corresponding to a num‐
1564 bered function key, then when this function key is typed it
1565 shall be mapped to rhs. Characters other than digits following
1566 a '#' character also represent the function key named by the
1567 characters in the lhs following the '#' and may be mapped to
1568 rhs. It is unspecified how function keys are named or what
1569 function keys are supported.
1570
1571 For text input mode mappings:
1572
1573 When the lhs is entered as any part of text entered in open or
1574 visual text input modes, the action shall be as if the corre‐
1575 sponding rhs had been entered.
1576
1577 If any character in the input text is escaped using a <con‐
1578 trol>‐V character, that character shall not be part of a match
1579 to an lhs.
1580
1581 It is unspecified whether the lhs text entered for subsequent
1582 map or unmap commands is replaced with the rhs text for the pur‐
1583 poses of the screen display; regardless of whether or not the
1584 display appears as if the corresponding rhs text was entered,
1585 the effect of the command shall be as if the lhs text was
1586 entered.
1587
1588 If only part of the lhs is entered, it is unspecified how long the edi‐
1589 tor will wait for additional, possibly matching characters before
1590 treating the already entered characters as not matching the lhs.
1591
1592 The rhs characters shall themselves be subject to remapping, unless
1593 otherwise specified by the remap edit option, except that if the char‐
1594 acters in lhs occur as prefix characters in rhs, those characters shall
1595 not be remapped.
1596
1597 On block-mode terminals, the mapping need not occur immediately (for
1598 example, it may occur after the terminal transmits a group of charac‐
1599 ters to the system), but it shall achieve the same results as if it
1600 occurred immediately.
1601
1602 Current line: Unchanged.
1603
1604 Current column: Unchanged.
1605
1606 Mark
1607 Synopsis:
1608
1609 [1addr] ma[rk] character
1610 [1addr] k character
1611
1612 Implementations shall support character values of a single lowercase
1613 letter of the POSIX locale and the backquote and single-quote charac‐
1614 ters; support of other characters is implementation-defined.
1615
1616 If executing the vi m command, set the specified mark to the current
1617 line and 1-based numbered character referenced by the current column,
1618 if any; otherwise, column position 1.
1619
1620 Otherwise, set the specified mark to the specified line and 1-based
1621 numbered first non-<blank> non-<newline> in the line, if any; other‐
1622 wise, the last non-<newline> in the line, if any; otherwise, column
1623 position 1.
1624
1625 The mark shall remain associated with the line until the mark is reset
1626 or the line is deleted. If a deleted line is restored by a subsequent
1627 undo command, any marks previously associated with the line, which have
1628 not been reset, shall be restored as well. Any use of a mark not asso‐
1629 ciated with a current line in the edit buffer shall be an error.
1630
1631 The marks ` and ' shall be set as described previously, immediately
1632 before the following events occur in the editor:
1633
1634 1. The use of '$' as an ex address
1635
1636 2. The use of a positive decimal number as an ex address
1637
1638 3. The use of a search command as an ex address
1639
1640 4. The use of a mark reference as an ex address
1641
1642 5. The use of the following open and visual mode commands: <con‐
1643 trol>‐], %, (, ), [, ], {, }
1644
1645 6. The use of the following open and visual mode commands: ', G, H, L,
1646 M, z if the current line will change as a result of the command
1647
1648 7. The use of the open and visual mode commands: /, ?, N, `, n if the
1649 current line or column will change as a result of the command
1650
1651 8. The use of the ex mode commands: z, undo, global, v
1652
1653 For rules 1., 2., 3., and 4., the ` and ' marks shall not be set if the
1654 ex command is parsed as specified by rule 6.a. in Command Line Parsing
1655 in ex.
1656
1657 For rules 5., 6., and 7., the ` and ' marks shall not be set if the
1658 commands are used as motion commands in open and visual mode.
1659
1660 For rules 1., 2., 3., 4., 5., 6., 7., and 8., the ` and ' marks shall
1661 not be set if the command fails.
1662
1663 The ` and ' marks shall be set as described previously, each time the
1664 contents of the edit buffer are replaced (including the editing of the
1665 initial buffer), if in open or visual mode, or if in ex mode and the
1666 edit buffer is not empty, before any commands or movements (including
1667 commands or movements specified by the -c or -t options or the +command
1668 argument) are executed on the edit buffer. If in open or visual mode,
1669 the marks shall be set as if executing the vi m command; otherwise, as
1670 if executing the ex mark command.
1671
1672 When changing from ex mode to open or visual mode, if the ` and ' marks
1673 are not already set, the ` and ' marks shall be set as described previ‐
1674 ously.
1675
1676 Current line: Unchanged.
1677
1678 Current column: Unchanged.
1679
1680 Move
1681 Synopsis:
1682
1683 [2addr] m[ove] 1addr [flags]
1684
1685 Move the specified lines after the specified destination line. A desti‐
1686 nation of line zero specifies that the lines shall be placed at the
1687 beginning of the edit buffer. It shall be an error if the destination
1688 line is within the range of lines to be moved.
1689
1690 Current line: Set to the last of the moved lines.
1691
1692 Current column: Set to non-<blank>.
1693
1694 Next
1695 Synopsis:
1696
1697 n[ext][!][+command][file ...]
1698
1699 If no '!' is appended to the command name, and the edit buffer has
1700 been modified since the last complete write, it shall be an error,
1701 unless the file is successfully written as specified by the autowrite
1702 option.
1703
1704 If one or more files is specified:
1705
1706 1. Set the argument list to the specified filenames.
1707
1708 2. Set the current argument list reference to be the first entry in
1709 the argument list.
1710
1711 3. Set the current pathname to the first filename specified.
1712
1713 Otherwise:
1714
1715 1. It shall be an error if there are no more filenames in the argument
1716 list after the filename currently referenced.
1717
1718 2. Set the current pathname and the current argument list reference to
1719 the filename after the filename currently referenced in the argu‐
1720 ment list.
1721
1722 Replace the contents of the edit buffer with the contents of the file
1723 named by the current pathname. If for any reason the contents of the
1724 file cannot be accessed, the edit buffer shall be empty.
1725
1726 This command shall be affected by the autowrite and writeany edit
1727 options.
1728
1729 The +command option shall be <blank>-delimited; <blank> characters can
1730 be escaped by preceding them with a <backslash> character. The +command
1731 shall be interpreted as an ex command immediately after the contents of
1732 the edit buffer have been replaced and the current line and column have
1733 been set.
1734
1735 Current line: Set as described for the edit command.
1736
1737 Current column: Set as described for the edit command.
1738
1739 Number
1740 Synopsis:
1741
1742 [2addr] nu[mber][count][flags]
1743 [2addr] #[count][flags]
1744
1745 These commands shall be equivalent to the ex command:
1746
1747
1748 [2addr] p[rint][count] #[flags]
1749
1750 See Print.
1751
1752 Open
1753 Synopsis:
1754
1755 [1addr] o[pen] /pattern/ [flags]
1756
1757 This command need not be supported on block-mode terminals or terminals
1758 with insufficient capabilities. If standard input, standard output, or
1759 standard error are not terminal devices, the results are unspecified.
1760
1761 Enter open mode.
1762
1763 The trailing delimiter can be omitted from pattern at the end of the
1764 command line. If pattern is empty (for example, "//") or not specified,
1765 the last regular expression used in the editor shall be used as the
1766 pattern. The pattern can be delimited by <slash> characters (shown in
1767 the Synopsis), as well as any alphanumeric, or non-<blank> other than
1768 <backslash>, <vertical-line>, <newline>, or double-quote.
1769
1770 Current line: Set to the specified line.
1771
1772 Current column: Set to non-<blank>.
1773
1774 Preserve
1775 Synopsis:
1776
1777 pre[serve]
1778
1779 Save the edit buffer in a form that can later be recovered by using the
1780 -r option or by using the ex recover command. After the file has been
1781 preserved, a mail message shall be sent to the user. This message shall
1782 be readable by invoking the mailx utility. The message shall contain
1783 the name of the file, the time of preservation, and an ex command that
1784 could be used to recover the file. Additional information may be
1785 included in the mail message.
1786
1787 Current line: Unchanged.
1788
1789 Current column: Unchanged.
1790
1791 Print
1792 Synopsis:
1793
1794 [2addr] p[rint][count][flags]
1795
1796 Write the addressed lines. The behavior is unspecified if the number of
1797 columns on the display is less than the number of columns required to
1798 write any single character in the lines being written.
1799
1800 Non-printable characters, except for the <tab>, shall be written as
1801 implementation-defined multi-character sequences.
1802
1803 If the # flag is specified or the number edit option is set, each line
1804 shall be preceded by its line number in the following format:
1805
1806
1807 "%6d ", <line number>
1808
1809 If the l flag is specified or the list edit option is set:
1810
1811 1. The characters listed in the Base Definitions volume of
1812 POSIX.1‐2017, Table 5-1, Escape Sequences and Associated Actions
1813 shall be written as the corresponding escape sequence.
1814
1815 2. Non-printable characters not in the Base Definitions volume of
1816 POSIX.1‐2017, Table 5-1, Escape Sequences and Associated Actions
1817 shall be written as one three-digit octal number (with a preceding
1818 <backslash>) for each byte in the character (most significant byte
1819 first).
1820
1821 3. The end of each line shall be marked with a '$', and literal '$'
1822 characters within the line shall be written with a preceding <back‐
1823 slash>.
1824
1825 Long lines shall be folded; the length at which folding occurs is
1826 unspecified, but should be appropriate for the output terminal, consid‐
1827 ering the number of columns of the terminal.
1828
1829 If a line is folded, and the l flag is not specified and the list edit
1830 option is not set, it is unspecified whether a multi-column character
1831 at the folding position is separated; it shall not be discarded.
1832
1833 Current line: Set to the last written line.
1834
1835 Current column: Unchanged if the current line is unchanged; otherwise,
1836 set to non-<blank>.
1837
1838 Put
1839 Synopsis:
1840
1841 [1addr] pu[t][buffer]
1842
1843 Append text from the specified buffer (by default, the unnamed buffer)
1844 to the specified line; line zero specifies that the text shall be
1845 placed at the beginning of the edit buffer. Each portion of a line in
1846 the buffer shall become a new line in the edit buffer, regardless of
1847 the mode of the buffer.
1848
1849 Current line: Set to the last line entered into the edit buffer.
1850
1851 Current column: Set to non-<blank>.
1852
1853 Quit
1854 Synopsis:
1855
1856 q[uit][!]
1857
1858 If no '!' is appended to the command name:
1859
1860 1. If the edit buffer has been modified since the last complete write,
1861 it shall be an error.
1862
1863 2. If there are filenames in the argument list after the filename cur‐
1864 rently referenced, and the last command was not a quit, wq, xit, or
1865 ZZ (see Exit) command, it shall be an error.
1866
1867 Otherwise, terminate the editing session.
1868
1869 Read
1870 Synopsis:
1871
1872 [1addr] r[ead][!][file]
1873
1874 If '!' is not the first non-<blank> to follow the command name, a copy
1875 of the specified file shall be appended into the edit buffer after the
1876 specified line; line zero specifies that the copy shall be placed at
1877 the beginning of the edit buffer. The number of lines and bytes read
1878 shall be written. If no file is named, the current pathname shall be
1879 the default. If there is no current pathname, then file shall become
1880 the current pathname. If there is no current pathname or file operand,
1881 it shall be an error. Specifying a file that is not of type regular
1882 shall have unspecified results.
1883
1884 Otherwise, if file is preceded by '!', the rest of the line after the
1885 '!' shall have '%', '#', and '!' characters expanded as described in
1886 Command Line Parsing in ex.
1887
1888 The ex utility shall then pass two arguments to the program named by
1889 the shell edit option; the first shall be -c and the second shall be
1890 the expanded arguments to the read command as a single argument. The
1891 standard input of the program shall be set to the standard input of the
1892 ex program when it was invoked. The standard error and standard output
1893 of the program shall be appended into the edit buffer after the speci‐
1894 fied line.
1895
1896 Each line in the copied file or program output (as delimited by <new‐
1897 line> characters or the end of the file or output if it is not immedi‐
1898 ately preceded by a <newline>), shall be a separate line in the edit
1899 buffer. Any occurrences of <carriage-return> and <newline> pairs in the
1900 output shall be treated as single <newline> characters.
1901
1902 The special meaning of the '!' following the read command can be over‐
1903 ridden by escaping it with a <backslash> character.
1904
1905 Current line: If no lines are added to the edit buffer, unchanged. Oth‐
1906 erwise, if in open or visual mode, set to the first line entered into
1907 the edit buffer. Otherwise, set to the last line entered into the edit
1908 buffer.
1909
1910 Current column: Set to non-<blank>.
1911
1912 Recover
1913 Synopsis:
1914
1915 rec[over][!] file
1916
1917 If no '!' is appended to the command name, and the edit buffer has
1918 been modified since the last complete write, it shall be an error.
1919
1920 If no file operand is specified, then the current pathname shall be
1921 used. If there is no current pathname or file operand, it shall be an
1922 error.
1923
1924 If no recovery information has previously been saved about file, the
1925 recover command shall behave identically to the edit command, and an
1926 informational message to this effect shall be written.
1927
1928 Otherwise, set the current pathname to file, and replace the current
1929 contents of the edit buffer with the recovered contents of file. If
1930 there are multiple instances of the file to be recovered, the one most
1931 recently saved shall be recovered, and an informational message that
1932 there are previous versions of the file that can be recovered shall be
1933 written. The editor shall behave as if the contents of the edit buffer
1934 have already been modified.
1935
1936 Current file: Set as described for the edit command.
1937
1938 Current column: Set as described for the edit command.
1939
1940 Rewind
1941 Synopsis:
1942
1943 rew[ind][!]
1944
1945 If no '!' is appended to the command name, and the edit buffer has
1946 been modified since the last complete write, it shall be an error,
1947 unless the file is successfully written as specified by the autowrite
1948 option.
1949
1950 If the argument list is empty, it shall be an error.
1951
1952 The current argument list reference and the current pathname shall be
1953 set to the first filename in the argument list.
1954
1955 Replace the contents of the edit buffer with the contents of the file
1956 named by the current pathname. If for any reason the contents of the
1957 file cannot be accessed, the edit buffer shall be empty.
1958
1959 This command shall be affected by the autowrite and writeany edit
1960 options.
1961
1962 Current line: Set as described for the edit command.
1963
1964 Current column: Set as described for the edit command.
1965
1966 Set
1967 Synopsis:
1968
1969 se[t][option[=[value]] ...][nooption ...][option? ...][all]
1970
1971 When no arguments are specified, write the value of the term edit
1972 option and those options whose values have been changed from the
1973 default settings; when the argument all is specified, write all of the
1974 option values.
1975
1976 Giving an option name followed by the character '?' shall cause the
1977 current value of that option to be written. The '?' can be separated
1978 from the option name by zero or more <blank> characters. The '?' shall
1979 be necessary only for Boolean valued options. Boolean options can be
1980 given values by the form set option to turn them on or set nooption to
1981 turn them off; string and numeric options can be assigned by the form
1982 set option=value. Any <blank> characters in strings can be included as
1983 is by preceding each <blank> with an escaping <backslash>. More than
1984 one option can be set or listed by a single set command by specifying
1985 multiple arguments, each separated from the next by one or more <blank>
1986 characters.
1987
1988 See Edit Options in ex for details about specific options.
1989
1990 Current line: Unchanged.
1991
1992 Current column: Unchanged.
1993
1994 Shell
1995 Synopsis:
1996
1997 sh[ell]
1998
1999 Invoke the program named in the shell edit option with the single argu‐
2000 ment -i (interactive mode). Editing shall be resumed when the program
2001 exits.
2002
2003 Current line: Unchanged.
2004
2005 Current column: Unchanged.
2006
2007 Source
2008 Synopsis:
2009
2010 so[urce] file
2011
2012 Read and execute ex commands from file. Lines in the file that are
2013 blank lines shall be ignored.
2014
2015 Current line: As specified for the individual ex commands.
2016
2017 Current column: As specified for the individual ex commands.
2018
2019 Substitute
2020 Synopsis:
2021
2022 [2addr] s[ubstitute][/pattern/repl/[options][count][flags]]
2023 [2addr] &[options][count][flags]]
2024 [2addr] ~[options][count][flags]]
2025
2026 Replace the first instance of the pattern pattern by the string repl on
2027 each specified line. (See Regular Expressions in ex and Replacement
2028 Strings in ex.) Any non-alphabetic, non-<blank> delimiter other than
2029 <backslash>, '|', <newline>, or double-quote can be used instead of
2030 '/'. <backslash> characters can be used to escape delimiters, <back‐
2031 slash> characters, and other special characters.
2032
2033 The trailing delimiter can be omitted from pattern or from repl at the
2034 end of the command line. If both pattern and repl are not specified or
2035 are empty (for example, "//"), the last s command shall be repeated. If
2036 only pattern is not specified or is empty, the last regular expression
2037 used in the editor shall be used as the pattern. If only repl is not
2038 specified or is empty, the pattern shall be replaced by nothing. If
2039 the entire replacement pattern is '%', the last replacement pattern to
2040 an s command shall be used.
2041
2042 Entering a <carriage-return> in repl (which requires an escaping <back‐
2043 slash> in ex mode and an escaping <control>‐V in open or vi mode) shall
2044 split the line at that point, creating a new line in the edit buffer.
2045 The <carriage-return> shall be discarded.
2046
2047 If options includes the letter 'g' (global), all non-overlapping
2048 instances of the pattern in the line shall be replaced.
2049
2050 If options includes the letter 'c' (confirm), then before each substi‐
2051 tution the line shall be written; the written line shall reflect all
2052 previous substitutions. On the following line, <space> characters shall
2053 be written beneath the characters from the line that are before the
2054 pattern to be replaced, and '^' characters written beneath the charac‐
2055 ters included in the pattern to be replaced. The ex utility shall then
2056 wait for a response from the user. An affirmative response shall cause
2057 the substitution to be done, while any other input shall not make the
2058 substitution. An affirmative response shall consist of a line with the
2059 affirmative response (as defined by the current locale) at the begin‐
2060 ning of the line. This line shall be subject to editing in the same way
2061 as the ex command line.
2062
2063 If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications
2064 confirmed by the user shall be preserved in the edit buffer after the
2065 interrupt.
2066
2067 If the remembered search direction is not set, the s command shall set
2068 it to forward.
2069
2070 In the second Synopsis, the & command shall repeat the previous substi‐
2071 tution, as if the & command were replaced by:
2072
2073
2074 s/pattern/repl/
2075
2076 where pattern and repl are as specified in the previous s, &, or ~ com‐
2077 mand.
2078
2079 In the third Synopsis, the ~ command shall repeat the previous substi‐
2080 tution, as if the '~' were replaced by:
2081
2082
2083 s/pattern/repl/
2084
2085 where pattern shall be the last regular expression specified to the
2086 editor, and repl shall be from the previous substitution (including &
2087 and ~) command.
2088
2089 These commands shall be affected by the LC_MESSAGES environment vari‐
2090 able.
2091
2092 Current line: Set to the last line in which a substitution occurred,
2093 or, unchanged if no substitution occurred.
2094
2095 Current column: Set to non-<blank>.
2096
2097 Suspend
2098 Synopsis:
2099
2100 su[spend][!]
2101 st[op][!]
2102
2103 Allow control to return to the invoking process; ex shall suspend
2104 itself as if it had received the SIGTSTP signal. The suspension shall
2105 occur only if job control is enabled in the invoking shell (see the
2106 description of set -m).
2107
2108 These commands shall be affected by the autowrite and writeany edit
2109 options.
2110
2111 The current susp character (see stty) shall be equivalent to the sus‐
2112 pend command.
2113
2114 Tag
2115 Synopsis:
2116
2117 ta[g][!] tagstring
2118
2119 The results are unspecified if the format of a tags file is not as
2120 specified by the ctags utility (see ctags) description.
2121
2122 The tag command shall search for tagstring in the tag files referred to
2123 by the tag edit option, in the order they are specified, until a refer‐
2124 ence to tagstring is found. Files shall be searched from beginning to
2125 end. If no reference is found, it shall be an error and an error mes‐
2126 sage to this effect shall be written. If the reference is not found, or
2127 if an error occurs while processing a file referred to in the tag edit
2128 option, it shall be an error, and an error message shall be written at
2129 the first occurrence of such an error.
2130
2131 Otherwise, if the tags file contained a pattern, the pattern shall be
2132 treated as a regular expression used in the editor; for example, for
2133 the purposes of the s command.
2134
2135 If the tagstring is in a file with a different name than the current
2136 pathname, set the current pathname to the name of that file, and
2137 replace the contents of the edit buffer with the contents of that file.
2138 In this case, if no '!' is appended to the command name, and the edit
2139 buffer has been modified since the last complete write, it shall be an
2140 error, unless the file is successfully written as specified by the
2141 autowrite option.
2142
2143 This command shall be affected by the autowrite, tag, taglength, and
2144 writeany edit options.
2145
2146 Current line: If the tags file contained a line number, set to that
2147 line number. If the line number is larger than the last line in the
2148 edit buffer, an error message shall be written and the current line
2149 shall be set as specified for the edit command.
2150
2151 If the tags file contained a pattern, set to the first occurrence of
2152 the pattern in the file. If no matching pattern is found, an error mes‐
2153 sage shall be written and the current line shall be set as specified
2154 for the edit command.
2155
2156 Current column: If the tags file contained a line-number reference and
2157 that line-number was not larger than the last line in the edit buffer,
2158 or if the tags file contained a pattern and that pattern was found, set
2159 to non-<blank>. Otherwise, set as specified for the edit command.
2160
2161 Unabbreviate
2162 Synopsis:
2163
2164 una[bbrev] lhs
2165
2166 If lhs is not an entry in the current list of abbreviations (see Abbre‐
2167 viate), it shall be an error. Otherwise, delete lhs from the list of
2168 abbreviations.
2169
2170 Current line: Unchanged.
2171
2172 Current column: Unchanged.
2173
2174 Undo
2175 Synopsis:
2176
2177 u[ndo]
2178
2179 Reverse the changes made by the last command that modified the contents
2180 of the edit buffer, including undo. For this purpose, the global, v,
2181 open, and visual commands, and commands resulting from buffer execu‐
2182 tions and mapped character expansions, are considered single commands.
2183
2184 If no action that can be undone preceded the undo command, it shall be
2185 an error.
2186
2187 If the undo command restores lines that were marked, the mark shall
2188 also be restored unless it was reset subsequent to the deletion of the
2189 lines.
2190
2191 Current line:
2192
2193 1. If lines are added or changed in the file, set to the first line
2194 added or changed.
2195
2196 2. Set to the line before the first line deleted, if it exists.
2197
2198 3. Set to 1 if the edit buffer is not empty.
2199
2200 4. Set to zero.
2201
2202 Current column: Set to non-<blank>.
2203
2204 Unmap
2205 Synopsis:
2206
2207 unm[ap][!] lhs
2208
2209 If '!' is appended to the command name, and if lhs is not an entry in
2210 the list of text input mode map definitions, it shall be an error. Oth‐
2211 erwise, delete lhs from the list of text input mode map definitions.
2212
2213 If no '!' is appended to the command name, and if lhs is not an entry
2214 in the list of command mode map definitions, it shall be an error. Oth‐
2215 erwise, delete lhs from the list of command mode map definitions.
2216
2217 Current line: Unchanged.
2218
2219 Current column: Unchanged.
2220
2221 Version
2222 Synopsis:
2223
2224 ve[rsion]
2225
2226 Write a message containing version information for the editor. The for‐
2227 mat of the message is unspecified.
2228
2229 Current line: Unchanged.
2230
2231 Current column: Unchanged.
2232
2233 Visual
2234 Synopsis:
2235
2236 [1addr] vi[sual][type][count][flags]
2237
2238 If ex is currently in open or visual mode, the Synopsis and behavior of
2239 the visual command shall be the same as the edit command, as specified
2240 by Edit.
2241
2242 Otherwise, this command need not be supported on block-mode terminals
2243 or terminals with insufficient capabilities. If standard input, stan‐
2244 dard output, or standard error are not terminal devices, the results
2245 are unspecified.
2246
2247 If count is specified, the value of the window edit option shall be set
2248 to count (as described in window). If the '^' type character was also
2249 specified, the window edit option shall be set before being used by the
2250 type character.
2251
2252 Enter visual mode. If type is not specified, it shall be as if a type
2253 of '+' was specified. The type shall cause the following effects:
2254
2255 + Place the beginning of the specified line at the top of the dis‐
2256 play.
2257
2258 - Place the end of the specified line at the bottom of the display.
2259
2260 . Place the beginning of the specified line in the middle of the
2261 display.
2262
2263 ^ If the specified line is less than or equal to the value of the
2264 window edit option, set the line to 1; otherwise, decrement the
2265 line by the value of the window edit option minus 1. Place the
2266 beginning of this line as close to the bottom of the displayed
2267 lines as possible, while still displaying the value of the window
2268 edit option number of lines.
2269
2270 Current line: Set to the specified line.
2271
2272 Current column: Set to non-<blank>.
2273
2274 Write
2275 Synopsis:
2276
2277 [2addr] w[rite][!][>>][file]
2278 [2addr] w[rite][!][file]
2279 [2addr] wq[!][>>][file]
2280
2281 If no lines are specified, the lines shall default to the entire file.
2282
2283 The command wq shall be equivalent to a write command followed by a
2284 quit command; wq! shall be equivalent to write! followed by quit. In
2285 both cases, if the write command fails, the quit shall not be
2286 attempted.
2287
2288 If the command name is not followed by one or more <blank> characters,
2289 or file is not preceded by a '!' character, the write shall be to a
2290 file.
2291
2292 1. If the >> argument is specified, and the file already exists, the
2293 lines shall be appended to the file instead of replacing its con‐
2294 tents. If the >> argument is specified, and the file does not
2295 already exist, it is unspecified whether the write shall proceed as
2296 if the >> argument had not been specified or if the write shall
2297 fail.
2298
2299 2. If the readonly edit option is set (see readonly), the write shall
2300 fail.
2301
2302 3. If file is specified, and is not the current pathname, and the file
2303 exists, the write shall fail.
2304
2305 4. If file is not specified, the current pathname shall be used. If
2306 there is no current pathname, the write command shall fail.
2307
2308 5. If the current pathname is used, and the current pathname has been
2309 changed by the file or read commands, and the file exists, the
2310 write shall fail. If the write is successful, subsequent writes
2311 shall not fail for this reason (unless the current pathname is
2312 changed again).
2313
2314 6. If the whole edit buffer is not being written, and the file to be
2315 written exists, the write shall fail.
2316
2317 For rules 1., 2., 3., and 5., the write can be forced by appending the
2318 character '!' to the command name.
2319
2320 For rules 2., 3., and 5., the write can be forced by setting the
2321 writeany edit option.
2322
2323 Additional, implementation-defined tests may cause the write to fail.
2324
2325 If the edit buffer is empty, a file without any contents shall be writ‐
2326 ten.
2327
2328 An informational message shall be written noting the number of lines
2329 and bytes written.
2330
2331 Otherwise, if the command is followed by one or more <blank> charac‐
2332 ters, and the file is preceded by '!', the rest of the line after the
2333 '!' shall have '%', '#', and '!' characters expanded as described in
2334 Command Line Parsing in ex.
2335
2336 The ex utility shall then pass two arguments to the program named by
2337 the shell edit option; the first shall be -c and the second shall be
2338 the expanded arguments to the write command as a single argument. The
2339 specified lines shall be written to the standard input of the command.
2340 The standard error and standard output of the program, if any, shall be
2341 written as described for the print command. If the last character in
2342 that output is not a <newline>, a <newline> shall be written at the end
2343 of the output.
2344
2345 The special meaning of the '!' following the write command can be
2346 overridden by escaping it with a <backslash> character.
2347
2348 Current line: Unchanged.
2349
2350 Current column: Unchanged.
2351
2352 Write and Exit
2353 Synopsis:
2354
2355 [2addr] x[it][!][file]
2356
2357 If the edit buffer has not been modified since the last complete write,
2358 xit shall be equivalent to the quit command, or if a '!' is appended
2359 to the command name, to quit!.
2360
2361 Otherwise, xit shall be equivalent to the wq command, or if a '!' is
2362 appended to the command name, to wq!.
2363
2364 Current line: Unchanged.
2365
2366 Current column: Unchanged.
2367
2368 Yank
2369 Synopsis:
2370
2371 [2addr] ya[nk][buffer][count]
2372
2373 Copy the specified lines to the specified buffer (by default, the
2374 unnamed buffer), which shall become a line-mode buffer.
2375
2376 Current line: Unchanged.
2377
2378 Current column: Unchanged.
2379
2380 Adjust Window
2381 Synopsis:
2382
2383 [1addr] z[!][type ...][count][flags]
2384
2385 If no line is specified, the current line shall be the default; if type
2386 is omitted as well, the current line value shall first be incremented
2387 by 1. If incrementing the current line would cause it to be greater
2388 than the last line in the edit buffer, it shall be an error.
2389
2390 If there are <blank> characters between the type argument and the pre‐
2391 ceding z command name or optional '!' character, it shall be an error.
2392
2393 If count is specified, the value of the window edit option shall be set
2394 to count (as described in window). If count is omitted, it shall
2395 default to 2 times the value of the scroll edit option, or if ! was
2396 specified, the number of lines in the display minus 1.
2397
2398 If type is omitted, then count lines starting with the specified line
2399 shall be written. Otherwise, count lines starting with the line speci‐
2400 fied by the type argument shall be written.
2401
2402 The type argument shall change the lines to be written. The possible
2403 values of type are as follows:
2404
2405 - The specified line shall be decremented by the following value:
2406
2407
2408 (((number of '-' characters) x count) -1)
2409
2410 If the calculation would result in a number less than 1, it shall
2411 be an error. Write lines from the edit buffer, starting at the
2412 new value of line, until count lines or the last line in the edit
2413 buffer has been written.
2414
2415 + The specified line shall be incremented by the following value:
2416
2417
2418 (((number of '+' characters) -1) x count) +1
2419
2420 If the calculation would result in a number greater than the last
2421 line in the edit buffer, it shall be an error. Write lines from
2422 the edit buffer, starting at the new value of line, until count
2423 lines or the last line in the edit buffer has been written.
2424
2425 =,. If more than a single '.' or '=' is specified, it shall be an
2426 error. The following steps shall be taken:
2427
2428 1. If count is zero, nothing shall be written.
2429
2430 2. Write as many of the N lines before the current line in the
2431 edit buffer as exist. If count or '!' was specified, N shall
2432 be:
2433
2434
2435 (count -1) /2
2436
2437 Otherwise, N shall be:
2438
2439
2440 (count -3) /2
2441
2442 If N is a number less than 3, no lines shall be written.
2443
2444 3. If '=' was specified as the type character, write a line con‐
2445 sisting of the smaller of the number of columns in the dis‐
2446 play divided by two, or 40 '-' characters.
2447
2448 4. Write the current line.
2449
2450 5. Repeat step 3.
2451
2452 6. Write as many of the N lines after the current line in the
2453 edit buffer as exist. N shall be defined as in step 2. If N
2454 is a number less than 3, no lines shall be written. If count
2455 is less than 3, no lines shall be written.
2456
2457 ^ The specified line shall be decremented by the following value:
2458
2459
2460 (((number of '^' characters) +1) x count) -1
2461
2462 If the calculation would result in a number less than 1, it shall
2463 be an error. Write lines from the edit buffer, starting at the
2464 new value of line, until count lines or the last line in the edit
2465 buffer has been written.
2466
2467 Current line: Set to the last line written, unless the type is =, in
2468 which case, set to the specified line.
2469
2470 Current column: Set to non-<blank>.
2471
2472 Escape
2473 Synopsis:
2474
2475 ! command
2476 [addr]! command
2477
2478 The contents of the line after the '!' shall have '%', '#', and '!'
2479 characters expanded as described in Command Line Parsing in ex. If the
2480 expansion causes the text of the line to change, it shall be redis‐
2481 played, preceded by a single '!' character.
2482
2483 The ex utility shall execute the program named by the shell edit
2484 option. It shall pass two arguments to the program; the first shall be
2485 -c, and the second shall be the expanded arguments to the ! command as
2486 a single argument.
2487
2488 If no lines are specified, the standard input, standard output, and
2489 standard error of the program shall be set to the standard input, stan‐
2490 dard output, and standard error of the ex program when it was invoked.
2491 In addition, a warning message shall be written if the edit buffer has
2492 been modified since the last complete write, and the warn edit option
2493 is set.
2494
2495 If lines are specified, they shall be passed to the program as standard
2496 input, and the standard output and standard error of the program shall
2497 replace those lines in the edit buffer. Each line in the program output
2498 (as delimited by <newline> characters or the end of the output if it is
2499 not immediately preceded by a <newline>), shall be a separate line in
2500 the edit buffer. Any occurrences of <carriage-return> and <newline>
2501 pairs in the output shall be treated as single <newline> characters.
2502 The specified lines shall be copied into the unnamed buffer before they
2503 are replaced, and the unnamed buffer shall become a line-mode buffer.
2504
2505 If in ex mode, a single '!' character shall be written when the pro‐
2506 gram completes.
2507
2508 This command shall be affected by the shell and warn edit options. If
2509 no lines are specified, this command shall be affected by the autowrite
2510 and writeany edit options. If lines are specified, this command shall
2511 be affected by the autoprint edit option.
2512
2513 Current line:
2514
2515 1. If no lines are specified, unchanged.
2516
2517 2. Otherwise, set to the last line read in, if any lines are read in.
2518
2519 3. Otherwise, set to the line before the first line of the lines spec‐
2520 ified, if that line exists.
2521
2522 4. Otherwise, set to the first line of the edit buffer if the edit
2523 buffer is not empty.
2524
2525 5. Otherwise, set to zero.
2526
2527 Current column: If no lines are specified, unchanged. Otherwise, set to
2528 non-<blank>.
2529
2530 Shift Left
2531 Synopsis:
2532
2533 [2addr] <[< ...][count][flags]
2534
2535 Shift the specified lines to the start of the line; the number of col‐
2536 umn positions to be shifted shall be the number of command characters
2537 times the value of the shiftwidth edit option. Only leading <blank>
2538 characters shall be deleted or changed into other <blank> characters in
2539 shifting; other characters shall not be affected.
2540
2541 Lines to be shifted shall be copied into the unnamed buffer, which
2542 shall become a line-mode buffer.
2543
2544 This command shall be affected by the autoprint edit option.
2545
2546 Current line: Set to the last line in the lines specified.
2547
2548 Current column: Set to non-<blank>.
2549
2550 Shift Right
2551 Synopsis:
2552
2553 [2addr] >[> ...][count][flags]
2554
2555 Shift the specified lines away from the start of the line; the number
2556 of column positions to be shifted shall be the number of command char‐
2557 acters times the value of the shiftwidth edit option. The shift shall
2558 be accomplished by adding <blank> characters as a prefix to the line or
2559 changing leading <blank> characters into other <blank> characters.
2560 Empty lines shall not be changed.
2561
2562 Lines to be shifted shall be copied into the unnamed buffer, which
2563 shall become a line-mode buffer.
2564
2565 This command shall be affected by the autoprint edit option.
2566
2567 Current line: Set to the last line in the lines specified.
2568
2569 Current column: Set to non-<blank>.
2570
2571 <control>‐D
2572 Synopsis:
2573
2574 <control>-D
2575
2576 Write the next n lines, where n is the minimum of the values of the
2577 scroll edit option and the number of lines after the current line in
2578 the edit buffer. If the current line is the last line of the edit buf‐
2579 fer it shall be an error.
2580
2581 Current line: Set to the last line written.
2582
2583 Current column: Set to non-<blank>.
2584
2585 Write Line Number
2586 Synopsis:
2587
2588 [1addr] = [flags]
2589
2590 If line is not specified, it shall default to the last line in the edit
2591 buffer. Write the line number of the specified line.
2592
2593 Current line: Unchanged.
2594
2595 Current column: Unchanged.
2596
2597 Execute
2598 Synopsis:
2599
2600 [2addr] @ buffer
2601 [2addr] * buffer
2602
2603 If no buffer is specified or is specified as '@' or '*', the last buf‐
2604 fer executed shall be used. If no previous buffer has been executed, it
2605 shall be an error.
2606
2607 For each line specified by the addresses, set the current line ('.')
2608 to the specified line, and execute the contents of the named buffer (as
2609 they were at the time the @ command was executed) as ex commands. For
2610 each line of a line-mode buffer, and all but the last line of a charac‐
2611 ter-mode buffer, the ex command parser shall behave as if the line was
2612 terminated by a <newline>.
2613
2614 If an error occurs during this process, or a line specified by the
2615 addresses does not exist when the current line would be set to it, or
2616 more than a single line was specified by the addresses, and the con‐
2617 tents of the edit buffer are replaced (for example, by the ex :edit
2618 command) an error message shall be written, and no more commands
2619 resulting from the execution of this command shall be processed.
2620
2621 Current line: As specified for the individual ex commands.
2622
2623 Current column: As specified for the individual ex commands.
2624
2625 Regular Expressions in ex
2626 The ex utility shall support regular expressions that are a superset of
2627 the basic regular expressions described in the Base Definitions volume
2628 of POSIX.1‐2017, Section 9.3, Basic Regular Expressions. A null regu‐
2629 lar expression ("//") shall be equivalent to the last regular expres‐
2630 sion encountered.
2631
2632 Regular expressions can be used in addresses to specify lines and, in
2633 some commands (for example, the substitute command), to specify por‐
2634 tions of a line to be substituted.
2635
2636 The following constructs can be used to enhance the basic regular
2637 expressions:
2638
2639 \< Match the beginning of a word. (See the definition of word at
2640 the beginning of Command Descriptions in ex.)
2641
2642 \> Match the end of a word.
2643
2644 ~ Match the replacement part of the last substitute command. The
2645 <tilde> ('~') character can be escaped in a regular expression to
2646 become a normal character with no special meaning. The <back‐
2647 slash> shall be discarded.
2648
2649 When the editor option magic is not set, the only characters with spe‐
2650 cial meanings shall be '^' at the beginning of a pattern, '$' at the
2651 end of a pattern, and <backslash>. The characters '.', '*', '[', and
2652 '~' shall be treated as ordinary characters unless preceded by a <back‐
2653 slash>; when preceded by a <backslash> they shall regain their special
2654 meaning, or in the case of <backslash>, be handled as a single <back‐
2655 slash>. <backslash> characters used to escape other characters shall
2656 be discarded.
2657
2658 Replacement Strings in ex
2659 The character '&' ('\&' if the editor option magic is not set) in the
2660 replacement string shall stand for the text matched by the pattern to
2661 be replaced. The character '~' ('\~' if magic is not set) shall be
2662 replaced by the replacement part of the previous substitute command.
2663 The sequence '\n', where n is an integer, shall be replaced by the text
2664 matched by the corresponding back-reference expression. If the corre‐
2665 sponding back-reference expression does not match, then the characters
2666 '\n' shall be replaced by the empty string.
2667
2668 The strings '\l', '\u', '\L', and '\U' can be used to modify the case
2669 of elements in the replacement string (using the '\&' or "\"digit)
2670 notation. The string '\l' ('\u') shall cause the character that follows
2671 to be converted to lowercase (uppercase). The string '\L' ('\U') shall
2672 cause all characters subsequent to it to be converted to lowercase
2673 (uppercase) as they are inserted by the substitution until the string
2674 '\e' or '\E', or the end of the replacement string, is encountered.
2675
2676 Otherwise, any character following a <backslash> shall be treated as
2677 that literal character, and the escaping <backslash> shall be dis‐
2678 carded.
2679
2680 An example of case conversion with the s command is as follows:
2681
2682
2683 :p
2684 The cat sat on the mat.
2685 :s/\<.at\>/\u&/gp
2686 The Cat Sat on the Mat.
2687 :s/S\(.*\)M/S\U\1\eM/p
2688 The Cat SAT ON THE Mat.
2689
2690 Edit Options in ex
2691 The ex utility has a number of options that modify its behavior. These
2692 options have default settings, which can be changed using the set com‐
2693 mand.
2694
2695 Options are Boolean unless otherwise specified.
2696
2697 autoindent, ai
2698 [Default unset]
2699
2700 If autoindent is set, each line in input mode shall be indented (using
2701 first as many <tab> characters as possible, as determined by the editor
2702 option tabstop, and then using <space> characters) to align with
2703 another line, as follows:
2704
2705 1. If in open or visual mode and the text input is part of a line-ori‐
2706 ented command (see the EXTENDED DESCRIPTION in vi), align to the
2707 first column.
2708
2709 2. Otherwise, if in open or visual mode, indentation for each line
2710 shall be set as follows:
2711
2712 a. If a line was previously inserted as part of this command, it
2713 shall be set to the indentation of the last inserted line by
2714 default, or as otherwise specified for the <control>‐D charac‐
2715 ter in Input Mode Commands in vi.
2716
2717 b. Otherwise, it shall be set to the indentation of the previous
2718 current line, if any; otherwise, to the first column.
2719
2720 3. For the ex a, i, and c commands, indentation for each line shall be
2721 set as follows:
2722
2723 a. If a line was previously inserted as part of this command, it
2724 shall be set to the indentation of the last inserted line by
2725 default, or as otherwise specified for the eof character in
2726 Scroll.
2727
2728 b. Otherwise, if the command is the ex a command, it shall be set
2729 to the line appended after, if any; otherwise to the first col‐
2730 umn.
2731
2732 c. Otherwise, if the command is the ex i command, it shall be set
2733 to the line inserted before, if any; otherwise to the first
2734 column.
2735
2736 d. Otherwise, if the command is the ex c command, it shall be set
2737 to the indentation of the line replaced.
2738
2739 autoprint, ap
2740 [Default set]
2741
2742 If autoprint is set, the current line shall be written after each ex
2743 command that modifies the contents of the current edit buffer, and
2744 after each tag command for which the tag search pattern was found or
2745 tag line number was valid, unless:
2746
2747 1. The command was executed while in open or visual mode.
2748
2749 2. The command was executed as part of a global or v command or @ buf‐
2750 fer execution.
2751
2752 3. The command was the form of the read command that reads a file into
2753 the edit buffer.
2754
2755 4. The command was the append, change, or insert command.
2756
2757 5. The command was not terminated by a <newline>.
2758
2759 6. The current line shall be written by a flag specified to the com‐
2760 mand; for example, delete # shall write the current line as speci‐
2761 fied for the flag modifier to the delete command, and not as speci‐
2762 fied by the autoprint edit option.
2763
2764 autowrite, aw
2765 [Default unset]
2766
2767 If autowrite is set, and the edit buffer has been modified since it was
2768 last completely written to any file, the contents of the edit buffer
2769 shall be written as if the ex write command had been specified without
2770 arguments, before each command affected by the autowrite edit option is
2771 executed. Appending the character '!' to the command name of any of
2772 the ex commands except '!' shall prevent the write. If the write
2773 fails, it shall be an error and the command shall not be executed.
2774
2775 beautify, bf
2776 [Default unset]
2777
2778 If beautify is set, all non-printable characters, other than <tab>,
2779 <newline>, and <form-feed> characters, shall be discarded from text
2780 read in from files.
2781
2782 directory, dir
2783 [Default implementation-defined]
2784
2785 The value of this option specifies the directory in which the editor
2786 buffer is to be placed. If this directory is not writable by the user,
2787 the editor shall quit.
2788
2789 edcompatible, ed
2790 [Default unset]
2791
2792 Causes the presence of g and c suffixes on substitute commands to be
2793 remembered, and toggled by repeating the suffixes.
2794
2795 errorbells, eb
2796 [Default unset]
2797
2798 If the editor is in ex mode, and the terminal does not support a stand‐
2799 out mode (such as inverse video), and errorbells is set, error messages
2800 shall be preceded by alerting the terminal.
2801
2802 exrc
2803 [Default unset]
2804
2805 If exrc is set, ex shall access any .exrc file in the current direc‐
2806 tory, as described in Initialization in ex and vi. If exrc is not set,
2807 ex shall ignore any .exrc file in the current directory during initial‐
2808 ization, unless the current directory is that named by the HOME envi‐
2809 ronment variable.
2810
2811 ignorecase, ic
2812 [Default unset]
2813
2814 If ignorecase is set, characters that have uppercase and lowercase rep‐
2815 resentations shall have those representations considered as equivalent
2816 for purposes of regular expression comparison.
2817
2818 The ignorecase edit option shall affect all remembered regular expres‐
2819 sions; for example, unsetting the ignorecase edit option shall cause a
2820 subsequent vi n command to search for the last basic regular expression
2821 in a case-sensitive fashion.
2822
2823 list
2824 [Default unset]
2825
2826 If list is set, edit buffer lines written while in ex command mode
2827 shall be written as specified for the print command with the l flag
2828 specified. In open or visual mode, each edit buffer line shall be dis‐
2829 played as specified for the ex print command with the l flag specified.
2830 In open or visual text input mode, when the cursor does not rest on any
2831 character in the line, it shall rest on the '$' marking the end of the
2832 line.
2833
2834 magic
2835 [Default set]
2836
2837 If magic is set, modify the interpretation of characters in regular
2838 expressions and substitution replacement strings (see Regular Expres‐
2839 sions in ex and Replacement Strings in ex).
2840
2841 mesg
2842 [Default set]
2843
2844 If mesg is set, the permission for others to use the write or talk com‐
2845 mands to write to the terminal shall be turned on while in open or vis‐
2846 ual mode. The shell-level command mesg n shall take precedence over any
2847 setting of the ex mesg option; that is, if mesg y was issued before the
2848 editor started (or in a shell escape), such as:
2849
2850
2851 :!mesg y
2852
2853 the mesg option in ex shall suppress incoming messages, but the mesg
2854 option shall not enable incoming messages if mesg n was issued.
2855
2856 number, nu
2857 [Default unset]
2858
2859 If number is set, edit buffer lines written while in ex command mode
2860 shall be written with line numbers, in the format specified by the
2861 print command with the # flag specified. In ex text input mode, each
2862 line shall be preceded by the line number it will have in the file.
2863
2864 In open or visual mode, each edit buffer line shall be displayed with a
2865 preceding line number, in the format specified by the ex print command
2866 with the # flag specified. This line number shall not be considered
2867 part of the line for the purposes of evaluating the current column;
2868 that is, column position 1 shall be the first column position after the
2869 format specified by the print command.
2870
2871 paragraphs, para
2872 [Default in the POSIX locale IPLPPPQPP LIpplpipbp]
2873
2874 The paragraphs edit option shall define additional paragraph boundaries
2875 for the open and visual mode commands. The paragraphs edit option can
2876 be set to a character string consisting of zero or more character
2877 pairs. It shall be an error to set it to an odd number of characters.
2878
2879 prompt
2880 [Default set]
2881
2882 If prompt is set, ex command mode input shall be prompted for with a
2883 <colon> (':'); when unset, no prompt shall be written.
2884
2885 readonly
2886 [Default see text]
2887
2888 If the readonly edit option is set, read-only mode shall be enabled
2889 (see Write). The readonly edit option shall be initialized to set if
2890 either of the following conditions are true:
2891
2892 * The command-line option -R was specified.
2893
2894 * Performing actions equivalent to the access() function called with
2895 the following arguments indicates that the file lacks write permis‐
2896 sion:
2897
2898 1. The current pathname is used as the path argument.
2899
2900 2. The constant W_OK is used as the amode argument.
2901
2902 The readonly edit option may be initialized to set for other, implemen‐
2903 tation-defined reasons. The readonly edit option shall not be initial‐
2904 ized to unset based on any special privileges of the user or process.
2905 The readonly edit option shall be reinitialized each time that the con‐
2906 tents of the edit buffer are replaced (for example, by an edit or next
2907 command) unless the user has explicitly set it, in which case it shall
2908 remain set until the user explicitly unsets it. Once unset, it shall
2909 again be reinitialized each time that the contents of the edit buffer
2910 are replaced.
2911
2912 redraw
2913 [Default unset]
2914
2915 The editor simulates an intelligent terminal on a dumb terminal.
2916 (Since this is likely to require a large amount of output to the termi‐
2917 nal, it is useful only at high transmission speeds.)
2918
2919 remap
2920 [Default set]
2921
2922 If remap is set, map translation shall allow for maps defined in terms
2923 of other maps; translation shall continue until a final product is
2924 obtained. If unset, only a one-step translation shall be done.
2925
2926 report
2927 [Default 5]
2928
2929 The value of this report edit option specifies what number of lines
2930 being added, copied, deleted, or modified in the edit buffer will cause
2931 an informational message to be written to the user. The following con‐
2932 ditions shall cause an informational message. The message shall contain
2933 the number of lines added, copied, deleted, or modified, but is other‐
2934 wise unspecified.
2935
2936 * An ex or vi editor command, other than open, undo, or visual, that
2937 modifies at least the value of the report edit option number of
2938 lines, and which is not part of an ex global or v command, or ex or
2939 vi buffer execution, shall cause an informational message to be
2940 written.
2941
2942 * An ex yank or vi y or Y command, that copies at least the value of
2943 the report edit option plus 1 number of lines, and which is not
2944 part of an ex global or v command, or ex or vi buffer execution,
2945 shall cause an informational message to be written.
2946
2947 * An ex global, v, open, undo, or visual command or ex or vi buffer
2948 execution, that adds or deletes a total of at least the value of
2949 the report edit option number of lines, and which is not part of an
2950 ex global or v command, or ex or vi buffer execution, shall cause
2951 an informational message to be written. (For example, if 3 lines
2952 were added and 8 lines deleted during an ex visual command, 5 would
2953 be the number compared against the report edit option after the
2954 command completed.)
2955
2956 scroll, scr
2957 [Default (number of lines in the display -1)/2]
2958
2959 The value of the scroll edit option shall determine the number of lines
2960 scrolled by the ex <control>‐D and z commands. For the vi <control>‐D
2961 and <control>‐U commands, it shall be the initial number of lines to
2962 scroll when no previous <control>‐D or <control>‐U command has been
2963 executed.
2964
2965 sections
2966 [Default in the POSIX locale NHSHH HUnhsh]
2967
2968 The sections edit option shall define additional section boundaries for
2969 the open and visual mode commands. The sections edit option can be set
2970 to a character string consisting of zero or more character pairs; it
2971 shall be an error to set it to an odd number of characters.
2972
2973 shell, sh
2974 [Default from the environment variable SHELL]
2975
2976 The value of this option shall be a string. The default shall be taken
2977 from the SHELL environment variable. If the SHELL environment variable
2978 is null or empty, the sh (see sh) utility shall be the default.
2979
2980 shiftwidth, sw
2981 [Default 8]
2982
2983 The value of this option shall give the width in columns of an indenta‐
2984 tion level used during autoindentation and by the shift commands (< and
2985 >).
2986
2987 showmatch, sm
2988 [Default unset]
2989
2990 The functionality described for the showmatch edit option need not be
2991 supported on block-mode terminals or terminals with insufficient capa‐
2992 bilities.
2993
2994 If showmatch is set, in open or visual mode, when a ')' or '}' is
2995 typed, if the matching '(' or '{' is currently visible on the display,
2996 the matching '(' or '{' shall be flagged moving the cursor to its loca‐
2997 tion for an unspecified amount of time.
2998
2999 showmode
3000 [Default unset]
3001
3002 If showmode is set, in open or visual mode, the current mode that the
3003 editor is in shall be displayed on the last line of the display. Com‐
3004 mand mode and text input mode shall be differentiated; other unspeci‐
3005 fied modes and implementation-defined information may be displayed.
3006
3007 slowopen
3008 [Default unset]
3009
3010 If slowopen is set during open and visual text input modes, the editor
3011 shall not update portions of the display other than those display line
3012 columns that display the characters entered by the user (see Input Mode
3013 Commands in vi).
3014
3015 tabstop, ts
3016 [Default 8]
3017
3018 The value of this edit option shall specify the column boundary used by
3019 a <tab> in the display (see autoprint, ap and Input Mode Commands in
3020 vi).
3021
3022 taglength, tl
3023 [Default zero]
3024
3025 The value of this edit option shall specify the maximum number of char‐
3026 acters that are considered significant in the user-specified tag name
3027 and in the tag name from the tags file. If the value is zero, all char‐
3028 acters in both tag names shall be significant.
3029
3030 tags
3031 [Default see text]
3032
3033 The value of this edit option shall be a string of <blank>-delimited
3034 pathnames of files used by the tag command. The default value is
3035 unspecified.
3036
3037 term
3038 [Default from the environment variable TERM]
3039
3040 The value of this edit option shall be a string. The default shall be
3041 taken from the TERM variable in the environment. If the TERM environ‐
3042 ment variable is empty or null, the default is unspecified. The editor
3043 shall use the value of this edit option to determine the type of the
3044 display device.
3045
3046 The results are unspecified if the user changes the value of the term
3047 edit option after editor initialization.
3048
3049 terse
3050 [Default unset]
3051
3052 If terse is set, error messages may be less verbose. However, except
3053 for this caveat, error messages are unspecified. Furthermore, not all
3054 error messages need change for different settings of this option.
3055
3056 warn
3057 [Default set]
3058
3059 If warn is set, and the contents of the edit buffer have been modified
3060 since they were last completely written, the editor shall write a warn‐
3061 ing message before certain ! commands (see Escape).
3062
3063 window
3064 [Default see text]
3065
3066 A value used in open and visual mode, by the <control>‐B and <con‐
3067 trol>‐F commands, and, in visual mode, to specify the number of lines
3068 displayed when the screen is repainted.
3069
3070 If the -w command-line option is not specified, the default value shall
3071 be set to the value of the LINES environment variable. If the LINES
3072 environment variable is empty or null, the default shall be the number
3073 of lines in the display minus 1.
3074
3075 Setting the window edit option to zero or to a value greater than the
3076 number of lines in the display minus 1 (either explicitly or based on
3077 the -w option or the LINES environment variable) shall cause the window
3078 edit option to be set to the number of lines in the display minus 1.
3079
3080 The baud rate of the terminal line may change the default in an imple‐
3081 mentation-defined manner.
3082
3083 wrapmargin, wm
3084 [Default 0]
3085
3086 If the value of this edit option is zero, it shall have no effect.
3087
3088 If not in the POSIX locale, the effect of this edit option is implemen‐
3089 tation-defined.
3090
3091 Otherwise, it shall specify a number of columns from the ending margin
3092 of the terminal.
3093
3094 During open and visual text input modes, for each character for which
3095 any part of the character is displayed in a column that is less than
3096 wrapmargin columns from the ending margin of the display line, the edi‐
3097 tor shall behave as follows:
3098
3099 1. If the character triggering this event is a <blank>, it, and all
3100 immediately preceding <blank> characters on the current line
3101 entered during the execution of the current text input command,
3102 shall be discarded, and the editor shall behave as if the user had
3103 entered a single <newline> instead. In addition, if the next user-
3104 entered character is a <space>, it shall be discarded as well.
3105
3106 2. Otherwise, if there are one or more <blank> characters on the cur‐
3107 rent line immediately preceding the last group of inserted
3108 non-<blank> characters which was entered during the execution of
3109 the current text input command, the <blank> characters shall be
3110 replaced as if the user had entered a single <newline> instead.
3111
3112 If the autoindent edit option is set, and the events described in 1. or
3113 2. are performed, any <blank> characters at or after the cursor in the
3114 current line shall be discarded.
3115
3116 The ending margin shall be determined by the system or overridden by
3117 the user, as described for COLUMNS in the ENVIRONMENT VARIABLES section
3118 and the Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
3119 Variables.
3120
3121 wrapscan, ws
3122 [Default set]
3123
3124 If wrapscan is set, searches (the ex / or ? addresses, or open and
3125 visual mode /, ?, N, and n commands) shall wrap around the beginning or
3126 end of the edit buffer; when unset, searches shall stop at the begin‐
3127 ning or end of the edit buffer.
3128
3129 writeany, wa
3130 [Default unset]
3131
3132 If writeany is set, some of the checks performed when executing the ex
3133 write commands shall be inhibited, as described in editor option
3134 autowrite.
3135
3137 The following exit values shall be returned:
3138
3139 0 Successful completion.
3140
3141 >0 An error occurred.
3142
3144 When any error is encountered and the standard input is not a terminal
3145 device file, ex shall not write the file or return to command or text
3146 input mode, and shall terminate with a non-zero exit status.
3147
3148 Otherwise, when an unrecoverable error is encountered, it shall be
3149 equivalent to a SIGHUP asynchronous event.
3150
3151 Otherwise, when an error is encountered, the editor shall behave as
3152 specified in Command Line Parsing in ex.
3153
3154 The following sections are informative.
3155
3157 If a SIGSEGV signal is received while ex is saving a file, the file
3158 might not be successfully saved.
3159
3160 The next command can accept more than one file, so usage such as:
3161
3162
3163 next `ls [abc]*`
3164
3165 is valid; it would not be valid for the edit or read commands, for
3166 example, because they expect only one file and unspecified results
3167 occur.
3168
3170 None.
3171
3173 The ex/vi specification is based on the historical practice found in
3174 the 4 BSD and System V implementations of ex and vi.
3175
3176 A restricted editor (both the historical red utility and modifications
3177 to ex) were considered and rejected for inclusion. Neither option pro‐
3178 vided the level of security that users might expect.
3179
3180 It is recognized that ex visual mode and related features would be dif‐
3181 ficult, if not impossible, to implement satisfactorily on a block-mode
3182 terminal, or a terminal without any form of cursor addressing; thus, it
3183 is not a mandatory requirement that such features should work on all
3184 terminals. It is the intention, however, that an ex implementation
3185 should provide the full set of capabilities on all terminals capable of
3186 supporting them.
3187
3188 Options
3189 The -c replacement for +command was inspired by the -e option of sed.
3190 Historically, all such commands (see edit and next as well) were exe‐
3191 cuted from the last line of the edit buffer. This meant, for example,
3192 that "+/pattern" would fail unless the wrapscan option was set.
3193 POSIX.1‐2008 requires conformance to historical practice. The +command
3194 option is no longer specified by POSIX.1‐2008 but may be present in
3195 some implementations. Historically, some implementations restricted the
3196 ex commands that could be listed as part of the command line arguments.
3197 For consistency, POSIX.1‐2008 does not permit these restrictions.
3198
3199 In historical implementations of the editor, the -R option (and the
3200 readonly edit option) only prevented overwriting of files; appending to
3201 files was still permitted, mapping loosely into the csh noclobber vari‐
3202 able. Some implementations, however, have not followed this semantic,
3203 and readonly does not permit appending either. POSIX.1‐2008 follows the
3204 latter practice, believing that it is a more obvious and intuitive
3205 meaning of readonly.
3206
3207 The -s option suppresses all interactive user feedback and is useful
3208 for editing scripts in batch jobs. The list of specific effects is his‐
3209 torical practice. The terminal type ``incapable of supporting open and
3210 visual modes'' has historically been named ``dumb''.
3211
3212 The -t option was required because the ctags utility appears in
3213 POSIX.1‐2008 and the option is available in all historical implementa‐
3214 tions of ex.
3215
3216 Historically, the ex and vi utilities accepted a -x option, which did
3217 encryption based on the algorithm found in the historical crypt util‐
3218 ity. The -x option for encryption, and the associated crypt utility,
3219 were omitted because the algorithm used was not specifiable and the
3220 export control laws of some nations make it difficult to export crypto‐
3221 graphic technology. In addition, it did not historically provide the
3222 level of security that users might expect.
3223
3224 Standard Input
3225 An end-of-file condition is not equivalent to an end-of-file character.
3226 A common end-of-file character, <control>‐D, is historically an ex com‐
3227 mand.
3228
3229 There was no maximum line length in historical implementations of ex.
3230 Specifically, as it was parsed in chunks, the addresses had a different
3231 maximum length than the filenames. Further, the maximum line buffer
3232 size was declared as BUFSIZ, which was different lengths on different
3233 systems. This version selected the value of {LINE_MAX} to impose a rea‐
3234 sonable restriction on portable usage of ex and to aid test suite writ‐
3235 ers in their development of realistic tests that exercise this limit.
3236
3237 Input Files
3238 It was an explicit decision by the standard developers that a <newline>
3239 be added to any file lacking one. It was believed that this feature of
3240 ex and vi was relied on by users in order to make text files lacking a
3241 trailing <newline> more portable. It is recognized that this will
3242 require a user-specified option or extension for implementations that
3243 permit ex and vi to edit files of type other than text if such files
3244 are not otherwise identified by the system. It was agreed that the
3245 ability to edit files of arbitrary type can be useful, but it was not
3246 considered necessary to mandate that an ex or vi implementation be
3247 required to handle files other than text files.
3248
3249 The paragraph in the INPUT FILES section, ``By default, ...'', is
3250 intended to close a long-standing security problem in ex and vi; that
3251 of the ``modeline'' or ``modelines'' edit option. This feature allows
3252 any line in the first or last five lines of the file containing the
3253 strings "ex:" or "vi:" (and, apparently, "ei:" or "vx:") to be a line
3254 containing editor commands, and ex interprets all the text up to the
3255 next ':' or <newline> as a command. Consider the consequences, for
3256 example, of an unsuspecting user using ex or vi as the editor when
3257 replying to a mail message in which a line such as:
3258
3259
3260 ex:! rm -rf :
3261
3262 appeared in the signature lines. The standard developers believed
3263 strongly that an editor should not by default interpret any lines of a
3264 file. Vendors are strongly urged to delete this feature from their
3265 implementations of ex and vi.
3266
3267 Asynchronous Events
3268 The intention of the phrase ``complete write'' is that the entire edit
3269 buffer be written to stable storage. The note regarding temporary files
3270 is intended for implementations that use temporary files to back edit
3271 buffers unnamed by the user.
3272
3273 Historically, SIGQUIT was ignored by ex, but was the equivalent of the
3274 Q command in visual mode; that is, it exited visual mode and entered ex
3275 mode. POSIX.1‐2008 permits, but does not require, this behavior. His‐
3276 torically, SIGINT was often used by vi users to terminate text input
3277 mode (<control>‐C is often easier to enter than <ESC>). Some implemen‐
3278 tations of vi alerted the terminal on this event, and some did not.
3279 POSIX.1‐2008 requires that SIGINT behave identically to <ESC>, and that
3280 the terminal not be alerted.
3281
3282 Historically, suspending the ex editor during text input mode was simi‐
3283 lar to SIGINT, as completed lines were retained, but any partial line
3284 discarded, and the editor returned to command mode. POSIX.1‐2008 is
3285 silent on this issue; implementations are encouraged to follow histori‐
3286 cal practice, where possible.
3287
3288 Historically, the vi editor did not treat SIGTSTP as an asynchronous
3289 event, and it was therefore impossible to suspend the editor in visual
3290 text input mode. There are two major reasons for this. The first is
3291 that SIGTSTP is a broadcast signal on UNIX systems, and the chain of
3292 events where the shell execs an application that then execs vi usually
3293 caused confusion for the terminal state if SIGTSTP was delivered to the
3294 process group in the default manner. The second was that most implemen‐
3295 tations of the UNIX curses package did not handle SIGTSTP safely, and
3296 the receipt of SIGTSTP at the wrong time would cause them to crash.
3297 POSIX.1‐2008 is silent on this issue; implementations are encouraged to
3298 treat suspension as an asynchronous event if possible.
3299
3300 Historically, modifications to the edit buffer made before SIGINT
3301 interrupted an operation were retained; that is, anywhere from zero to
3302 all of the lines to be modified might have been modified by the time
3303 the SIGINT arrived. These changes were not discarded by the arrival of
3304 SIGINT. POSIX.1‐2008 permits this behavior, noting that the undo com‐
3305 mand is required to be able to undo these partially completed commands.
3306
3307 The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and
3308 SIGTERM is unspecified because some implementations attempt to save the
3309 edit buffer in a useful state when other signals are received.
3310
3311 Standard Error
3312 For ex/vi, diagnostic messages are those messages reported as a result
3313 of a failed attempt to invoke ex or vi, such as invalid options or
3314 insufficient resources, or an abnormal termination condition. Diagnos‐
3315 tic messages should not be confused with the error messages generated
3316 by inappropriate or illegal user commands.
3317
3318 Initialization in ex and vi
3319 If an ex command (other than cd, chdir, or source) has a filename argu‐
3320 ment, one or both of the alternate and current pathnames will be set.
3321 Informally, they are set as follows:
3322
3323 1. If the ex command is one that replaces the contents of the edit
3324 buffer, and it succeeds, the current pathname will be set to the
3325 filename argument (the first filename argument in the case of the
3326 next command) and the alternate pathname will be set to the previ‐
3327 ous current pathname, if there was one.
3328
3329 2. In the case of the file read/write forms of the read and write com‐
3330 mands, if there is no current pathname, the current pathname will
3331 be set to the filename argument.
3332
3333 3. Otherwise, the alternate pathname will be set to the filename argu‐
3334 ment.
3335
3336 For example, :edit foo and :recover foo, when successful, set the cur‐
3337 rent pathname, and, if there was a previous current pathname, the
3338 alternate pathname. The commands :write, !command, and :edit set nei‐
3339 ther the current or alternate pathnames. If the :edit foo command were
3340 to fail for some reason, the alternate pathname would be set. The read
3341 and write commands set the alternate pathname to their file argument,
3342 unless the current pathname is not set, in which case they set the cur‐
3343 rent pathname to their file arguments. The alternate pathname was not
3344 historically set by the :source command. POSIX.1‐2008 requires confor‐
3345 mance to historical practice. Implementations adding commands that
3346 take filenames as arguments are encouraged to set the alternate path‐
3347 name as described here.
3348
3349 Historically, ex and vi read the .exrc file in the $HOME directory
3350 twice, if the editor was executed in the $HOME directory. POSIX.1‐2008
3351 prohibits this behavior.
3352
3353 Historically, the 4 BSD ex and vi read the $HOME and local .exrc files
3354 if they were owned by the real ID of the user, or the sourceany option
3355 was set, regardless of other considerations. This was a security prob‐
3356 lem because it is possible to put normal UNIX system commands inside a
3357 .exrc file. POSIX.1‐2008 does not specify the sourceany option, and
3358 historical implementations are encouraged to delete it.
3359
3360 The .exrc files must be owned by the real ID of the user, and not
3361 writable by anyone other than the owner. The appropriate privileges
3362 exception is intended to permit users to acquire special privileges,
3363 but continue to use the .exrc files in their home directories.
3364
3365 System V Release 3.2 and later vi implementations added the option
3366 [no]exrc. The behavior is that local .exrc files are read-only if the
3367 exrc option is set. The default for the exrc option was off, so by
3368 default, local .exrc files were not read. The problem this was intended
3369 to solve was that System V permitted users to give away files, so there
3370 is no possible ownership or writeability test to ensure that the file
3371 is safe. This is still a security problem on systems where users can
3372 give away files, but there is nothing additional that POSIX.1‐2008 can
3373 do. The implementation-defined exception is intended to permit groups
3374 to have local .exrc files that are shared by users, by creating pseudo-
3375 users to own the shared files.
3376
3377 POSIX.1‐2008 does not mention system-wide ex and vi start-up files.
3378 While they exist in several implementations of ex and vi, they are not
3379 present in any implementations considered historical practice by
3380 POSIX.1‐2008. Implementations that have such files should use them only
3381 if they are owned by the real user ID or an appropriate user (for exam‐
3382 ple, root on UNIX systems) and if they are not writable by any user
3383 other than their owner. System-wide start-up files should be read
3384 before the EXINIT variable, $HOME/.exrc, or local .exrc files are eval‐
3385 uated.
3386
3387 Historically, any ex command could be entered in the EXINIT variable or
3388 the .exrc file, although ones requiring that the edit buffer already
3389 contain lines of text generally caused historical implementations of
3390 the editor to drop core. POSIX.1‐2008 requires that any ex command be
3391 permitted in the EXINIT variable and .exrc files, for simplicity of
3392 specification and consistency, although many of them will obviously
3393 fail under many circumstances.
3394
3395 The initialization of the contents of the edit buffer uses the phrase
3396 ``the effect shall be'' with regard to various ex commands. The intent
3397 of this phrase is that edit buffer contents loaded during the initial‐
3398 ization phase not be lost; that is, loading the edit buffer should fail
3399 if the .exrc file read in the contents of a file and did not subse‐
3400 quently write the edit buffer. An additional intent of this phrase is
3401 to specify that the initial current line and column is set as specified
3402 for the individual ex commands.
3403
3404 Historically, the -t option behaved as if the tag search were a +com‐
3405 mand; that is, it was executed from the last line of the file specified
3406 by the tag. This resulted in the search failing if the pattern was a
3407 forward search pattern and the wrapscan edit option was not set.
3408 POSIX.1‐2008 does not permit this behavior, requiring that the search
3409 for the tag pattern be performed on the entire file, and, if not found,
3410 that the current line be set to a more reasonable location in the file.
3411
3412 Historically, the empty edit buffer presented for editing when a file
3413 was not specified by the user was unnamed. This is permitted by
3414 POSIX.1‐2008; however, implementations are encouraged to provide users
3415 a temporary filename for this buffer because it permits them the use of
3416 ex commands that use the current pathname during temporary edit ses‐
3417 sions.
3418
3419 Historically, the file specified using the -t option was not part of
3420 the current argument list. This practice is permitted by POSIX.1‐2008;
3421 however, implementations are encouraged to include its name in the cur‐
3422 rent argument list for consistency.
3423
3424 Historically, the -c command was generally not executed until a file
3425 that already exists was edited. POSIX.1‐2008 requires conformance to
3426 this historical practice. Commands that could cause the -c command to
3427 be executed include the ex commands edit, next, recover, rewind, and
3428 tag, and the vi commands <control>‐^ and <control>‐]. Historically,
3429 reading a file into an edit buffer did not cause the -c command to be
3430 executed (even though it might set the current pathname) with the
3431 exception that it did cause the -c command to be executed if: the edi‐
3432 tor was in ex mode, the edit buffer had no current pathname, the edit
3433 buffer was empty, and no read commands had yet been attempted. For con‐
3434 sistency and simplicity of specification, POSIX.1‐2008 does not permit
3435 this behavior.
3436
3437 Historically, the -r option was the same as a normal edit session if
3438 there was no recovery information available for the file. This allowed
3439 users to enter:
3440
3441
3442 vi -r *.c
3443
3444 and recover whatever files were recoverable. In some implementations,
3445 recovery was attempted only on the first file named, and the file was
3446 not entered into the argument list; in others, recovery was attempted
3447 for each file named. In addition, some historical implementations
3448 ignored -r if -t was specified or did not support command line file
3449 arguments with the -t option. For consistency and simplicity of speci‐
3450 fication, POSIX.1‐2008 disallows these special cases, and requires that
3451 recovery be attempted the first time each file is edited.
3452
3453 Historically, vi initialized the ` and ' marks, but ex did not. This
3454 meant that if the first command in ex mode was visual or if an ex com‐
3455 mand was executed first (for example, vi +10 file), vi was entered
3456 without the marks being initialized. Because the standard developers
3457 believed the marks to be generally useful, and for consistency and sim‐
3458 plicity of specification, POSIX.1‐2008 requires that they always be
3459 initialized if in open or visual mode, or if in ex mode and the edit
3460 buffer is not empty. Not initializing it in ex mode if the edit buffer
3461 is empty is historical practice; however, it has always been possible
3462 to set (and use) marks in empty edit buffers in open and visual mode
3463 edit sessions.
3464
3465 Addressing
3466 Historically, ex and vi accepted the additional addressing forms '\/'
3467 and '\?'. They were equivalent to "//" and "??", respectively. They
3468 are not required by POSIX.1‐2008, mostly because nobody can remember
3469 whether they ever did anything different historically.
3470
3471 Historically, ex and vi permitted an address of zero for several com‐
3472 mands, and permitted the % address in empty files for others. For con‐
3473 sistency, POSIX.1‐2008 requires support for the former in the few com‐
3474 mands where it makes sense, and disallows it otherwise. In addition,
3475 because POSIX.1‐2008 requires that % be logically equivalent to "1,$",
3476 it is also supported where it makes sense and disallowed otherwise.
3477
3478 Historically, the % address could not be followed by further addresses.
3479 For consistency and simplicity of specification, POSIX.1‐2008 requires
3480 that additional addresses be supported.
3481
3482 All of the following are valid addresses:
3483
3484 +++ Three lines after the current line.
3485
3486 /re/- One line before the next occurrence of re.
3487
3488 -2 Two lines before the current line.
3489
3490 3 ---- 2 Line one (note intermediate negative address).
3491
3492 1 2 3 Line six.
3493
3494 Any number of addresses can be provided to commands taking addresses;
3495 for example, "1,2,3,4,5p" prints lines 4 and 5, because two is the
3496 greatest valid number of addresses accepted by the print command. This,
3497 in combination with the <semicolon> delimiter, permits users to create
3498 commands based on ordered patterns in the file. For example, the com‐
3499 mand 3;/foo/;+2print will display the first line after line 3 that con‐
3500 tains the pattern foo, plus the next two lines. Note that the address
3501 3; must be evaluated before being discarded because the search origin
3502 for the /foo/ command depends on this.
3503
3504 Historically, values could be added to addresses by including them
3505 after one or more <blank> characters; for example, 3 - 5p wrote the
3506 seventh line of the file, and /foo/ 5 was the same as /foo/+5. How‐
3507 ever, only absolute values could be added; for example, 5 /foo/ was an
3508 error. POSIX.1‐2008 requires conformance to historical practice.
3509 Address offsets are separately specified from addresses because they
3510 could historically be provided to visual mode search commands.
3511
3512 Historically, any missing addresses defaulted to the current line. This
3513 was true for leading and trailing <comma>-delimited addresses, and for
3514 trailing <semicolon>-delimited addresses. For consistency, POSIX.1‐2008
3515 requires it for leading <semicolon> addresses as well.
3516
3517 Historically, ex and vi accepted the '^' character as both an address
3518 and as a flag offset for commands. In both cases it was identical to
3519 the '-' character. POSIX.1‐2008 does not require or prohibit this
3520 behavior.
3521
3522 Historically, the enhancements to basic regular expressions could be
3523 used in addressing; for example, '~', '\<', and '\>'. POSIX.1‐2008
3524 requires conformance to historical practice; that is, that regular
3525 expression usage be consistent, and that regular expression enhance‐
3526 ments be supported wherever regular expressions are used.
3527
3528 Command Line Parsing in ex
3529 Historical ex command parsing was even more complex than that described
3530 here. POSIX.1‐2008 requires the subset of the command parsing that the
3531 standard developers believed was documented and that users could rea‐
3532 sonably be expected to use in a portable fashion, and that was histori‐
3533 cally consistent between implementations. (The discarded functionality
3534 is obscure, at best.) Historical implementations will require changes
3535 in order to comply with POSIX.1‐2008; however, users are not expected
3536 to notice any of these changes. Most of the complexity in ex parsing
3537 is to handle three special termination cases:
3538
3539 1. The !, global, v, and the filter versions of the read and write
3540 commands are delimited by <newline> characters (they can contain
3541 <vertical-line> characters that are usually shell pipes).
3542
3543 2. The ex, edit, next, and visual in open and visual mode commands all
3544 take ex commands, optionally containing <vertical-line> characters,
3545 as their first arguments.
3546
3547 3. The s command takes a regular expression as its first argument, and
3548 uses the delimiting characters to delimit the command.
3549
3550 Historically, <vertical-line> characters in the +command argument of
3551 the ex, edit, next, vi, and visual commands, and in the pattern and
3552 replacement parts of the s command, did not delimit the command, and in
3553 the filter cases for read and write, and the !, global, and v commands,
3554 they did not delimit the command at all. For example, the following
3555 commands are all valid:
3556
3557
3558 :edit +25 | s/abc/ABC/ file.c
3559 :s/ | /PIPE/
3560 :read !spell % | columnate
3561 :global/pattern/p | l
3562 :s/a/b/ | s/c/d | set
3563
3564 Historically, empty or <blank> filled lines in .exrc files and sourced
3565 files (as well as EXINIT variables and ex command scripts) were treated
3566 as default commands; that is, print commands. POSIX.1‐2008 specifically
3567 requires that they be ignored when encountered in .exrc and sourced
3568 files to eliminate a common source of new user error.
3569
3570 Historically, ex commands with multiple adjacent (or <blank>-separated)
3571 vertical lines were handled oddly when executed from ex mode. For exam‐
3572 ple, the command ||| <carriage-return>, when the cursor was on line 1,
3573 displayed lines 2, 3, and 5 of the file. In addition, the command |
3574 would only display the line after the next line, instead of the next
3575 two lines. The former worked more logically when executed from vi mode,
3576 and displayed lines 2, 3, and 4. POSIX.1‐2008 requires the vi behavior;
3577 that is, a single default command and line number increment for each
3578 command separator, and trailing <newline> characters after <vertical-
3579 line> separators are discarded.
3580
3581 Historically, ex permitted a single extra <colon> as a leading command
3582 character; for example, :g/pattern/:p was a valid command. POSIX.1‐2008
3583 generalizes this to require that any number of leading <colon> charac‐
3584 ters be stripped.
3585
3586 Historically, any prefix of the delete command could be followed with‐
3587 out intervening <blank> characters by a flag character because in the
3588 command d p, p is interpreted as the buffer p. POSIX.1‐2008 requires
3589 conformance to historical practice.
3590
3591 Historically, the k command could be followed by the mark name without
3592 intervening <blank> characters. POSIX.1‐2008 requires conformance to
3593 historical practice.
3594
3595 Historically, the s command could be immediately followed by flag and
3596 option characters; for example, s/e/E/|s|sgc3p was a valid command.
3597 However, flag characters could not stand alone; for example, the com‐
3598 mands sp and s l would fail, while the command sgp and s gl would suc‐
3599 ceed. (Obviously, the '#' flag character was used as a delimiter char‐
3600 acter if it followed the command.) Another issue was that option char‐
3601 acters had to precede flag characters even when the command was fully
3602 specified; for example, the command s/e/E/pg would fail, while the com‐
3603 mand s/e/E/gp would succeed. POSIX.1‐2008 requires conformance to his‐
3604 torical practice.
3605
3606 Historically, the first command name that had a prefix matching the
3607 input from the user was the executed command; for example, ve, ver, and
3608 vers all executed the version command. Commands were in a specific
3609 order, however, so that a matched append, not abbreviate. POSIX.1‐2008
3610 requires conformance to historical practice. The restriction on command
3611 search order for implementations with extensions is to avoid the addi‐
3612 tion of commands such that the historical prefixes would fail to work
3613 portably.
3614
3615 Historical implementations of ex and vi did not correctly handle multi‐
3616 ple ex commands, separated by <vertical-line> characters, that entered
3617 or exited visual mode or the editor. Because implementations of vi
3618 exist that do not exhibit this failure mode, POSIX.1‐2008 does not per‐
3619 mit it.
3620
3621 The requirement that alphabetic command names consist of all following
3622 alphabetic characters up to the next non-alphabetic character means
3623 that alphabetic command names must be separated from their arguments by
3624 one or more non-alphabetic characters, normally a <blank> or '!' char‐
3625 acter, except as specified for the exceptions, the delete, k, and s
3626 commands.
3627
3628 Historically, the repeated execution of the ex default print commands
3629 (<control>‐D, eof, <newline>, <carriage-return>) erased any prompting
3630 character and displayed the next lines without scrolling the terminal;
3631 that is, immediately below any previously displayed lines. This pro‐
3632 vided a cleaner presentation of the lines in the file for the user.
3633 POSIX.1‐2008 does not require this behavior because it may be impossi‐
3634 ble in some situations; however, implementations are strongly encour‐
3635 aged to provide this semantic if possible.
3636
3637 Historically, it was possible to change files in the middle of a com‐
3638 mand, and have the rest of the command executed in the new file; for
3639 example:
3640
3641
3642 :edit +25 file.c | s/abc/ABC/ | 1
3643
3644 was a valid command, and the substitution was attempted in the newly
3645 edited file. POSIX.1‐2008 requires conformance to historical practice.
3646 The following commands are examples that exercise the ex parser:
3647
3648
3649 echo 'foo | bar' > file1; echo 'foo/bar' > file2;
3650 vi
3651 :edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\//SLASH/ | wq
3652
3653 Historically, there was no protection in editor implementations to
3654 avoid ex global, v, @, or * commands changing edit buffers during exe‐
3655 cution of their associated commands. Because this would almost invari‐
3656 ably result in catastrophic failure of the editor, and implementations
3657 exist that do exhibit these problems, POSIX.1‐2008 requires that chang‐
3658 ing the edit buffer during a global or v command, or during a @ or *
3659 command for which there will be more than a single execution, be an
3660 error. Implementations supporting multiple edit buffers simultaneously
3661 are strongly encouraged to apply the same semantics to switching
3662 between buffers as well.
3663
3664 The ex command quoting required by POSIX.1‐2008 is a superset of the
3665 quoting in historical implementations of the editor. For example, it
3666 was not historically possible to escape a <blank> in a filename; for
3667 example, :edit foo\\\ bar would report that too many filenames had been
3668 entered for the edit command, and there was no method of escaping a
3669 <blank> in the first argument of an edit, ex, next, or visual command
3670 at all. POSIX.1‐2008 extends historical practice, requiring that quot‐
3671 ing behavior be made consistent across all ex commands, except for the
3672 map, unmap, abbreviate, and unabbreviate commands, which historically
3673 used <control>‐V instead of <backslash> characters for quoting. For
3674 those four commands, POSIX.1‐2008 requires conformance to historical
3675 practice.
3676
3677 Backslash quoting in ex is non-intuitive. <backslash>-escapes are
3678 ignored unless they escape a special character; for example, when per‐
3679 forming file argument expansion, the string "\\%" is equivalent to
3680 '\%', not "\<current pathname>". This can be confusing for users
3681 because <backslash> is usually one of the characters that causes shell
3682 expansion to be performed, and therefore shell quoting rules must be
3683 taken into consideration. Generally, quoting characters are only con‐
3684 sidered if they escape a special character, and a quoting character
3685 must be provided for each layer of parsing for which the character is
3686 special. As another example, only a single <backslash> is necessary for
3687 the '\l' sequence in substitute replacement patterns, because the char‐
3688 acter 'l' is not special to any parsing layer above it.
3689
3690 <control>‐V quoting in ex is slightly different from backslash quoting.
3691 In the four commands where <control>‐V quoting applies (abbreviate,
3692 unabbreviate, map, and unmap), any character may be escaped by a <con‐
3693 trol>‐V whether it would have a special meaning or not. POSIX.1‐2008
3694 requires conformance to historical practice.
3695
3696 Historical implementations of the editor did not require delimiters
3697 within character classes to be escaped; for example, the command
3698 :s/[/]// on the string "xxx/yyy" would delete the '/' from the string.
3699 POSIX.1‐2008 disallows this historical practice for consistency and
3700 because it places a large burden on implementations by requiring that
3701 knowledge of regular expressions be built into the editor parser.
3702
3703 Historically, quoting <newline> characters in ex commands was handled
3704 inconsistently. In most cases, the <newline> character always termi‐
3705 nated the command, regardless of any preceding escape character,
3706 because <backslash> characters did not escape <newline> characters for
3707 most ex commands. However, some ex commands (for example, s, map, and
3708 abbreviation) permitted <newline> characters to be escaped (although in
3709 the case of map and abbreviation, <control>‐V characters escaped them
3710 instead of <backslash> characters). This was true in not only the com‐
3711 mand line, but also .exrc and sourced files. For example, the command:
3712
3713
3714 map = foo<control-V><newline>bar
3715
3716 would succeed, although it was sometimes difficult to get the <con‐
3717 trol>‐V and the inserted <newline> passed to the ex parser. For consis‐
3718 tency and simplicity of specification, POSIX.1‐2008 requires that it be
3719 possible to escape <newline> characters in ex commands at all times,
3720 using <backslash> characters for most ex commands, and using <con‐
3721 trol>‐V characters for the map and abbreviation commands. For example,
3722 the command print<newline>list is required to be parsed as the single
3723 command print<newline>list. While this differs from historical prac‐
3724 tice, POSIX.1‐2008 developers believed it unlikely that any script or
3725 user depended on the historical behavior.
3726
3727 Historically, an error in a command specified using the -c option did
3728 not cause the rest of the -c commands to be discarded. POSIX.1‐2008
3729 disallows this for consistency with mapped keys, the @, global, source,
3730 and v commands, the EXINIT environment variable, and the .exrc files.
3731
3732 Input Editing in ex
3733 One of the common uses of the historical ex editor is over slow network
3734 connections. Editors that run in canonical mode can require far less
3735 traffic to and from, and far less processing on, the host machine, as
3736 well as more easily supporting block-mode terminals. For these reasons,
3737 POSIX.1‐2008 requires that ex be implemented using canonical mode input
3738 processing, as was done historically.
3739
3740 POSIX.1‐2008 does not require the historical 4 BSD input editing char‐
3741 acters ``word erase'' or ``literal next''. For this reason, it is
3742 unspecified how they are handled by ex, although they must have the
3743 required effect. Implementations that resolve them after the line has
3744 been ended using a <newline> or <control>‐M character, and implementa‐
3745 tions that rely on the underlying system terminal support for this pro‐
3746 cessing, are both conforming. Implementations are strongly urged to
3747 use the underlying system functionality, if at all possible, for com‐
3748 patibility with other system text input interfaces.
3749
3750 Historically, when the eof character was used to decrement the autoin‐
3751 dent level, the cursor moved to display the new end of the autoindent
3752 characters, but did not move the cursor to a new line, nor did it erase
3753 the <control>‐D character from the line. POSIX.1‐2008 does not specify
3754 that the cursor remain on the same line or that the rest of the line is
3755 erased; however, implementations are strongly encouraged to provide the
3756 best possible user interface; that is, the cursor should remain on the
3757 same line, and any <control>‐D character on the line should be erased.
3758
3759 POSIX.1‐2008 does not require the historical 4 BSD input editing char‐
3760 acter ``reprint'', traditionally <control>‐R, which redisplayed the
3761 current input from the user. For this reason, and because the function‐
3762 ality cannot be implemented after the line has been terminated by the
3763 user, POSIX.1‐2008 makes no requirements about this functionality.
3764 Implementations are strongly urged to make this historical functional‐
3765 ity available, if possible.
3766
3767 Historically, <control>‐Q did not perform a literal next function in
3768 ex, as it did in vi. POSIX.1‐2008 requires conformance to historical
3769 practice to avoid breaking historical ex scripts and .exrc files.
3770
3771 eof
3772 Whether the eof character immediately modifies the autoindent charac‐
3773 ters in the prompt is left unspecified so that implementations can con‐
3774 form in the presence of systems that do not support this functionality.
3775 Implementations are encouraged to modify the line and redisplay it
3776 immediately, if possible.
3777
3778 The specification of the handling of the eof character differs from
3779 historical practice only in that eof characters are not discarded if
3780 they follow normal characters in the text input. Historically, they
3781 were always discarded.
3782
3783 Command Descriptions in ex
3784 Historically, several commands (for example, global, v, visual, s,
3785 write, wq, yank, !, <, >, &, and ~) were executable in empty files
3786 (that is, the default address(es) were 0), or permitted explicit
3787 addresses of 0 (for example, 0 was a valid address, or 0,0 was a valid
3788 range). Addresses of 0, or command execution in an empty file, make
3789 sense only for commands that add new text to the edit buffer or write
3790 commands (because users may wish to write empty files). POSIX.1‐2008
3791 requires this behavior for such commands and disallows it otherwise,
3792 for consistency and simplicity of specification.
3793
3794 A count to an ex command has been historically corrected to be no
3795 greater than the last line in a file; for example, in a five-line file,
3796 the command 1,6print would fail, but the command 1print300 would suc‐
3797 ceed. POSIX.1‐2008 requires conformance to historical practice.
3798
3799 Historically, the use of flags in ex commands could be obscure. General
3800 historical practice was as described by POSIX.1‐2008, but there were
3801 some special cases. For instance, the list, number, and print commands
3802 ignored trailing address offsets; for example, 3p +++# would display
3803 line 3, and 3 would be the current line after the execution of the com‐
3804 mand. The open and visual commands ignored both the trailing offsets
3805 and the trailing flags. Also, flags specified to the open and visual
3806 commands interacted badly with the list edit option, and setting and
3807 then unsetting it during the open/visual session would cause vi to stop
3808 displaying lines in the specified format. For consistency and simplic‐
3809 ity of specification, POSIX.1‐2008 does not permit any of these excep‐
3810 tions to the general rule.
3811
3812 POSIX.1‐2008 uses the word copy in several places when discussing buf‐
3813 fers. This is not intended to imply implementation.
3814
3815 Historically, ex users could not specify numeric buffers because of the
3816 ambiguity this would cause; for example, in the command 3 delete 2, it
3817 is unclear whether 2 is a buffer name or a count. POSIX.1‐2008
3818 requires conformance to historical practice by default, but does not
3819 preclude extensions.
3820
3821 Historically, the contents of the unnamed buffer were frequently dis‐
3822 carded after commands that did not explicitly affect it; for example,
3823 when using the edit command to switch files. For consistency and sim‐
3824 plicity of specification, POSIX.1‐2008 does not permit this behavior.
3825
3826 The ex utility did not historically have access to the numeric buffers,
3827 and, furthermore, deleting lines in ex did not modify their contents.
3828 For example, if, after doing a delete in vi, the user switched to ex,
3829 did another delete, and then switched back to vi, the contents of the
3830 numeric buffers would not have changed. POSIX.1‐2008 requires confor‐
3831 mance to historical practice. Numeric buffers are described in the ex
3832 utility in order to confine the description of buffers to a single
3833 location in POSIX.1‐2008.
3834
3835 The metacharacters that trigger shell expansion in file arguments match
3836 historical practice, as does the method for doing shell expansion.
3837 Implementations wishing to provide users with the flexibility to alter
3838 the set of metacharacters are encouraged to provide a shellmeta string
3839 edit option.
3840
3841 Historically, ex commands executed from vi refreshed the screen when it
3842 did not strictly need to do so; for example, :!date > /dev/null does
3843 not require a screen refresh because the output of the UNIX date com‐
3844 mand requires only a single line of the screen. POSIX.1‐2008 requires
3845 that the screen be refreshed if it has been overwritten, but makes no
3846 requirements as to how an implementation should make that determina‐
3847 tion. Implementations may prompt and refresh the screen regardless.
3848
3849 Abbreviate
3850 Historical practice was that characters that were entered as part of an
3851 abbreviation replacement were subject to map expansions, the showmatch
3852 edit option, further abbreviation expansions, and so on; that is, they
3853 were logically pushed onto the terminal input queue, and were not a
3854 simple replacement. POSIX.1‐2008 requires conformance to historical
3855 practice. Historical practice was that whenever a non-word character
3856 (that had not been escaped by a <control>‐V) was entered after a word
3857 character, vi would check for abbreviations. The check was based on the
3858 type of the character entered before the word character of the
3859 word/non-word pair that triggered the check. The word character of the
3860 word/non-word pair that triggered the check and all characters entered
3861 before the trigger pair that were of that type were included in the
3862 check, with the exception of <blank> characters, which always delimited
3863 the abbreviation.
3864
3865 This means that, for the abbreviation to work, the lhs must end with a
3866 word character, there can be no transitions from word to non-word char‐
3867 acters (or vice versa) other than between the last and next-to-last
3868 characters in the lhs, and there can be no <blank> characters in the
3869 lhs. In addition, because of the historical quoting rules, it was
3870 impossible to enter a literal <control>‐V in the lhs. POSIX.1‐2008
3871 requires conformance to historical practice. Historical implementations
3872 did not inform users when abbreviations that could never be used were
3873 entered; implementations are strongly encouraged to do so.
3874
3875 For example, the following abbreviations will work:
3876
3877
3878 :ab (p REPLACE
3879 :ab p REPLACE
3880 :ab ((p REPLACE
3881
3882 The following abbreviations will not work:
3883
3884
3885 :ab ( REPLACE
3886 :ab (pp REPLACE
3887
3888 Historical practice is that words on the vi colon command line were
3889 subject to abbreviation expansion, including the arguments to the
3890 abbrev (and more interestingly) the unabbrev command. Because there are
3891 implementations that do not do abbreviation expansion for the first
3892 argument to those commands, this is permitted, but not required, by
3893 POSIX.1‐2008. However, the following sequence:
3894
3895
3896 :ab foo bar
3897 :ab foo baz
3898
3899 resulted in the addition of an abbreviation of "baz" for the string
3900 "bar" in historical ex/vi, and the sequence:
3901
3902
3903 :ab foo1 bar
3904 :ab foo2 bar
3905 :unabbreviate foo2
3906
3907 deleted the abbreviation "foo1", not "foo2". These behaviors are not
3908 permitted by POSIX.1‐2008 because they clearly violate the expectations
3909 of the user.
3910
3911 It was historical practice that <control>‐V, not <backslash>, charac‐
3912 ters be interpreted as escaping subsequent characters in the abbreviate
3913 command. POSIX.1‐2008 requires conformance to historical practice; how‐
3914 ever, it should be noted that an abbreviation containing a <blank> will
3915 never work.
3916
3917 Append
3918 Historically, any text following a <vertical-line> command separator
3919 after an append, change, or insert command became part of the insert
3920 text. For example, in the command:
3921
3922
3923 :g/pattern/append|stuff1
3924
3925 a line containing the text "stuff1" would be appended to each line
3926 matching pattern. It was also historically valid to enter:
3927
3928
3929 :append|stuff1
3930 stuff2
3931 .
3932
3933 and the text on the ex command line would be appended along with the
3934 text inserted after it. There was an historical bug, however, that the
3935 user had to enter two terminating lines (the '.' lines) to terminate
3936 text input mode in this case. POSIX.1‐2008 requires conformance to his‐
3937 torical practice, but disallows the historical need for multiple termi‐
3938 nating lines.
3939
3940 Change
3941 See the RATIONALE for the append command. Historical practice for cur‐
3942 sor positioning after the change command when no text is input, is as
3943 described in POSIX.1‐2008. However, one System V implementation is
3944 known to have been modified such that the cursor is positioned on the
3945 first address specified, and not on the line before the first address.
3946 POSIX.1‐2008 disallows this modification for consistency.
3947
3948 Historically, the change command did not support buffer arguments,
3949 although some implementations allow the specification of an optional
3950 buffer. This behavior is neither required nor disallowed by
3951 POSIX.1‐2008.
3952
3953 Change Directory
3954 A common extension in ex implementations is to use the elements of a
3955 cdpath edit option as prefix directories for path arguments to chdir
3956 that are relative pathnames and that do not have '.' or ".." as their
3957 first component. Elements in the cdpath edit option are <colon>-sepa‐
3958 rated. The initial value of the cdpath edit option is the value of the
3959 shell CDPATH environment variable. This feature was not included in
3960 POSIX.1‐2008 because it does not exist in any of the implementations
3961 considered historical practice.
3962
3963 Copy
3964 Historical implementations of ex permitted copies to lines inside of
3965 the specified range; for example, :2,5copy3 was a valid command.
3966 POSIX.1‐2008 requires conformance to historical practice.
3967
3968 Delete
3969 POSIX.1‐2008 requires support for the historical parsing of a delete
3970 command followed by flags, without any intervening <blank> characters.
3971 For example:
3972
3973 1dp Deletes the first line and prints the line that was second.
3974
3975 1delep As for 1dp.
3976
3977 1d Deletes the first line, saving it in buffer p.
3978
3979 1d p1l (Pee-one-ell.) Deletes the first line, saving it in buffer p,
3980 and listing the line that was second.
3981
3982 Edit
3983 Historically, any ex command could be entered as a +command argument to
3984 the edit command, although some (for example, insert and append) were
3985 known to confuse historical implementations. For consistency and sim‐
3986 plicity of specification, POSIX.1‐2008 requires that any command be
3987 supported as an argument to the edit command.
3988
3989 Historically, the command argument was executed with the current line
3990 set to the last line of the file, regardless of whether the edit com‐
3991 mand was executed from visual mode or not. POSIX.1‐2008 requires con‐
3992 formance to historical practice.
3993
3994 Historically, the +command specified to the edit and next commands was
3995 delimited by the first <blank>, and there was no way to quote them. For
3996 consistency, POSIX.1‐2008 requires that the usual ex backslash quoting
3997 be provided.
3998
3999 Historically, specifying the +command argument to the edit command
4000 required a filename to be specified as well; for example, :edit +100
4001 would always fail. For consistency and simplicity of specification,
4002 POSIX.1‐2008 does not permit this usage to fail for that reason.
4003
4004 Historically, only the cursor position of the last file edited was
4005 remembered by the editor. POSIX.1‐2008 requires that this be supported;
4006 however, implementations are permitted to remember and restore the cur‐
4007 sor position for any file previously edited.
4008
4009 File
4010 Historical versions of the ex editor file command displayed a current
4011 line and number of lines in the edit buffer of 0 when the file was
4012 empty, while the vi <control>‐G command displayed a current line and
4013 number of lines in the edit buffer of 1 in the same situation.
4014 POSIX.1‐2008 does not permit this discrepancy, instead requiring that a
4015 message be displayed indicating that the file is empty.
4016
4017 Global
4018 The two-pass operation of the global and v commands is not intended to
4019 imply implementation, only the required result of the operation.
4020
4021 The current line and column are set as specified for the individual ex
4022 commands. This requirement is cumulative; that is, the current line and
4023 column must track across all the commands executed by the global or v
4024 commands.
4025
4026 Insert
4027 See the RATIONALE for the append command.
4028
4029 Historically, insert could not be used with an address of zero; that
4030 is, not when the edit buffer was empty. POSIX.1‐2008 requires that this
4031 command behave consistently with the append command.
4032
4033 Join
4034 The action of the join command in relation to the special characters is
4035 only defined for the POSIX locale because the correct amount of white
4036 space after a period varies; in Japanese none is required, in French
4037 only a single space, and so on.
4038
4039 List
4040 The historical output of the list command was potentially ambiguous.
4041 The standard developers believed correcting this to be more important
4042 than adhering to historical practice, and POSIX.1‐2008 requires unam‐
4043 biguous output.
4044
4045 Map
4046 Historically, command mode maps only applied to command names; for
4047 example, if the character 'x' was mapped to 'y', the command fx
4048 searched for the 'x' character, not the 'y' character. POSIX.1‐2008
4049 requires this behavior. Historically, entering <control>‐V as the first
4050 character of a vi command was an error. Several implementations have
4051 extended the semantics of vi such that <control>‐V means that the sub‐
4052 sequent command character is not mapped. This is permitted, but not
4053 required, by POSIX.1‐2008. Regardless, using <control>‐V to escape the
4054 second or later character in a sequence of characters that might match
4055 a map command, or any character in text input mode, is historical prac‐
4056 tice, and stops the entered keys from matching a map. POSIX.1‐2008
4057 requires conformance to historical practice.
4058
4059 Historical implementations permitted digits to be used as a map command
4060 lhs, but then ignored the map. POSIX.1‐2008 requires that the mapped
4061 digits not be ignored.
4062
4063 The historical implementation of the map command did not permit map
4064 commands that were more than a single character in length if the first
4065 character was printable. This behavior is permitted, but not required,
4066 by POSIX.1‐2008.
4067
4068 Historically, mapped characters were remapped unless the remap edit
4069 option was not set, or the prefix of the mapped characters matched the
4070 mapping characters; for example, in the map:
4071
4072
4073 :map ab abcd
4074
4075 the characters "ab" were used as is and were not remapped, but the
4076 characters "cd" were mapped if appropriate. This can cause infinite
4077 loops in the vi mapping mechanisms. POSIX.1‐2008 requires conformance
4078 to historical practice, and that such loops be interruptible.
4079
4080 Text input maps had the same problems with expanding the lhs for the ex
4081 map! and unmap! command as did the ex abbreviate and unabbreviate
4082 commands. See the RATIONALE for the ex abbreviate command. POSIX.1‐2008
4083 requires similar modification of some historical practice for the map
4084 and unmap commands, as described for the abbreviate and unabbreviate
4085 commands.
4086
4087 Historically, maps that were subsets of other maps behaved differently
4088 depending on the order in which they were defined. For example:
4089
4090
4091 :map! ab short
4092 :map! abc long
4093
4094 would always translate the characters "ab" to "short", regardless of
4095 how fast the characters "abc" were entered. If the entry order was
4096 reversed:
4097
4098
4099 :map! abc long
4100 :map! ab short
4101
4102 the characters "ab" would cause the editor to pause, waiting for the
4103 completing 'c' character, and the characters might never be mapped to
4104 "short". For consistency and simplicity of specification, POSIX.1‐2008
4105 requires that the shortest match be used at all times.
4106
4107 The length of time the editor spends waiting for the characters to com‐
4108 plete the lhs is unspecified because the timing capabilities of systems
4109 are often inexact and variable, and it may depend on other factors such
4110 as the speed of the connection. The time should be long enough for the
4111 user to be able to complete the sequence, but not long enough for the
4112 user to have to wait. Some implementations of vi have added a keytime
4113 option, which permits users to set the number of 0,1 seconds the editor
4114 waits for the completing characters. Because mapped terminal function
4115 and cursor keys tend to start with an <ESC> character, and <ESC> is the
4116 key ending vi text input mode, maps starting with <ESC> characters are
4117 generally exempted from this timeout period, or, at least timed out
4118 differently.
4119
4120 Mark
4121 Historically, users were able to set the ``previous context'' marks
4122 explicitly. In addition, the ex commands '' and '` and the vi commands
4123 '', ``, `', and '` all referred to the same mark. In addition, the pre‐
4124 vious context marks were not set if the command, with which the address
4125 setting the mark was associated, failed. POSIX.1‐2008 requires confor‐
4126 mance to historical practice. Historically, if marked lines were
4127 deleted, the mark was also deleted, but would reappear if the change
4128 was undone. POSIX.1‐2008 requires conformance to historical practice.
4129
4130 The description of the special events that set the ` and ' marks
4131 matches historical practice. For example, historically the command
4132 /a/,/b/ did not set the ` and ' marks, but the command /a/,/b/delete
4133 did.
4134
4135 Next
4136 Historically, any ex command could be entered as a +command argument to
4137 the next command, although some (for example, insert and append) were
4138 known to confuse historical implementations. POSIX.1‐2008 requires that
4139 any command be permitted and that it behave as specified. The next com‐
4140 mand can accept more than one file, so usage such as:
4141
4142
4143 next `ls [abc] `
4144
4145 is valid; it need not be valid for the edit or read commands, for exam‐
4146 ple, because they expect only one filename.
4147
4148 Historically, the next command behaved differently from the :rewind
4149 command in that it ignored the force flag if the autowrite flag was
4150 set. For consistency, POSIX.1‐2008 does not permit this behavior.
4151
4152 Historically, the next command positioned the cursor as if the file had
4153 never been edited before, regardless. POSIX.1‐2008 does not permit this
4154 behavior, for consistency with the edit command.
4155
4156 Implementations wanting to provide a counterpart to the next command
4157 that edited the previous file have used the command prev[ious], which
4158 takes no file argument. POSIX.1‐2008 does not require this command.
4159
4160 Open
4161 Historically, the open command would fail if the open edit option was
4162 not set. POSIX.1‐2008 does not mention the open edit option and does
4163 not require this behavior. Some historical implementations do not per‐
4164 mit entering open mode from open or visual mode, only from ex mode. For
4165 consistency, POSIX.1‐2008 does not permit this behavior.
4166
4167 Historically, entering open mode from the command line (that is, vi
4168 +open) resulted in anomalous behaviors; for example, the ex file and
4169 set commands, and the vi command <control>‐G did not work. For consis‐
4170 tency, POSIX.1‐2008 does not permit this behavior.
4171
4172 Historically, the open command only permitted '/' characters to be used
4173 as the search pattern delimiter. For consistency, POSIX.1‐2008 requires
4174 that the search delimiters used by the s, global, and v commands be
4175 accepted as well.
4176
4177 Preserve
4178 The preserve command does not historically cause the file to be consid‐
4179 ered unmodified for the purposes of future commands that may exit the
4180 editor. POSIX.1‐2008 requires conformance to historical practice.
4181
4182 Historical documentation stated that mail was not sent to the user when
4183 preserve was executed; however, historical implementations did send
4184 mail in this case. POSIX.1‐2008 requires conformance to the historical
4185 implementations.
4186
4187 Print
4188 The writing of NUL by the print command is not specified as a special
4189 case because the standard developers did not want to require ex to sup‐
4190 port NUL characters. Historically, characters were displayed using the
4191 ARPA standard mappings, which are as follows:
4192
4193 1. Printable characters are left alone.
4194
4195 2. Control characters less than \177 are represented as '^' followed
4196 by the character offset from the '@' character in the ASCII map;
4197 for example, \007 is represented as '^G'.
4198
4199 3. \177 is represented as '^' followed by '?'.
4200
4201 The display of characters having their eighth bit set was less stan‐
4202 dard. Existing implementations use hex (0x00), octal (\000), and a
4203 meta-bit display. (The latter displayed bytes that had their eighth bit
4204 set as the two characters "M-" followed by the seven-bit display as
4205 described above.) The latter probably has the best claim to historical
4206 practice because it was used for the -v option of 4 BSD and 4 BSD-
4207 derived versions of the cat utility since 1980.
4208
4209 No specific display format is required by POSIX.1‐2008.
4210
4211 Explicit dependence on the ASCII character set has been avoided where
4212 possible, hence the use of the phrase an ``implementation-defined
4213 multi-character sequence'' for the display of non-printable characters
4214 in preference to the historical usage of, for instance, "^I" for the
4215 <tab>. Implementations are encouraged to conform to historical prac‐
4216 tice in the absence of any strong reason to diverge.
4217
4218 Historically, all ex commands beginning with the letter 'p' could be
4219 entered using capitalized versions of the commands; for example,
4220 P[rint], Pre[serve], and Pu[t] were all valid command names.
4221 POSIX.1‐2008 permits, but does not require, this historical practice
4222 because capital forms of the commands are used by some implementations
4223 for other purposes.
4224
4225 Put
4226 Historically, an ex put command, executed from open or visual mode, was
4227 the same as the open or visual mode P command, if the buffer was named
4228 and was cut in character mode, and the same as the p command if the
4229 buffer was named and cut in line mode. If the unnamed buffer was the
4230 source of the text, the entire line from which the text was taken was
4231 usually put, and the buffer was handled as if in line mode, but it was
4232 possible to get extremely anomalous behavior. In addition, using the Q
4233 command to switch into ex mode, and then doing a put often resulted in
4234 errors as well, such as appending text that was unrelated to the (sup‐
4235 posed) contents of the buffer. For consistency and simplicity of speci‐
4236 fication, POSIX.1‐2008 does not permit these behaviors. All ex put com‐
4237 mands are required to operate in line mode, and the contents of the
4238 buffers are not altered by changing the mode of the editor.
4239
4240 Read
4241 Historically, an ex read command executed from open or visual mode,
4242 executed in an empty file, left an empty line as the first line of the
4243 file. For consistency and simplicity of specification, POSIX.1‐2008
4244 does not permit this behavior. Historically, a read in open or visual
4245 mode from a program left the cursor at the last line read in, not the
4246 first. For consistency, POSIX.1‐2008 does not permit this behavior.
4247
4248 Historical implementations of ex were unable to undo read commands that
4249 read from the output of a program. For consistency, POSIX.1‐2008 does
4250 not permit this behavior.
4251
4252 Historically, the ex and vi message after a successful read or write
4253 command specified ``characters'', not ``bytes''. POSIX.1‐2008 requires
4254 that the number of bytes be displayed, not the number of characters,
4255 because it may be difficult in multi-byte implementations to determine
4256 the number of characters read. Implementations are encouraged to clar‐
4257 ify the message displayed to the user.
4258
4259 Historically, reads were not permitted on files other than type regu‐
4260 lar, except that FIFO files could be read (probably only because they
4261 did not exist when ex and vi were originally written). Because the his‐
4262 torical ex evaluated read! and read ! equivalently, there can be no
4263 optional way to force the read. POSIX.1‐2008 permits, but does not
4264 require, this behavior.
4265
4266 Recover
4267 Some historical implementations of the editor permitted users to
4268 recover the edit buffer contents from a previous edit session, and then
4269 exit without saving those contents (or explicitly discarding them). The
4270 intent of POSIX.1‐2008 in requiring that the edit buffer be treated as
4271 already modified is to prevent this user error.
4272
4273 Rewind
4274 Historical implementations supported the rewind command when the user
4275 was editing the first file in the list; that is, the file that the
4276 rewind command would edit. POSIX.1‐2008 requires conformance to histor‐
4277 ical practice.
4278
4279 Substitute
4280 Historically, ex accepted an r option to the s command. The effect of
4281 the r option was to use the last regular expression used in any command
4282 as the pattern, the same as the ~ command. The r option is not required
4283 by POSIX.1‐2008. Historically, the c and g options were toggled; for
4284 example, the command :s/abc/def/ was the same as s/abc/def/ccccgggg.
4285 For simplicity of specification, POSIX.1‐2008 does not permit this
4286 behavior.
4287
4288 The tilde command is often used to replace the last search RE. For
4289 example, in the sequence:
4290
4291
4292 s/red/blue/
4293 /green
4294 ~
4295
4296 the ~ command is equivalent to:
4297
4298
4299 s/green/blue/
4300
4301 Historically, ex accepted all of the following forms:
4302
4303
4304 s/abc/def/
4305 s/abc/def
4306 s/abc/
4307 s/abc
4308
4309 POSIX.1‐2008 requires conformance to this historical practice.
4310
4311 The s command presumes that the '^' character only occupies a single
4312 column in the display. Much of the ex and vi specification presumes
4313 that the <space> only occupies a single column in the display. There
4314 are no known character sets for which this is not true.
4315
4316 Historically, the final column position for the substitute commands was
4317 based on previous column movements; a search for a pattern followed by
4318 a substitution would leave the column position unchanged, while a 0
4319 command followed by a substitution would change the column position to
4320 the first non-<blank>. For consistency and simplicity of specifica‐
4321 tion, POSIX.1‐2008 requires that the final column position always be
4322 set to the first non-<blank>.
4323
4324 Set
4325 Historical implementations redisplayed all of the options for each
4326 occurrence of the all keyword. POSIX.1‐2008 permits, but does not
4327 require, this behavior.
4328
4329 Tag
4330 No requirement is made as to where ex and vi shall look for the file
4331 referenced by the tag entry. Historical practice has been to look for
4332 the path found in the tags file, based on the current directory. A use‐
4333 ful extension found in some implementations is to look based on the
4334 directory containing the tags file that held the entry, as well. No
4335 requirement is made as to which reference for the tag in the tags file
4336 is used. This is deliberate, in order to permit extensions such as mul‐
4337 tiple entries in a tags file for a tag.
4338
4339 Because users often specify many different tags files, some of which
4340 need not be relevant or exist at any particular time, POSIX.1‐2008
4341 requires that error messages about problem tags files be displayed only
4342 if the requested tag is not found, and then, only once for each time
4343 that the tag edit option is changed.
4344
4345 The requirement that the current edit buffer be unmodified is only nec‐
4346 essary if the file indicated by the tag entry is not the same as the
4347 current file (as defined by the current pathname). Historically, the
4348 file would be reloaded if the filename had changed, as well as if the
4349 filename was different from the current pathname. For consistency and
4350 simplicity of specification, POSIX.1‐2008 does not permit this behav‐
4351 ior, requiring that the name be the only factor in the decision.
4352
4353 Historically, vi only searched for tags in the current file from the
4354 current cursor to the end of the file, and therefore, if the wrapscan
4355 option was not set, tags occurring before the current cursor were not
4356 found. POSIX.1‐2008 considers this a bug, and implementations are
4357 required to search for the first occurrence in the file, regardless.
4358
4359 Undo
4360 The undo description deliberately uses the word ``modified''. The undo
4361 command is not intended to undo commands that replace the contents of
4362 the edit buffer, such as edit, next, tag, or recover.
4363
4364 Cursor positioning after the undo command was inconsistent in the his‐
4365 torical vi, sometimes attempting to restore the original cursor posi‐
4366 tion (global, undo, and v commands), and sometimes, in the presence of
4367 maps, placing the cursor on the last line added or changed instead of
4368 the first. POSIX.1‐2008 requires a simplified behavior for consistency
4369 and simplicity of specification.
4370
4371 Version
4372 The version command cannot be exactly specified since there is no
4373 widely-accepted definition of what the version information should con‐
4374 tain. Implementations are encouraged to do something reasonably intel‐
4375 ligent.
4376
4377 Write
4378 Historically, the ex and vi message after a successful read or write
4379 command specified ``characters'', not ``bytes''. POSIX.1‐2008 requires
4380 that the number of bytes be displayed, not the number of characters
4381 because it may be difficult in multi-byte implementations to determine
4382 the number of characters written. Implementations are encouraged to
4383 clarify the message displayed to the user.
4384
4385 Implementation-defined tests are permitted so that implementations can
4386 make additional checks; for example, for locks or file modification
4387 times.
4388
4389 Historically, attempting to append to a nonexistent file caused an
4390 error. It has been left unspecified in POSIX.1‐2008 to permit implemen‐
4391 tations to let the write succeed, so that the append semantics are sim‐
4392 ilar to those of the historical csh.
4393
4394 Historical vi permitted empty edit buffers to be written. However,
4395 since the way vi got around dealing with ``empty'' files was to always
4396 have a line in the edit buffer, no matter what, it wrote them as files
4397 of a single, empty line. POSIX.1‐2008 does not permit this behavior.
4398
4399 Historically, ex restored standard output and standard error to their
4400 values as of when ex was invoked, before writes to programs were per‐
4401 formed. This could disturb the terminal configuration as well as be a
4402 security issue for some terminals. POSIX.1‐2008 does not permit this,
4403 requiring that the program output be captured and displayed as if by
4404 the ex print command.
4405
4406 Adjust Window
4407 Historically, the line count was set to the value of the scroll option
4408 if the type character was end-of-file. This feature was broken on most
4409 historical implementations long ago, however, and is not documented
4410 anywhere. For this reason, POSIX.1‐2008 is resolutely silent.
4411
4412 Historically, the z command was <blank>-sensitive and z + and z - did
4413 different things than z+ and z- because the type could not be distin‐
4414 guished from a flag. (The commands z . and z = were historically
4415 invalid.) POSIX.1‐2008 requires conformance to this historical prac‐
4416 tice.
4417
4418 Historically, the z command was further <blank>-sensitive in that the
4419 count could not be <blank>-delimited; for example, the commands z= 5
4420 and z- 5 were also invalid. Because the count is not ambiguous with
4421 respect to either the type character or the flags, this is not permit‐
4422 ted by POSIX.1‐2008.
4423
4424 Escape
4425 Historically, ex filter commands only read the standard output of the
4426 commands, letting standard error appear on the terminal as usual. The
4427 vi utility, however, read both standard output and standard error.
4428 POSIX.1‐2008 requires the latter behavior for both ex and vi, for con‐
4429 sistency.
4430
4431 Shift Left and Shift Right
4432 Historically, it was possible to add shift characters to increase the
4433 effect of the command; for example, <<< outdented (or >>> indented) the
4434 lines 3 levels of indentation instead of the default 1. POSIX.1‐2008
4435 requires conformance to historical practice.
4436
4437 <control>‐D
4438 Historically, the <control>‐D command erased the prompt, providing the
4439 user with an unbroken presentation of lines from the edit buffer. This
4440 is not required by POSIX.1‐2008; implementations are encouraged to pro‐
4441 vide it if possible. Historically, the <control>‐D command took, and
4442 then ignored, a count. POSIX.1‐2008 does not permit this behavior.
4443
4444 Write Line Number
4445 Historically, the ex = command, when executed in ex mode in an empty
4446 edit buffer, reported 0, and from open or visual mode, reported 1. For
4447 consistency and simplicity of specification, POSIX.1‐2008 does not per‐
4448 mit this behavior.
4449
4450 Execute
4451 Historically, ex did not correctly handle the inclusion of text input
4452 commands (that is, append, insert, and change) in executed buffers.
4453 POSIX.1‐2008 does not permit this exclusion for consistency.
4454
4455 Historically, the logical contents of the buffer being executed did not
4456 change if the buffer itself were modified by the commands being exe‐
4457 cuted; that is, buffer execution did not support self-modifying code.
4458 POSIX.1‐2008 requires conformance to historical practice.
4459
4460 Historically, the @ command took a range of lines, and the @ buffer was
4461 executed once per line, with the current line ('.') set to each speci‐
4462 fied line. POSIX.1‐2008 requires conformance to historical practice.
4463
4464 Some historical implementations did not notice if errors occurred dur‐
4465 ing buffer execution. This, coupled with the ability to specify a range
4466 of lines for the ex @ command, makes it trivial to cause them to drop
4467 core. POSIX.1‐2008 requires that implementations stop buffer execution
4468 if any error occurs, if the specified line doesn't exist, or if the
4469 contents of the edit buffer itself are replaced (for example, the buf‐
4470 fer executes the ex :edit command).
4471
4472 Regular Expressions in ex
4473 Historical practice is that the characters in the replacement part of
4474 the last s command—that is, those matched by entering a '~' in the reg‐
4475 ular expression—were not further expanded by the regular expression
4476 engine. So, if the characters contained the string "a.," they would
4477 match 'a' followed by ".," and not 'a' followed by any character.
4478 POSIX.1‐2008 requires conformance to historical practice.
4479
4480 Edit Options in ex
4481 The following paragraphs describe the historical behavior of some edit
4482 options that were not, for whatever reason, included in POSIX.1‐2008.
4483 Implementations are strongly encouraged to only use these names if the
4484 functionality described here is fully supported.
4485
4486 extended The extended edit option has been used in some implementa‐
4487 tions of vi to provide extended regular expressions instead
4488 of basic regular expressions This option was omitted from
4489 POSIX.1‐2008 because it is not widespread historical prac‐
4490 tice.
4491
4492 flash The flash edit option historically caused the screen to flash
4493 instead of beeping on error. This option was omitted from
4494 POSIX.1‐2008 because it is not found in some historical
4495 implementations.
4496
4497 hardtabs The hardtabs edit option historically defined the number of
4498 columns between hardware tab settings. This option was omit‐
4499 ted from POSIX.1‐2008 because it was believed to no longer be
4500 generally useful.
4501
4502 modeline The modeline (sometimes named modelines) edit option histori‐
4503 cally caused ex or vi to read the five first and last lines
4504 of the file for editor commands. This option is a security
4505 problem, and vendors are strongly encouraged to delete it
4506 from historical implementations.
4507
4508 open The open edit option historically disallowed the ex open and
4509 visual commands. This edit option was omitted because these
4510 commands are required by POSIX.1‐2008.
4511
4512 optimize The optimize edit option historically expedited text through‐
4513 put by setting the terminal to not do automatic <carriage-
4514 return> characters when printing more than one logical line
4515 of output. This option was omitted from POSIX.1‐2008 because
4516 it was intended for terminals without addressable cursors,
4517 which are rarely, if ever, still used.
4518
4519 ruler The ruler edit option has been used in some implementations
4520 of vi to present a current row/column ruler for the user.
4521 This option was omitted from POSIX.1‐2008 because it is not
4522 widespread historical practice.
4523
4524 sourceany The sourceany edit option historically caused ex or vi to
4525 source start-up files that were owned by users other than the
4526 user running the editor. This option is a security problem,
4527 and vendors are strongly encouraged to remove it from their
4528 implementations.
4529
4530 timeout The timeout edit option historically enabled the (now stan‐
4531 dard) feature of only waiting for a short period before
4532 returning keys that could be part of a macro. This feature
4533 was omitted from POSIX.1‐2008 because its behavior is now
4534 standard, it is not widely useful, and it was rarely docu‐
4535 mented.
4536
4537 verbose The verbose edit option has been used in some implementations
4538 of vi to cause vi to output error messages for common errors;
4539 for example, attempting to move the cursor past the beginning
4540 or end of the line instead of only alerting the screen. (The
4541 historical vi only alerted the terminal and presented no mes‐
4542 sage for such errors. The historical editor option terse did
4543 not select when to present error messages, it only made
4544 existing error messages more or less verbose.) This option
4545 was omitted from POSIX.1‐2008 because it is not widespread
4546 historical practice; however, implementors are encouraged to
4547 use it if they wish to provide error messages for naive
4548 users.
4549
4550 wraplen The wraplen edit option has been used in some implementations
4551 of vi to specify an automatic margin measured from the left
4552 margin instead of from the right margin. This is useful when
4553 multiple screen sizes are being used to edit a single file.
4554 This option was omitted from POSIX.1‐2008 because it is not
4555 widespread historical practice; however, implementors are
4556 encouraged to use it if they add this functionality.
4557
4558 autoindent, ai
4559 Historically, the command 0a did not do any autoindentation, regardless
4560 of the current indentation of line 1. POSIX.1‐2008 requires that any
4561 indentation present in line 1 be used.
4562
4563 autoprint, ap
4564 Historically, the autoprint edit option was not completely consistent
4565 or based solely on modifications to the edit buffer. Exceptions were
4566 the read command (when reading from a file, but not from a filter), the
4567 append, change, insert, global, and v commands, all of which were not
4568 affected by autoprint, and the tag command, which was affected by auto‐
4569 print. POSIX.1‐2008 requires conformance to historical practice.
4570
4571 Historically, the autoprint option only applied to the last of multiple
4572 commands entered using <vertical-line> delimiters; for example, delete
4573 <newline> was affected by autoprint, but delete|version <newline> was
4574 not. POSIX.1‐2008 requires conformance to historical practice.
4575
4576 autowrite, aw
4577 Appending the '!' character to the ex next command to avoid performing
4578 an automatic write was not supported in historical implementations.
4579 POSIX.1‐2008 requires that the behavior match the other ex commands for
4580 consistency.
4581
4582 ignorecase, ic
4583 Historical implementations of case-insensitive matching (the ignorecase
4584 edit option) lead to counter-intuitive situations when uppercase char‐
4585 acters were used in range expressions. Historically, the process was as
4586 follows:
4587
4588 1. Take a line of text from the edit buffer.
4589
4590 2. Convert uppercase to lowercase in text line.
4591
4592 3. Convert uppercase to lowercase in regular expressions, except in
4593 character class specifications.
4594
4595 4. Match regular expressions against text.
4596
4597 This would mean that, with ignorecase in effect, the text:
4598
4599
4600 The cat sat on the mat
4601
4602 would be matched by
4603
4604
4605 /^the/
4606
4607 but not by:
4608
4609
4610 /^[A-Z]he/
4611
4612 For consistency with other commands implementing regular expressions,
4613 POSIX.1‐2008 does not permit this behavior.
4614
4615 paragraphs, para
4616 The ISO POSIX‐2:1993 standard made the default paragraphs and sections
4617 edit options implementation-defined, arguing they were historically
4618 oriented to the UNIX system troff text formatter, and a ``portable
4619 user'' could use the {, }, [[, ]], (, and ) commands in open or visual
4620 mode and have the cursor stop in unexpected places. POSIX.1‐2008 speci‐
4621 fies their values in the POSIX locale because the unusual grouping
4622 (they only work when grouped into two characters at a time) means that
4623 they cannot be used for general-purpose movement, regardless.
4624
4625 readonly
4626 Implementations are encouraged to provide the best possible information
4627 to the user as to the read-only status of the file, with the exception
4628 that they should not consider the current special privileges of the
4629 process. This provides users with a safety net because they must force
4630 the overwrite of read-only files, even when running with additional
4631 privileges.
4632
4633 The readonly edit option specification largely conforms to historical
4634 practice. The only difference is that historical implementations did
4635 not notice that the user had set the readonly edit option in cases
4636 where the file was already marked read-only for some reason, and would
4637 therefore reinitialize the readonly edit option the next time the con‐
4638 tents of the edit buffer were replaced. This behavior is disallowed by
4639 POSIX.1‐2008.
4640
4641 report
4642 The requirement that lines copied to a buffer interact differently than
4643 deleted lines is historical practice. For example, if the report edit
4644 option is set to 3, deleting 3 lines will cause a report to be written,
4645 but 4 lines must be copied before a report is written.
4646
4647 The requirement that the ex global, v, open, undo, and visual commands
4648 present reports based on the total number of lines added or deleted
4649 during the command execution, and that commands executed by the global
4650 and v commands not present reports, is historical practice.
4651 POSIX.1‐2008 extends historical practice by requiring that buffer exe‐
4652 cution be treated similarly. The reasons for this are two-fold. Histor‐
4653 ically, only the report by the last command executed from the buffer
4654 would be seen by the user, as each new report would overwrite the last.
4655 In addition, the standard developers believed that buffer execution had
4656 more in common with global and v commands than it did with other ex
4657 commands, and should behave similarly, for consistency and simplicity
4658 of specification.
4659
4660 showmatch, sm
4661 The length of time the cursor spends on the matching character is
4662 unspecified because the timing capabilities of systems are often inex‐
4663 act and variable. The time should be long enough for the user to
4664 notice, but not long enough for the user to become annoyed. Some imple‐
4665 mentations of vi have added a matchtime option that permits users to
4666 set the number of 0,1 second intervals the cursor pauses on the match‐
4667 ing character.
4668
4669 showmode
4670 The showmode option has been used in some historical implementations of
4671 ex and vi to display the current editing mode when in open or visual
4672 mode. The editing modes have generally included ``command'' and
4673 ``input'', and sometimes other modes such as ``replace'' and
4674 ``change''. The string was usually displayed on the bottom line of the
4675 screen at the far right-hand corner. In addition, a preceding '*' char‐
4676 acter often denoted whether the contents of the edit buffer had been
4677 modified. The latter display has sometimes been part of the showmode
4678 option, and sometimes based on another option. This option was not
4679 available in the 4 BSD historical implementation of vi, but was viewed
4680 as generally useful, particularly to novice users, and is required by
4681 POSIX.1‐2008.
4682
4683 The smd shorthand for the showmode option was not present in all his‐
4684 torical implementations of the editor. POSIX.1‐2008 requires it, for
4685 consistency.
4686
4687 Not all historical implementations of the editor displayed a mode
4688 string for command mode, differentiating command mode from text input
4689 mode by the absence of a mode string. POSIX.1‐2008 permits this behav‐
4690 ior for consistency with historical practice, but implementations are
4691 encouraged to provide a display string for both modes.
4692
4693 slowopen
4694 Historically, the slowopen option was automatically set if the terminal
4695 baud rate was less than 1200 baud, or if the baud rate was 1200 baud
4696 and the redraw option was not set. The slowopen option had two effects.
4697 First, when inserting characters in the middle of a line, characters
4698 after the cursor would not be pushed ahead, but would appear to be
4699 overwritten. Second, when creating a new line of text, lines after the
4700 current line would not be scrolled down, but would appear to be over‐
4701 written. In both cases, ending text input mode would cause the screen
4702 to be refreshed to match the actual contents of the edit buffer.
4703 Finally, terminals that were sufficiently intelligent caused the editor
4704 to ignore the slowopen option. POSIX.1‐2008 permits most historical
4705 behavior, extending historical practice to require slowopen behaviors
4706 if the edit option is set by the user.
4707
4708 tags
4709 The default path for tags files is left unspecified as implementations
4710 may have their own tags implementations that do not correspond to the
4711 historical ones. The default tags option value should probably at least
4712 include the file ./tags.
4713
4714 term
4715 Historical implementations of ex and vi ignored changes to the term
4716 edit option after the initial terminal information was loaded. This is
4717 permitted by POSIX.1‐2008; however, implementations are encouraged to
4718 permit the user to modify their terminal type at any time.
4719
4720 terse
4721 Historically, the terse edit option optionally provided a shorter, less
4722 descriptive error message, for some error messages. This is permitted,
4723 but not required, by POSIX.1‐2008. Historically, most common visual
4724 mode errors (for example, trying to move the cursor past the end of a
4725 line) did not result in an error message, but simply alerted the termi‐
4726 nal. Implementations wishing to provide messages for novice users are
4727 urged to do so based on the edit option verbose, and not terse.
4728
4729 window
4730 In historical implementations, the default for the window edit option
4731 was based on the baud rate as follows:
4732
4733 1. If the baud rate was less than 1200, the edit option w300 set the
4734 window value; for example, the line:
4735
4736
4737 set w300=12
4738
4739 would set the window option to 12 if the baud rate was less than
4740 1200.
4741
4742 2. If the baud rate was equal to 1200, the edit option w1200 set the
4743 window value.
4744
4745 3. If the baud rate was greater than 1200, the edit option w9600 set
4746 the window value.
4747
4748 The w300, w1200, and w9600 options do not appear in POSIX.1‐2008
4749 because of their dependence on specific baud rates.
4750
4751 In historical implementations, the size of the window displayed by var‐
4752 ious commands was related to, but not necessarily the same as, the win‐
4753 dow edit option. For example, the size of the window was set by the ex
4754 command visual 10, but it did not change the value of the window edit
4755 option. However, changing the value of the window edit option did
4756 change the number of lines that were displayed when the screen was
4757 repainted. POSIX.1‐2008 does not permit this behavior in the interests
4758 of consistency and simplicity of specification, and requires that all
4759 commands that change the number of lines that are displayed do it by
4760 setting the value of the window edit option.
4761
4762 wrapmargin, wm
4763 Historically, the wrapmargin option did not affect maps inserting char‐
4764 acters that also had associated counts; for example :map K 5aABC DEF.
4765 Unfortunately, there are widely used maps that depend on this behavior.
4766 For consistency and simplicity of specification, POSIX.1‐2008 does not
4767 permit this behavior.
4768
4769 Historically, wrapmargin was calculated using the column display width
4770 of all characters on the screen. For example, an implementation using
4771 "^I" to represent <tab> characters when the list edit option was set,
4772 where '^' and 'I' each took up a single column on the screen, would
4773 calculate the wrapmargin based on a value of 2 for each <tab>. The
4774 number edit option similarly changed the effective length of the line
4775 as well. POSIX.1‐2008 requires conformance to historical practice.
4776
4777 Earlier versions of this standard allowed for implementations with
4778 bytes other than eight bits, but this has been modified in this ver‐
4779 sion.
4780
4782 None.
4783
4785 Section 2.9.1.1, Command Search and Execution, ctags, ed, sed, sh,
4786 stty, vi
4787
4788 The Base Definitions volume of POSIX.1‐2017, Table 5-1, Escape
4789 Sequences and Associated Actions, Chapter 8, Environment Variables,
4790 Section 9.3, Basic Regular Expressions, Section 12.2, Utility Syntax
4791 Guidelines
4792
4793 The System Interfaces volume of POSIX.1‐2017, access()
4794
4796 Portions of this text are reprinted and reproduced in electronic form
4797 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
4798 table Operating System Interface (POSIX), The Open Group Base Specifi‐
4799 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
4800 Electrical and Electronics Engineers, Inc and The Open Group. In the
4801 event of any discrepancy between this version and the original IEEE and
4802 The Open Group Standard, the original IEEE and The Open Group Standard
4803 is the referee document. The original Standard can be obtained online
4804 at http://www.opengroup.org/unix/online.html .
4805
4806 Any typographical or formatting errors that appear in this page are
4807 most likely to have been introduced during the conversion of the source
4808 files to man page format. To report such errors, see https://www.ker‐
4809 nel.org/doc/man-pages/reporting_bugs.html .
4810
4811
4812
4813IEEE/The Open Group 2017 EX(1P)