xref: /freebsd/contrib/nvi/man/vi.1 (revision 7ef62cebc2f965b0f640263e179276928885e33d)
1.\" Copyright (c) 1994
2.\"     The Regents of the University of California.  All rights reserved.
3.\" Copyright (c) 1994, 1995, 1996
4.\"	Keith Bostic.  All rights reserved.
5.\" Copyright (c) 2011
6.\"	Zhihao Yuan.  All rights reserved.
7.\"
8.\" The vi program is freely redistributable.
9.\" You are welcome to copy, modify and share it with others
10.\" under the conditions listed in the LICENSE file.
11.\" If any company (not individual!) finds vi sufficiently useful
12.\" that you would have purchased it, or if any company wishes to
13.\" redistribute it, contributions to the authors would be appreciated.
14.\"
15.Dd September 25, 2020
16.Dt VI 1
17.Os
18.Sh NAME
19.Nm ex , vi , view
20.Nd text editors
21.Sh SYNOPSIS
22.Nm ex
23.Op Fl FRrSsv
24.Op Fl c Ar cmd
25.Op Fl t Ar tag
26.Op Fl w Ar size
27.Op Ar
28.Nm vi\ \&
29.Op Fl eFRrS
30.Op Fl c Ar cmd
31.Op Fl t Ar tag
32.Op Fl w Ar size
33.Op Ar
34.Nm view
35.Op Fl eFrS
36.Op Fl c Ar cmd
37.Op Fl t Ar tag
38.Op Fl w Ar size
39.Op Ar
40.Sh DESCRIPTION
41.Nm vi
42is a screen-oriented text editor.
43.Nm ex
44is a line-oriented text editor.
45.Nm ex
46and
47.Nm vi
48are different interfaces to the same program,
49and it is possible to switch back and forth during an edit session.
50.Nm view
51is the equivalent of using the
52.Fl R
53.Pq read-only
54option of
55.Nm vi .
56.Pp
57This manual page is the one provided with the
58.Nm nex Ns / Ns Nm nvi
59versions of the
60.Nm ex Ns / Ns Nm vi
61text editors.
62.Nm nex Ns / Ns Nm nvi
63are intended as bug-for-bug compatible replacements for the original
64Fourth Berkeley Software Distribution
65.Pq 4BSD
66.Nm ex
67and
68.Nm vi
69programs.
70For the rest of this manual page,
71.Nm nex Ns / Ns Nm nvi
72is used only when it's necessary to distinguish it from the historic
73implementations of
74.Nm ex Ns / Ns Nm vi .
75.Pp
76This manual page is intended for users already familiar with
77.Nm ex Ns / Ns Nm vi .
78Anyone else should almost certainly read a good tutorial on the
79editor before this manual page.
80If you're in an unfamiliar environment,
81and you absolutely have to get work done immediately,
82read the section after the options description, entitled
83.Sx FAST STARTUP .
84It's probably enough to get you going.
85.Pp
86The following options are available:
87.Bl -tag -width "-w size "
88.It Fl c Ar cmd
89Execute
90.Ar cmd
91on the first file loaded.
92Particularly useful for initial positioning in the file, although
93.Ar cmd
94is not limited to positioning commands.
95This is the POSIX 1003.2 interface for the historic
96.Dq +cmd
97syntax.
98.Nm nex Ns / Ns Nm nvi
99supports both the old and new syntax.
100.It Fl e
101Start editing in ex mode, as if the command name were
102.Nm ex .
103.It Fl F
104Don't copy the entire file when first starting to edit.
105(The default is to make a copy in case someone else modifies
106the file during your edit session.)
107.\" .It Fl l
108.\" Start editing with the lisp and showmatch options set.
109.It Fl R
110Start editing in read-only mode, as if the command name was
111.Nm view ,
112or the
113.Cm readonly
114option was set.
115.It Fl r
116Recover the specified files, or, if no files are specified,
117list the files that could be recovered.
118If no recoverable files by the specified name exist,
119the file is edited as if the
120.Fl r
121option had not been specified.
122.It Fl S
123Run with the
124.Cm secure
125edit option set, disallowing all access to external programs.
126.It Fl s
127Enter batch mode; applicable only to
128.Nm ex
129edit sessions.
130Batch mode is useful when running
131.Nm ex
132scripts.
133Prompts, informative messages and other user oriented messages are turned off,
134and no startup files or environment variables are read.
135This is the POSIX 1003.2 interface for the historic
136.Dq -
137argument.
138.Nm nex Ns / Ns Nm nvi
139supports both the old and new syntax.
140.It Fl t Ar tag
141Start editing at the specified
142.Ar tag
143.Pq see Xr ctags 1 .
144.It Fl v
145Start editing in vi mode, as if the command name was
146.Nm vi .
147.It Fl w Ar size
148Set the initial window size to the specified number of lines.
149.El
150.Pp
151Command input for
152.Nm ex Ns / Ns Nm vi
153is read from the standard input.
154In the
155.Nm vi
156interface, it is an error if standard input is not a terminal.
157In the
158.Nm ex
159interface, if standard input is not a terminal,
160.Nm ex
161will read commands from it regardless; however, the session will be a
162batch mode session, exactly as if the
163.Fl s
164option had been specified.
165.Sh FAST STARTUP
166This section will tell you the minimum amount that you need to
167do simple editing tasks using
168.Nm vi .
169If you've never used any screen editor before,
170you're likely to have problems even with this simple introduction.
171In that case you should find someone that already knows
172.Nm vi
173and have them walk you through this section.
174.Pp
175.Nm vi
176is a screen editor.
177This means that it takes up almost the entire screen,
178displaying part of the file on each screen line,
179except for the last line of the screen.
180The last line of the screen is used for you to give commands to
181.Nm vi ,
182and for
183.Nm vi
184to give information to you.
185.Pp
186The other fact that you need to understand is that
187.Nm vi
188is a modeful editor,
189i.e., you are either entering text or you are executing commands,
190and you have to be in the right mode to do one or the other.
191You will be in command mode when you first start editing a file.
192There are commands that switch you into input mode.
193There is only one key that takes you out of input mode,
194and that is the
195.Aq escape
196key.
197.Pp
198In this manual,
199key names are denoted with \(la and \(ra, e.g.,
200.Aq escape
201means the
202.Dq escape
203key, usually labeled
204.Dq Esc
205on your terminal's keyboard.
206If you're ever confused as to which mode you're in,
207keep entering the
208.Aq escape
209key until
210.Nm vi
211beeps at you.
212Generally,
213.Nm vi
214will beep at you if you try and do something that's not allowed.
215It will also display error messages.
216.Pp
217To start editing a file, enter the following command:
218.Pp
219.Dl $ vi file
220.Pp
221The command you should enter as soon as you start editing is:
222.Pp
223.Dl :set verbose showmode
224.Pp
225This will make the editor give you verbose error messages and display
226the current mode at the bottom of the screen.
227.Pp
228The commands to move around the file are:
229.Bl -tag -width Ds
230.It Cm h
231Move the cursor left one character.
232.It Cm j
233Move the cursor down one line.
234.It Cm k
235Move the cursor up one line.
236.It Cm l
237Move the cursor right one character.
238.It Aq Cm cursor-arrows
239The cursor arrow keys should work, too.
240.It Cm / Ns Ar text
241Search for the string
242.Dq Ar text
243in the file,
244and move the cursor to its first character.
245.El
246.Pp
247The commands to enter new text are:
248.Bl -tag -width "<escape>"
249.It Cm a
250Append new text, after the cursor.
251.It Cm i
252Insert new text, before the cursor.
253.It Cm o
254Open a new line below the line the cursor is on, and start entering text.
255.It Cm O
256Open a new line above the line the cursor is on, and start entering text.
257.It Aq Cm escape
258Once you've entered input mode using one of the
259.Cm a ,
260.Cm i ,
261.Cm o
262or
263.Cm O
264commands, use
265.Aq Cm escape
266to quit entering text and return to command mode.
267.El
268.Pp
269The commands to copy text are:
270.Bl -tag -width Ds
271.It Cm yy
272Copy the line the cursor is on.
273.It Cm p
274Append the copied line after the line the cursor is on.
275.El
276.Pp
277The commands to delete text are:
278.Bl -tag -width Ds
279.It Cm dd
280Delete the line the cursor is on.
281.It Cm x
282Delete the character the cursor is on.
283.El
284.Pp
285The commands to write the file are:
286.Bl -tag -width Ds
287.It Cm :w
288Write the file back to the file with the name that you originally used
289as an argument on the
290.Nm vi
291command line.
292.It Cm :w Ar file_name
293Write the file back to the file with the name
294.Ar file_name .
295.El
296.Pp
297The commands to quit editing and exit the editor are:
298.Bl -tag -width Ds
299.It Cm :q
300Quit editing and leave
301.Nm vi
302(if you've modified the file, but not saved your changes,
303.Nm vi
304will refuse to quit).
305.It Cm :q!
306Quit, discarding any modifications that you may have made.
307.El
308.Pp
309One final caution:
310Unusual characters can take up more than one column on the screen,
311and long lines can take up more than a single screen line.
312The above commands work on
313.Dq physical
314characters and lines,
315i.e., they affect the entire line no matter how many screen lines it takes up
316and the entire character no matter how many screen columns it takes up.
317.Sh REGULAR EXPRESSIONS
318.Nm ex Ns / Ns Nm vi
319supports regular expressions
320.Pq REs ,
321as documented in
322.Xr re_format 7 ,
323for line addresses, as the first part of the
324.Nm ex Cm substitute ,
325.Cm global
326and
327.Cm v
328commands, and in search patterns.
329Basic regular expressions
330.Pq BREs
331are enabled by default;
332extended regular expressions
333.Pq EREs
334are used if the
335.Cm extended
336option is enabled.
337The use of regular expressions can be largely disabled using the
338.Cm magic
339option.
340.Pp
341The following strings have special meanings in the
342.Nm ex Ns / Ns Nm vi
343version of regular expressions:
344.Bl -bullet -offset 6u
345.It
346An empty regular expression is equivalent to the last regular expression used.
347.It
348.Sq \e<
349matches the beginning of the word.
350.It
351.Sq \e>
352matches the end of the word.
353.It
354.Sq \(ti
355matches the replacement part of the last
356.Cm substitute
357command.
358.El
359.Sh BUFFERS
360A buffer is an area where commands can save changed or deleted text
361for later use.
362.Nm vi
363buffers are named with a single character preceded by a double quote,
364for example
365.Cm \&" Ns Aq Ar c ;
366.Nm ex
367buffers are the same,
368but without the double quote.
369.Nm nex Ns / Ns Nm nvi
370permits the use of any character without another meaning in the position where
371a buffer name is expected.
372.Pp
373All buffers are either in
374.Em line mode
375or
376.Em character mode .
377Inserting a buffer in line mode into the text creates new lines for each of the
378lines it contains, while a buffer in character mode creates new lines for any
379lines
380.Em other
381than the first and last lines it contains.
382The first and last lines are inserted at the current cursor position, becoming
383part of the current line.
384If there is more than one line in the buffer,
385the current line itself will be split.
386All
387.Nm ex
388commands which store text into buffers do so in line mode.
389The behaviour of
390.Nm vi
391commands depend on their associated motion command:
392.Bl -bullet -offset 6u
393.It
394.Aq Cm control-A ,
395.Cm h ,
396.Cm l ,
397.Cm ,\& ,
398.Cm 0 ,
399.Cm B ,
400.Cm E ,
401.Cm F ,
402.Cm T ,
403.Cm W ,
404.Cm \(ha ,
405.Cm b ,
406.Cm e ,
407.Cm f
408and
409.Cm t
410make the destination buffer character-oriented.
411.It
412.Cm j ,
413.Aq Cm control-M ,
414.Cm k ,
415.Cm \(aq ,
416.Cm - ,
417.Cm G ,
418.Cm H ,
419.Cm L ,
420.Cm M ,
421.Cm _
422and
423.Cm |\&
424make the destination buffer line-oriented.
425.It
426.Cm $ ,
427.Cm % ,
428.Cm \` ,
429.Cm (\& ,
430.Cm )\& ,
431.Cm / ,
432.Cm ?\& ,
433.Cm [[ ,
434.Cm ]] ,
435.Cm {
436and
437.Cm }
438make the destination buffer character-oriented, unless the starting and
439end positions are the first and last characters on a line.
440In that case, the buffer is line-oriented.
441.El
442.Pp
443The
444.Nm ex
445command
446.Cm display buffers
447displays the current mode for each buffer.
448.Pp
449Buffers named
450.Sq a
451through
452.Sq z
453may be referred to using their uppercase equivalent, in which case new content
454will be appended to the buffer, instead of replacing it.
455.Pp
456Buffers named
457.Sq 1
458through
459.Sq 9
460are special.
461A region of text modified using the
462.Cm c
463.Pq change
464or
465.Cm d
466.Pq delete
467commands is placed into the numeric buffer
468.Sq 1
469if no other buffer is specified and if it meets one of the following conditions:
470.Bl -bullet -offset 6u
471.It
472It includes characters from more than one line.
473.It
474It is specified using a line-oriented motion.
475.It
476It is specified using one of the following motion commands:
477.Aq Cm control-A ,
478.Cm \` Ns Aq Ar character ,
479.Cm n ,
480.Cm N ,
481.Cm % ,
482.Cm / ,
483.Cm { ,
484.Cm } ,
485.Cm \&( ,
486.Cm \&) ,
487and
488.Cm \&? .
489.El
490.Pp
491Before this copy is done, the previous contents of buffer
492.Sq 1
493are moved into buffer
494.Sq 2 ,
495.Sq 2
496into buffer
497.Sq 3 ,
498and so on.
499The contents of buffer
500.Sq 9
501are discarded.
502Note that this rotation occurs
503.Em regardless
504of the user specifying another buffer.
505In
506.Nm vi ,
507text may be explicitly stored into the numeric buffers.
508In this case, the buffer rotation occurs before the replacement of the buffer's
509contents.
510The numeric buffers are only available in
511.Nm vi
512mode.
513.Sh VI COMMANDS
514The following section describes the commands available in the command
515mode of the
516.Nm vi
517editor.
518The following words have a special meaning in the commands description:
519.Pp
520.Bl -tag -width bigword -compact -offset 3u
521.It Ar bigword
522A set of non-whitespace characters.
523.It Ar buffer
524Temporary area where commands may place text.
525If not specified, the default buffer is used.
526See also
527.Sx BUFFERS ,
528above.
529.It Ar count
530A positive number used to specify the desired number of iterations
531of a command.
532It defaults to 1 if not specified.
533.It Ar motion
534A cursor movement command which indicates the other end of the affected region
535of text, the first being the current cursor position.
536Repeating the command character makes it affect the whole current line.
537.It Ar word
538A sequence of letters, digits or underscores.
539.El
540.Pp
541.Ar buffer
542and
543.Ar count ,
544if both present, may be specified in any order.
545.Ar motion
546and
547.Ar count ,
548if both present, are effectively multiplied together
549and considered part of the motion.
550.Pp
551.Bl -tag -width Ds -compact
552.It Xo
553.Aq Cm control-A
554.Xc
555Search forward
556for the word starting at the cursor position.
557.Pp
558.It Xo
559.Op Ar count
560.Aq Cm control-B
561.Xc
562Page backwards
563.Ar count
564screens.
565Two lines of overlap are maintained, if possible.
566.Pp
567.It Xo
568.Op Ar count
569.Aq Cm control-D
570.Xc
571Scroll forward
572.Ar count
573lines.
574If
575.Ar count
576is not given, scroll forward the number of lines specified by the last
577.Aq Cm control-D
578or
579.Aq Cm control-U
580command.
581If this is the first
582.Aq Cm control-D
583command, scroll half the number of lines in the current screen.
584.Pp
585.It Xo
586.Op Ar count
587.Aq Cm control-E
588.Xc
589Scroll forward
590.Ar count
591lines, leaving the current line and column as is, if possible.
592.Pp
593.It Xo
594.Op Ar count
595.Aq Cm control-F
596.Xc
597Page forward
598.Ar count
599screens.
600Two lines of overlap are maintained, if possible.
601.Pp
602.It Aq Cm control-G
603Display the following file information:
604the file name
605.Pq as given to Nm vi ;
606whether the file has been modified since it was last written;
607if the file is read-only;
608the current line number;
609the total number of lines in the file;
610and the current line number as a percentage of the total lines in the file.
611.Pp
612.It Xo
613.Op Ar count
614.Aq Cm control-H
615.Xc
616.It Xo
617.Op Ar count
618.Cm h
619.Xc
620Move the cursor back
621.Ar count
622characters in the current line.
623.Pp
624.It Xo
625.Op Ar count
626.Aq Cm control-J
627.Xc
628.It Xo
629.Op Ar count
630.Aq Cm control-N
631.Xc
632.It Xo
633.Op Ar count
634.Cm j
635.Xc
636Move the cursor down
637.Ar count
638lines without changing the current column.
639.Pp
640.It Aq Cm control-L
641.It Aq Cm control-R
642Repaint the screen.
643.Pp
644.It Xo
645.Op Ar count
646.Aq Cm control-M
647.Xc
648.It Xo
649.Op Ar count
650.Cm +
651.Xc
652Move the cursor down
653.Ar count
654lines to the first non-blank character of that line.
655.Pp
656.It Xo
657.Op Ar count
658.Aq Cm control-P
659.Xc
660.It Xo
661.Op Ar count
662.Cm k
663.Xc
664Move the cursor up
665.Ar count
666lines, without changing the current column.
667.Pp
668.It Aq Cm control-T
669Return to the most recent tag context.
670.Pp
671.It Xo
672.Op Ar count
673.Aq Cm control-U
674.Xc
675Scroll backwards
676.Ar count
677lines.
678If
679.Ar count
680is not given, scroll backwards the number of lines specified by the last
681.Aq Cm control-D
682or
683.Aq Cm control-U
684command.
685If this is the first
686.Aq Cm control-U
687command, scroll half the number of lines in the current screen.
688.Pp
689.It Aq Cm control-W
690Switch to the next lower screen in the window,
691or to the first screen if there are no lower screens in the window.
692.Pp
693.It Xo
694.Op Ar count
695.Aq Cm control-Y
696.Xc
697Scroll backwards
698.Ar count
699lines, leaving the current line and column as is, if possible.
700.Pp
701.It Aq Cm control-Z
702Suspend the current editor session.
703.Pp
704.It Aq Cm escape
705Execute the
706.Nm ex
707command being entered, or cancel it if it is only partial.
708.Pp
709.It Aq Cm control-]
710Push a tag reference onto the tag stack.
711.Pp
712.It Aq Cm control-\(ha
713Switch to the most recently edited file.
714.Pp
715.It Xo
716.Op Ar count
717.Aq Cm space
718.Xc
719.It Xo
720.Op Ar count
721.Cm l
722.Xc
723Move the cursor forward
724.Ar count
725characters without changing the current line.
726.Pp
727.It Xo
728.Op Ar count
729.Cm !\&
730.Ar motion shell-argument(s)
731.Aq Li carriage-return
732.Xc
733Replace the lines spanned by
734.Ar count
735and
736.Ar motion
737with the output
738.Pq standard output and standard error
739of the program named by the
740.Cm shell
741option, called with a
742.Fl c
743flag followed by the
744.Ar shell-argument(s)
745.Pq bundled into a single argument .
746Within
747.Ar shell-argument(s) ,
748the
749.Sq % ,
750.Sq #
751and
752.Sq !\&
753characters are expanded to the current file name,
754the previous current file name,
755and the command text of the previous
756.Cm !\&
757or
758.Cm :!
759commands, respectively.
760The special meaning of
761.Sq % ,
762.Sq #
763and
764.Sq !\&
765can be overridden by escaping them with a backslash.
766.Pp
767.It Xo
768.Op Ar count
769.Cm #
770.Sm off
771.Cm # | + | -
772.Sm on
773.Xc
774Increment
775.Pq trailing So # Sc or So + Sc
776or decrement
777.Pq trailing Sq -
778the number under the cursor by
779.Ar count ,
780starting at the cursor position or at the first non-blank
781character following it.
782Numbers with a leading
783.Sq 0x
784or
785.Sq 0X
786are interpreted as hexadecimal numbers.
787Numbers with a leading
788.Sq 0
789are interpreted as octal numbers unless they contain a non-octal digit.
790Other numbers may be prefixed with a
791.Sq +
792or
793.Sq -
794sign.
795.Pp
796.It Xo
797.Op Ar count
798.Cm $
799.Xc
800Move the cursor to the end of a line.
801If
802.Ar count
803is specified, additionally move the cursor down
804.Ar count
805\(mi 1 lines.
806.Pp
807.It Cm %
808Move to the
809.Cm matchchars
810character matching
811the one found at the cursor position or the closest to the right of it.
812.Pp
813.It Cm &
814Repeat the previous substitution command on the current line.
815.Pp
816.It Xo
817.Cm \(aq Ns Aq Ar character
818.Xc
819.It Xo
820.Cm \` Ns Aq Ar character
821.Xc
822Return to the cursor position marked by the character
823.Ar character ,
824or, if
825.Ar character
826is
827.Sq \(aq
828or
829.Sq \` ,
830to the position of the cursor before the last of the following commands:
831.Aq Cm control-A ,
832.Aq Cm control-T ,
833.Aq Cm control-] ,
834.Cm % ,
835.Cm \(aq ,
836.Cm \` ,
837.Cm (\& ,
838.Cm )\& ,
839.Cm / ,
840.Cm ?\& ,
841.Cm G ,
842.Cm H ,
843.Cm L ,
844.Cm [[ ,
845.Cm ]] ,
846.Cm { ,
847.Cm } .
848The first form returns to the first non-blank character of the line marked by
849.Ar character .
850The second form returns to the line and column marked by
851.Ar character .
852.Pp
853.It Xo
854.Op Ar count
855.Cm \&(
856.Xc
857.It Xo
858.Op Ar count
859.Cm \&)
860.Xc
861Move
862.Ar count
863sentences backward or forward, respectively.
864A sentence is an area of text that begins with the first nonblank character
865following the previous sentence, paragraph, or section
866boundary and continues until the next period, exclamation point,
867or question mark character, followed by any number of closing parentheses,
868brackets, double or single quote characters, followed by
869either an end-of-line or two whitespace characters.
870Groups of empty lines
871.Pq or lines containing only whitespace characters
872are treated as a single sentence.
873.Pp
874.It Xo
875.Op Ar count
876.Cm ,\&
877.Xc
878Reverse find character
879.Pq i.e., the last Cm F , f , T No or Cm t No command
880.Ar count
881times.
882.Pp
883.It Xo
884.Op Ar count
885.Cm -
886.Xc
887Move to the first non-blank character of the previous line,
888.Ar count
889times.
890.Pp
891.It Xo
892.Op Ar count
893.Cm .\&
894.Xc
895Repeat the last
896.Nm vi
897command that modified text.
898.Ar count
899replaces both the
900.Ar count
901argument of the repeated command and that of the associated
902.Ar motion .
903If the
904.Cm .\&
905command repeats the
906.Cm u
907command, the change log is rolled forward or backward, depending on the action
908of the
909.Cm u
910command.
911.Pp
912.It Xo
913.Pf / Ns Ar RE
914.Aq Li carriage-return
915.Xc
916.It Xo
917.Pf / Ns Ar RE Ns /
918.Op Ar offset
919.Op Cm z
920.Aq Li carriage-return
921.Xc
922.It Xo
923.Pf ?\& Ns Ar RE
924.Aq Li carriage-return
925.Xc
926.It Xo
927.Pf ?\& Ns Ar RE Ns ?\&
928.Op Ar offset
929.Op Cm z
930.Aq Li carriage-return
931.Xc
932.It Cm N
933.It Cm n
934Search forward
935.Pq Sq /
936or backward
937.Pq Sq ?\&
938for a regular expression.
939.Cm n
940and
941.Cm N
942repeat the last search in the same or opposite directions, respectively.
943If
944.Ar RE
945is empty, the last search regular expression is used.
946If
947.Ar offset
948is specified, the cursor is placed
949.Ar offset
950lines before or after the matched regular expression.
951If either
952.Cm n
953or
954.Cm N
955commands are used as motion components for the
956.Cm !\&
957command, there will be no prompt for the text of the command and the previous
958.Cm !\&
959will be executed.
960Multiple search patterns may be grouped together by delimiting them with
961semicolons and zero or more whitespace characters.
962These patterns are evaluated from left to right with the final cursor position
963determined by the last search pattern.
964A
965.Cm z
966command may be appended to the closed search expressions to reposition the
967result line.
968.Pp
969.It Cm 0
970Move to the first character in the current line.
971.Pp
972.It Cm :\&
973Execute an
974.Nm ex
975command.
976.Pp
977.It Xo
978.Op Ar count
979.Cm ;\&
980.Xc
981Repeat the last character find
982(i.e., the last
983.Cm F , f , T
984or
985.Cm t
986command)
987.Ar count
988times.
989.Pp
990.It Xo
991.Op Ar count
992.Cm <
993.Ar motion
994.Xc
995.It Xo
996.Op Ar count
997.Cm >
998.Ar motion
999.Xc
1000Shift
1001.Ar count
1002lines left or right, respectively, by an amount of
1003.Cm shiftwidth .
1004.Pp
1005.It Cm @ Ar buffer
1006Execute a named
1007.Ar buffer
1008as
1009.Nm vi
1010commands.
1011The buffer may include
1012.Nm ex
1013commands too, but they must be expressed as a
1014.Cm \&:
1015command.
1016If
1017.Ar buffer
1018is
1019.Sq @
1020or
1021.Sq * ,
1022then the last buffer executed shall be used.
1023.Pp
1024.It Xo
1025.Op Ar count
1026.Cm A
1027.Xc
1028Enter input mode, appending the text after the end of the line.
1029If a
1030.Ar count
1031argument is given, the characters input are repeated
1032.Ar count
1033\(mi 1 times after input mode is exited.
1034.Pp
1035.It Xo
1036.Op Ar count
1037.Cm B
1038.Xc
1039Move backwards
1040.Ar count
1041bigwords.
1042.Pp
1043.It Xo
1044.Op Ar buffer
1045.Cm C
1046.Xc
1047Change text from the current position to the end-of-line.
1048If
1049.Ar buffer
1050is specified,
1051.Dq yank
1052the deleted text into
1053.Ar buffer .
1054.Pp
1055.It Xo
1056.Op Ar buffer
1057.Cm D
1058.Xc
1059Delete text from the current position to the end-of-line.
1060If
1061.Ar buffer
1062is specified,
1063.Dq yank
1064the deleted text into
1065.Ar buffer .
1066.Pp
1067.It Xo
1068.Op Ar count
1069.Cm E
1070.Xc
1071Move forward
1072.Ar count
1073end-of-bigwords.
1074.Pp
1075.It Xo
1076.Op Ar count
1077.Cm F Aq Ar character
1078.Xc
1079Search
1080.Ar count
1081times backward through the current line for
1082.Aq Ar character .
1083.Pp
1084.It Xo
1085.Op Ar count
1086.Cm G
1087.Xc
1088Move to line
1089.Ar count ,
1090or the last line of the file if
1091.Ar count
1092is not specified.
1093.Pp
1094.It Xo
1095.Op Ar count
1096.Cm H
1097.Xc
1098Move to the screen line
1099.Ar count
1100\(mi 1 lines below the top of the screen.
1101.Pp
1102.It Xo
1103.Op Ar count
1104.Cm I
1105.Xc
1106Enter input mode, inserting the text at the beginning of the line.
1107If a
1108.Ar count
1109argument is given,
1110the characters input are repeated
1111.Ar count
1112\(mi 1 more times.
1113.Pp
1114.It Xo
1115.Op Ar count
1116.Cm J
1117.Xc
1118Join
1119.Ar count
1120lines with the current line.
1121The spacing between two joined lines is set to two whitespace characters if the
1122former ends with a question mark, a period or an exclamation point.
1123It is set to one whitespace character otherwise.
1124.Pp
1125.It Xo
1126.Op Ar count
1127.Cm L
1128.Xc
1129Move to the screen line
1130.Ar count
1131\(mi 1 lines above the bottom of the screen.
1132.Pp
1133.It Cm M
1134Move to the screen line in the middle of the screen.
1135.Pp
1136.It Xo
1137.Op Ar count
1138.Cm O
1139.Xc
1140Enter input mode, appending text in a new line above the current line.
1141If a
1142.Ar count
1143argument is given,
1144the characters input are repeated
1145.Ar count
1146\(mi 1 more times.
1147.Pp
1148.It Xo
1149.Op Ar buffer
1150.Cm P
1151.Xc
1152Insert text from
1153.Ar buffer
1154before the current column if
1155.Ar buffer
1156is character-oriented or before the current line if it is line-oriented.
1157.Pp
1158.It Cm Q
1159Exit
1160.Nm vi
1161.Pq or visual
1162mode and switch to
1163.Nm ex
1164mode.
1165.Pp
1166.It Xo
1167.Op Ar count
1168.Cm R
1169.Xc
1170Enter input mode, replacing the characters in the current line.
1171If a
1172.Ar count
1173argument is given,
1174the characters input are repeated
1175.Ar count
1176\(mi 1 more times upon exit from insert mode.
1177.Pp
1178.It Xo
1179.Op Ar buffer
1180.Op Ar count
1181.Cm S
1182.Xc
1183Substitute
1184.Ar count
1185lines.
1186If
1187.Ar buffer
1188is specified,
1189.Dq yank
1190the deleted text into
1191.Ar buffer .
1192.Pp
1193.It Xo
1194.Op Ar count
1195.Cm T
1196.Aq Ar character
1197.Xc
1198Search backwards,
1199.Ar count
1200times, through the current line for the character after the specified
1201.Aq Ar character .
1202.Pp
1203.It Cm U
1204Restore the current line to its state before the cursor last moved to it.
1205.Pp
1206.It Xo
1207.Op Ar count
1208.Cm W
1209.Xc
1210Move forward
1211.Ar count
1212bigwords.
1213.Pp
1214.It Xo
1215.Op Ar buffer
1216.Op Ar count
1217.Cm X
1218.Xc
1219Delete
1220.Ar count
1221characters before the cursor, on the current line.
1222If
1223.Ar buffer
1224is specified,
1225.Dq yank
1226the deleted text into
1227.Ar buffer .
1228.Pp
1229.It Xo
1230.Op Ar buffer
1231.Op Ar count
1232.Cm Y
1233.Xc
1234Copy
1235.Pq or Dq yank
1236.Ar count
1237lines into
1238.Ar buffer .
1239.Pp
1240.It Cm ZZ
1241Write the file and exit
1242.Nm vi
1243if there are no more files to edit.
1244Entering two
1245.Dq quit
1246commands in a row ignores any remaining file to edit.
1247.Pp
1248.It Xo
1249.Op Ar count
1250.Cm [[
1251.Xc
1252Back up
1253.Ar count
1254section boundaries.
1255.Pp
1256.It Xo
1257.Op Ar count
1258.Cm ]]
1259.Xc
1260Move forward
1261.Ar count
1262section boundaries.
1263.Pp
1264.It Cm \(ha
1265Move to the first non-blank character on the current line.
1266.Pp
1267.It Xo
1268.Op Ar count
1269.Cm _
1270.Xc
1271Move down
1272.Ar count
1273\(mi 1 lines, to the first non-blank character.
1274.Pp
1275.It Xo
1276.Op Ar count
1277.Cm a
1278.Xc
1279Enter input mode, appending the text after the cursor.
1280If a
1281.Ar count
1282argument is given,
1283the characters input are repeated
1284.Ar count
1285number of times.
1286.Pp
1287.It Xo
1288.Op Ar count
1289.Cm b
1290.Xc
1291Move backwards
1292.Ar count
1293words.
1294.Pp
1295.It Xo
1296.Op Ar buffer
1297.Op Ar count
1298.Cm c
1299.Ar motion
1300.Xc
1301Change the region of text described by
1302.Ar count
1303and
1304.Ar motion .
1305If
1306.Ar buffer
1307is specified,
1308.Dq yank
1309the changed text into
1310.Ar buffer .
1311.Pp
1312.It Xo
1313.Op Ar buffer
1314.Op Ar count
1315.Cm d
1316.Ar motion
1317.Xc
1318Delete the region of text described by
1319.Ar count
1320and
1321.Ar motion .
1322If
1323.Ar buffer
1324is specified,
1325.Dq yank
1326the deleted text into
1327.Ar buffer .
1328.Pp
1329.It Xo
1330.Op Ar count
1331.Cm e
1332.Xc
1333Move forward
1334.Ar count
1335end-of-words.
1336.Pp
1337.It Xo
1338.Op Ar count
1339.Cm f Aq Ar character
1340.Xc
1341Search forward,
1342.Ar count
1343times, through the rest of the current line for
1344.Aq Ar character .
1345.Pp
1346.It Xo
1347.Op Ar count
1348.Cm i
1349.Xc
1350Enter input mode, inserting the text before the cursor.
1351If a
1352.Ar count
1353argument is given,
1354the characters input are repeated
1355.Ar count
1356number of times.
1357.Pp
1358.It Xo
1359.Cm m
1360.Aq Ar character
1361.Xc
1362Save the current context
1363.Pq line and column
1364as
1365.Aq Ar character .
1366.Pp
1367.It Xo
1368.Op Ar count
1369.Cm o
1370.Xc
1371Enter input mode, appending text in a new line under the current line.
1372If a
1373.Ar count
1374argument is given,
1375the characters input are repeated
1376.Ar count
1377\(mi 1 more times.
1378.Pp
1379.It Xo
1380.Op Ar buffer
1381.Cm p
1382.Xc
1383Append text from
1384.Ar buffer .
1385Text is appended after the current column if
1386.Ar buffer
1387is character oriented, or after the current line otherwise.
1388.Pp
1389.It Xo
1390.Op Ar count
1391.Cm r
1392.Aq Ar character
1393.Xc
1394Replace
1395.Ar count
1396characters with
1397.Ar character .
1398.Pp
1399.It Xo
1400.Op Ar buffer
1401.Op Ar count
1402.Cm s
1403.Xc
1404Substitute
1405.Ar count
1406characters in the current line starting with the current character.
1407If
1408.Ar buffer
1409is specified,
1410.Dq yank
1411the substituted text into
1412.Ar buffer .
1413.Pp
1414.It Xo
1415.Op Ar count
1416.Cm t
1417.Aq Ar character
1418.Xc
1419Search forward,
1420.Ar count
1421times, through the current line for the character immediately before
1422.Aq Ar character .
1423.Pp
1424.It Cm u
1425Undo the last change made to the file.
1426If repeated, the
1427.Cm u
1428command alternates between these two states.
1429The
1430.Cm .\&
1431command, when used immediately after
1432.Cm u ,
1433causes the change log to be rolled forward or backward, depending on the action
1434of the
1435.Cm u
1436command.
1437.Pp
1438.It Xo
1439.Op Ar count
1440.Cm w
1441.Xc
1442Move forward
1443.Ar count
1444words.
1445.Pp
1446.It Xo
1447.Op Ar buffer
1448.Op Ar count
1449.Cm x
1450.Xc
1451Delete
1452.Ar count
1453characters at the current cursor position, but no more than there are till the
1454end of the line.
1455.Pp
1456.It Xo
1457.Op Ar buffer
1458.Op Ar count
1459.Cm y
1460.Ar motion
1461.Xc
1462Copy
1463.Pq or Dq yank
1464a text region specified by
1465.Ar count
1466and
1467.Ar motion
1468into a buffer.
1469.Pp
1470.It Xo
1471.Op Ar count1
1472.Cm z
1473.Op Ar count2
1474.Cm type
1475.Xc
1476Redraw, optionally repositioning and resizing the screen.
1477If
1478.Ar count2
1479is specified, limit the screen size to
1480.Ar count2
1481lines.
1482The following
1483.Cm type
1484characters may be used:
1485.Bl -tag -width Ds
1486.It Cm +
1487If
1488.Ar count1
1489is specified, place the line
1490.Ar count1
1491at the top of the screen.
1492Otherwise, display the screen after the current screen.
1493.It Aq Cm carriage-return
1494Place the line
1495.Ar count1
1496at the top of the screen.
1497.It Cm .\&
1498Place the line
1499.Ar count1
1500in the center of the screen.
1501.It Cm -
1502Place the line
1503.Ar count1
1504at the bottom of the screen.
1505.It Cm \(ha
1506If
1507.Ar count1
1508is given,
1509display the screen before the screen before
1510.Ar count1
1511.Pq i.e., 2 screens before .
1512Otherwise, display the screen before the current screen.
1513.El
1514.Pp
1515.It Xo
1516.Op Ar count
1517.Cm {\&
1518.Xc
1519Move backward
1520.Ar count
1521paragraphs.
1522.Pp
1523.It Xo
1524.Op Ar column
1525.Cm |\&
1526.Xc
1527Move to a specific
1528.Ar column
1529position on the current line.
1530If
1531.Ar column
1532is omitted,
1533move to the start of the current line.
1534.Pp
1535.It Xo
1536.Op Ar count
1537.Cm }\&
1538.Xc
1539Move forward
1540.Ar count
1541paragraphs.
1542.Pp
1543.It Xo
1544.Op Ar count
1545.Cm \(ti
1546.Ar motion
1547.Xc
1548If the
1549.Cm tildeop
1550option is not set, reverse the case of the next
1551.Ar count
1552character(s) and no
1553.Ar motion
1554can be specified.
1555Otherwise
1556.Ar motion
1557is mandatory and
1558.Cm \(ti
1559reverses the case of the characters in a text region specified by the
1560.Ar count
1561and
1562.Ar motion .
1563.Pp
1564.It Aq Cm interrupt
1565Interrupt the current operation.
1566The
1567.Aq interrupt
1568character is usually
1569.Aq control-C .
1570.El
1571.Sh VI TEXT INPUT COMMANDS
1572The following section describes the commands available in the text input mode
1573of the
1574.Nm vi
1575editor.
1576.Pp
1577.Bl -tag -width Ds -compact
1578.It Aq Cm nul
1579Replay the previous input.
1580.Pp
1581.It Aq Cm control-D
1582Erase to the previous
1583.Ar shiftwidth
1584column boundary.
1585.Pp
1586.It Cm \(ha Ns Aq Cm control-D
1587Erase all of the autoindent characters, and reset the autoindent level.
1588.Pp
1589.It Cm 0 Ns Aq Cm control-D
1590Erase all of the autoindent characters.
1591.Pp
1592.It Aq Cm control-T
1593Insert sufficient
1594.Aq tab
1595and
1596.Aq space
1597characters to move forward to the next
1598.Ar shiftwidth
1599column boundary.
1600If the
1601.Cm expandtab
1602option is set, only insert
1603.Aq space
1604characters.
1605.Pp
1606.It Aq Cm erase
1607.It Aq Cm control-H
1608Erase the last character.
1609.Pp
1610.It Aq Cm literal next
1611Escape the next character from any special meaning.
1612The
1613.Aq literal\ \&next
1614character is usually
1615.Aq control-V .
1616.Pp
1617.It Aq Cm escape
1618Resolve all text input into the file, and return to command mode.
1619.Pp
1620.It Aq Cm line erase
1621Erase the current line.
1622.Pp
1623.It Aq Cm control-W
1624.It Aq Cm word erase
1625Erase the last word.
1626The definition of word is dependent on the
1627.Cm altwerase
1628and
1629.Cm ttywerase
1630options.
1631.Pp
1632.Sm off
1633.It Xo
1634.Aq Cm control-X
1635.Bq Cm 0-9A-Fa-f
1636.Cm +
1637.Xc
1638.Sm on
1639Insert a character with the specified hexadecimal value into the text.
1640.Pp
1641.It Aq Cm interrupt
1642Interrupt text input mode, returning to command mode.
1643The
1644.Aq interrupt
1645character is usually
1646.Aq control-C .
1647.El
1648.Sh EX COMMANDS
1649The following section describes the commands available in the
1650.Nm ex
1651editor.
1652In each entry below, the tag line is a usage synopsis for the command.
1653.Pp
1654.Bl -tag -width Ds -compact
1655.It Aq Cm end-of-file
1656Scroll the screen.
1657.Pp
1658.It Cm !\& Ar argument(s)
1659.It Xo
1660.Op Ar range
1661.Cm !\&
1662.Ar argument(s)
1663.Xc
1664Execute a shell command, or filter lines through a shell command.
1665.Pp
1666.It Cm \&"
1667A comment.
1668.Pp
1669.It Xo
1670.Op Ar range
1671.Cm nu Ns Op Cm mber
1672.Op Ar count
1673.Op Ar flags
1674.Xc
1675.It Xo
1676.Op Ar range
1677.Cm #
1678.Op Ar count
1679.Op Ar flags
1680.Xc
1681Display the selected lines, each preceded with its line number.
1682.Pp
1683.It Cm @ Ar buffer
1684.It Cm * Ar buffer
1685Execute a buffer.
1686.Pp
1687.It Xo
1688.Op Ar range
1689.Cm < Ns Op Cm < ...
1690.Op Ar count
1691.Op Ar flags
1692.Xc
1693Shift lines left.
1694.Pp
1695.It Xo
1696.Op Ar line
1697.Cm =
1698.Op Ar flags
1699.Xc
1700Display the line number of
1701.Ar line .
1702If
1703.Ar line
1704is not specified, display the line number of the last line in the file.
1705.Pp
1706.It Xo
1707.Op Ar range
1708.Cm > Ns Op Cm > ...
1709.Op Ar count
1710.Op Ar flags
1711.Xc
1712Shift lines right.
1713.Pp
1714.It Xo
1715.Cm ab Ns Op Cm breviate
1716.Ar lhs rhs
1717.Xc
1718.Nm vi
1719only.
1720Add
1721.Ar lhs
1722as an abbreviation for
1723.Ar rhs
1724to the abbreviation list.
1725.Pp
1726.It Xo
1727.Op Ar line
1728.Cm a Ns Op Cm ppend Ns
1729.Op Cm !\&
1730.Xc
1731The input text is appended after the specified line.
1732.Pp
1733.It Cm ar Ns Op Cm gs
1734Display the argument list.
1735.Pp
1736.It Cm bg
1737.Nm vi
1738only.
1739Background the current screen.
1740.Pp
1741.It Xo
1742.Op Ar range
1743.Cm c Ns Op Cm hange Ns
1744.Op Cm !\&
1745.Op Ar count
1746.Xc
1747The input text replaces the specified range.
1748.Pp
1749.It Xo
1750.Cm chd Ns Op Cm ir Ns
1751.Op Cm !\&
1752.Op Ar directory
1753.Xc
1754.It Xo
1755.Cm cd Ns Op Cm !\&
1756.Op Ar directory
1757.Xc
1758Change the current working directory.
1759.Pp
1760.It Xo
1761.Op Ar range
1762.Cm co Ns Op Cm py
1763.Ar line
1764.Op Ar flags
1765.Xc
1766.It Xo
1767.Op Ar range
1768.Cm t
1769.Ar line
1770.Op Ar flags
1771.Xc
1772Copy the specified lines after the destination
1773.Ar line .
1774.Pp
1775.It Xo
1776.Cm cs Ns Op Cm cope
1777.Cm add | find | help | kill | reset
1778.Xc
1779Execute a Cscope command.
1780.Pp
1781.It Xo
1782.Op Ar range
1783.Cm d Ns Op Cm elete
1784.Op Ar buffer
1785.Op Ar count
1786.Op Ar flags
1787.Xc
1788Delete the lines from the file.
1789.Pp
1790.It Xo
1791.Cm di Ns Op Cm splay
1792.Cm b Ns Oo Cm uffers Oc |
1793.Cm c Ns Oo Cm onnections Oc |
1794.Cm s Ns Oo Cm creens Oc |
1795.Cm t Ns Op Cm ags
1796.Xc
1797Display buffers, Cscope connections, screens or tags.
1798.Pp
1799.It Xo
1800.Op Cm Ee Ns
1801.Op Cm dit Ns
1802.Op Cm !\&
1803.Op Ar +cmd
1804.Op Ar file
1805.Xc
1806.It Xo
1807.Op Cm Ee Ns
1808.Cm x Ns Op Cm !\&
1809.Op Ar +cmd
1810.Op Ar file
1811.Xc
1812Edit a different file. The capitalized command opens a new screen below the
1813current screen.
1814.Pp
1815.It Xo
1816.Cm exu Ns Op Cm sage
1817.Op Ar command
1818.Xc
1819Display usage for an
1820.Nm ex
1821command.
1822.Pp
1823.It Xo
1824.Cm f Ns Op Cm ile
1825.Op Ar file
1826.Xc
1827Display and optionally change the file name.
1828.Pp
1829.It Xo
1830.Op Cm Ff Ns
1831.Cm g
1832.Op Ar name
1833.Xc
1834.Nm vi
1835mode only.
1836Foreground the specified screen. The capitalized command opens a new screen
1837below the current screen.
1838.Pp
1839.It Xo
1840.Op Ar range
1841.Cm g Ns Op Cm lobal
1842.No / Ns Ar pattern Ns /
1843.Op Ar commands
1844.Xc
1845.It Xo
1846.Op Ar range
1847.Cm v
1848.No / Ns Ar pattern Ns /
1849.Op Ar commands
1850.Xc
1851Apply commands to lines matching
1852.Pq Sq global
1853or not matching
1854.Pq Sq v
1855a pattern.
1856.Pp
1857.It Cm he Ns Op Cm lp
1858Display a help message.
1859.Pp
1860.It Xo
1861.Op Ar line
1862.Cm i Ns Op Cm nsert Ns
1863.Op Cm !\&
1864.Xc
1865The input text is inserted before the specified line.
1866.Pp
1867.It Xo
1868.Op Ar range
1869.Cm j Ns Op Cm oin Ns
1870.Op Cm !\&
1871.Op Ar count
1872.Op Ar flags
1873.Xc
1874Join lines of text together.
1875.Pp
1876.It Xo
1877.Op Ar range
1878.Cm l Ns Op Cm ist
1879.Op Ar count
1880.Op Ar flags
1881.Xc
1882Display the lines unambiguously.
1883.Pp
1884.It Xo
1885.Cm map Ns Op Cm !\&
1886.Op Ar lhs rhs
1887.Xc
1888Define or display maps
1889.Pq for Nm vi No only .
1890.Pp
1891.It Xo
1892.Op Ar line
1893.Cm ma Ns Op Cm rk
1894.Aq Ar character
1895.Xc
1896.It Xo
1897.Op Ar line
1898.Cm k Aq Ar character
1899.Xc
1900Mark the line with the mark
1901.Aq Ar character .
1902.Pp
1903.It Xo
1904.Op Ar range
1905.Cm m Ns Op Cm ove
1906.Ar line
1907.Xc
1908Move the specified lines after the target line.
1909.Pp
1910.It Xo
1911.Cm mk Ns Op Cm exrc Ns
1912.Op Cm !\&
1913.Ar file
1914.Xc
1915Write the abbreviations, editor options and maps to the specified
1916.Ar file .
1917.Pp
1918.It Xo
1919.Op Cm Nn Ns
1920.Op Cm ext Ns
1921.Op Cm !\&
1922.Op Ar
1923.Xc
1924Edit the next file from the argument list. The capitalized command opens a
1925new screen below the current screen.
1926.\" .Pp
1927.\" .It Xo
1928.\" .Op Ar line
1929.\" .Cm o Ns Op Cm pen
1930.\" .No / Ns Ar pattern Ns /
1931.\" .Op Ar flags
1932.\" .Xc
1933.\" Enter open mode.
1934.Pp
1935.It Cm pre Ns Op Cm serve
1936Save the file in a form that can later be recovered using the
1937.Nm ex
1938.Fl r
1939option.
1940.Pp
1941.It Xo
1942.Op Cm \&Pp Ns
1943.Cm rev Ns Op Cm ious Ns
1944.Op Cm !\&
1945.Xc
1946Edit the previous file from the argument list. The capitalized command opens
1947a new screen below the current screen.
1948.Pp
1949.It Xo
1950.Op Ar range
1951.Cm p Ns Op Cm rint
1952.Op Ar count
1953.Op Ar flags
1954.Xc
1955Display the specified lines.
1956.Pp
1957.It Xo
1958.Op Ar line
1959.Cm pu Ns Op Cm t
1960.Op Ar buffer
1961.Xc
1962Append buffer contents to the current line.
1963.Pp
1964.It Xo
1965.Cm q Ns Op Cm uit Ns
1966.Op Cm !\&
1967.Xc
1968End the editing session.
1969.Pp
1970.It Xo
1971.Op Ar line
1972.Cm r Ns Op Cm ead Ns
1973.Op Cm !\&
1974.Op Ar file
1975.Xc
1976Read a file.
1977.Pp
1978.It Xo
1979.Cm rec Ns Op Cm over
1980.Ar file
1981.Xc
1982Recover
1983.Ar file
1984if it was previously saved.
1985.Pp
1986.It Xo
1987.Cm res Ns Op Cm ize
1988.Op Cm + Ns | Ns Cm - Ns
1989.Ar size
1990.Xc
1991.Nm vi
1992mode only.
1993Grow or shrink the current screen.
1994.Pp
1995.It Xo
1996.Cm rew Ns Op Cm ind Ns
1997.Op Cm !\&
1998.Xc
1999Rewind the argument list.
2000.Pp
2001.It Xo
2002.Cm se Ns Op Cm t
2003.Sm off
2004.Op option Oo = Oo value Oc Oc \ \&...
2005.Sm on
2006.Pf \ \& Op nooption ...
2007.Op option? ...
2008.Op Ar all
2009.Xc
2010Display or set editor options.
2011.Pp
2012.It Cm sh Ns Op Cm ell
2013Run a shell program.
2014.Pp
2015.It Xo
2016.Cm so Ns Op Cm urce
2017.Ar file
2018.Xc
2019Read and execute
2020.Nm ex
2021commands from a file.
2022.Pp
2023.It Xo
2024.Op Ar range
2025.Cm s Ns Op Cm ubstitute
2026.Sm off
2027.Op / Ar pattern No / Ar replace No /
2028.Sm on
2029.Pf \ \& Op Ar options
2030.Op Ar count
2031.Op Ar flags
2032.Xc
2033.It Xo
2034.Op Ar range
2035.Cm &
2036.Op Ar options
2037.Op Ar count
2038.Op Ar flags
2039.Xc
2040.It Xo
2041.Op Ar range
2042.Cm \(ti
2043.Op Ar options
2044.Op Ar count
2045.Op Ar flags
2046.Xc
2047Make substitutions.
2048The
2049.Ar replace
2050field may contain any of the following sequences:
2051.Bl -tag -width Ds
2052.It Sq \*(Am
2053The text matched by
2054.Ar pattern .
2055.It Sq \(ti
2056The replacement part of the previous
2057.Cm substitute
2058command.
2059.It Sq %
2060If this is the entire
2061.Ar replace
2062pattern, the replacement part of the previous
2063.Cm substitute
2064command.
2065.It Sq \e Ns Ar \(sh
2066Where
2067.Sq Ar \(sh
2068is an integer from 1 to 9, the text matched by the
2069.Ar # Ns 'th subexpression in
2070.Ar pattern .
2071.It Sq \eL
2072Causes the characters up to the end of the line of the next occurrence of
2073.Sq \eE
2074or
2075.Sq \ee
2076to be converted to lowercase.
2077.It Sq \el
2078Causes the next character to be converted to lowercase.
2079.It Sq \eU
2080Causes the characters up to the end of the line of the next occurrence of
2081.Sq \eE
2082or
2083.Sq \ee
2084to be converted to uppercase.
2085.It Sq \eu
2086Causes the next character to be converted to uppercase.
2087.El
2088.Pp
2089.It Xo
2090.Cm su Ns Op Cm spend Ns
2091.Op Cm !\&
2092.Xc
2093.It Xo
2094.Cm st Ns Op Cm op Ns
2095.Op Cm !\&
2096.Xc
2097.It Aq Cm suspend
2098Suspend the edit session.
2099The
2100.Aq suspend
2101character is usually
2102.Aq control-Z .
2103.Pp
2104.It Xo
2105.Op Cm Tt Ns
2106.Cm a Ns Op Cm g Ns
2107.Op Cm !\&
2108.Ar tagstring
2109.Xc
2110Edit the file containing the specified tag. The capitalized command opens a
2111new screen below the current screen.
2112.Pp
2113.It Xo
2114.Cm tagn Ns Op Cm ext Ns
2115.Op Cm !\&
2116.Xc
2117Edit the file containing the next context for the current tag.
2118.Pp
2119.It Xo
2120.Cm tagp Ns Op Cm op Ns
2121.Op Cm !\&
2122.Op Ar file | number
2123.Xc
2124Pop to the specified tag in the tags stack.
2125.Pp
2126.It Xo
2127.Cm tagpr Ns Op Cm ev Ns
2128.Op Cm !\&
2129.Xc
2130Edit the file containing the previous context for the current tag.
2131.Pp
2132.It Xo
2133.Cm tagt Ns Op Cm op Ns
2134.Op Cm !\&
2135.Xc
2136Pop to the least recent tag on the tags stack, clearing the stack.
2137.Pp
2138.It Xo
2139.Cm una Ns Op Cm bbreviate
2140.Ar lhs
2141.Xc
2142.Nm vi
2143only.
2144Delete an abbreviation.
2145.Pp
2146.It Cm u Ns Op Cm ndo
2147Undo the last change made to the file.
2148.Pp
2149.It Xo
2150.Cm unm Ns Op Cm ap Ns
2151.Op Cm !\&
2152.Ar lhs
2153.Xc
2154Unmap a mapped string.
2155.Pp
2156.It Cm ve Ns Op Cm rsion
2157Display the version of the
2158.Nm ex Ns / Ns Nm vi
2159editor.
2160.Pp
2161.It Xo
2162.Op Ar line
2163.Cm vi Ns Op Cm sual
2164.Op Ar type
2165.Op Ar count
2166.Op Ar flags
2167.Xc
2168.Nm ex
2169mode only.
2170Enter
2171.Nm vi .
2172.Pp
2173.It Xo
2174.Cm Vi Ns
2175.Op Cm sual Ns
2176.Op Cm !\&
2177.Op Ar +cmd
2178.Op Ar file
2179.Xc
2180.Nm vi
2181mode only. Edit a different file by opening a new screen below the current
2182screen.
2183.Pp
2184.It Xo
2185.Cm viu Ns Op Cm sage
2186.Op Ar command
2187.Xc
2188Display usage for a
2189.Nm vi
2190command.
2191.Pp
2192.It Xo
2193.Cm vs Ns Op Cm plit
2194.Op Ar +cmd
2195.Op Ar file
2196.Xc
2197Edit a different file by opening a new screen to the right of the current
2198screen.
2199.Pp
2200.It Xo
2201.Op Ar range
2202.Cm w Ns Op Cm rite Ns
2203.Op Cm !\&
2204.Op >>
2205.Op Ar file
2206.Xc
2207.It Xo
2208.Op Ar range
2209.Cm w Ns Op Cm rite
2210.Cm !\& Ns Ar shell-command
2211.Xc
2212.It Xo
2213.Op Ar range
2214.Cm wn Ns Op Cm !\&
2215.Op >>
2216.Op Ar file
2217.Xc
2218.It Xo
2219.Op Ar range
2220.Cm wq Ns Op Cm !\&
2221.Op >>
2222.Op Ar file
2223.Xc
2224Write the entire file, or
2225.Ar range .
2226.Sq !\&
2227overwrites a different, preexisting file.
2228.Sq >>
2229appends to a file that may preexist. Whitespace followed by
2230.Sq !\&
2231pipes the file to
2232.Ar shell-command .
2233.Cm wn
2234moves to the next file if writing succeeds.
2235.Cm wq
2236exits the editor if writing succeeds, unless there are more files to edit;
2237.Sq !\&
2238exits regardless.
2239.Pp
2240.It Xo
2241.Op Ar range
2242.Cm x Ns Op Cm it Ns
2243.Op Cm !\&
2244.Op Ar file
2245.Xc
2246Exit the editor,
2247writing the file if it has been modified.
2248.Pp
2249.It Xo
2250.Op Ar range
2251.Cm ya Ns Op Cm nk
2252.Op Ar buffer
2253.Op Ar count
2254.Xc
2255Copy the specified lines to a buffer.
2256.Pp
2257.It Xo
2258.Op Ar line
2259.Cm z
2260.Op Ar type
2261.Op Ar count
2262.Op Ar flags
2263.Xc
2264Adjust the window.
2265.El
2266.Sh SET OPTIONS
2267There are a large number of options that may be set
2268.Pq or unset
2269to change the editor's behavior.
2270This section describes the options, their abbreviations and their
2271default values.
2272.Pp
2273In each entry below, the first part of the tag line is the full name
2274of the option, followed by any equivalent abbreviations.
2275The part in square brackets is the default value of the option.
2276Most of the options are boolean, i.e., they are either on or off,
2277and do not have an associated value.
2278.Pp
2279Options apply to both
2280.Nm ex
2281and
2282.Nm vi
2283modes, unless otherwise specified.
2284.Bl -tag -width Ds
2285.It Cm altwerase Bq off
2286.Nm vi
2287only.
2288Select an alternate word erase algorithm.
2289.It Cm autoindent , ai Bq off
2290Automatically indent new lines.
2291.It Cm autoprint , ap Bq on
2292.Nm ex
2293only.
2294Display the current line automatically.
2295.It Cm autowrite , aw Bq off
2296Write modified files automatically when changing files or suspending the editor
2297session.
2298.It Cm backup Bq \&"\&"
2299Back up files before they are overwritten.
2300.It Cm beautify , bf Bq off
2301Discard control characters.
2302.It Cm cdpath Bo environment variable Ev CDPATH , or current directory Bc
2303The directory paths used as path prefixes for the
2304.Cm cd
2305command.
2306.It Cm cedit Bq no default
2307Set the character to edit the colon command-line history.
2308.It Cm columns , co Bq 80
2309Set the number of columns in the screen.
2310.It Cm comment Bq off
2311.Nm vi
2312only.
2313Skip leading comments in shell, C and C++ language files.
2314.It Cm directory , dir Bo environment variable Ev TMPDIR , or Pa /tmp Bc
2315The directory where temporary files are created.
2316.It Cm edcompatible , ed Bq off
2317Remember the values of the
2318.Sq c
2319and
2320.Sq g
2321suffixes to the
2322.Cm substitute
2323commands, instead of initializing them as unset for each new command.
2324.It Cm errorbells , eb Bq off
2325.Nm ex
2326only.
2327Announce error messages with a bell.
2328.It Cm escapetime Bq 1
2329The tenths of a second
2330.Nm ex Ns / Ns Nm vi
2331waits for a subsequent key to complete an
2332.Aq escape
2333key mapping.
2334.It Cm expandtab , et Bq off
2335Expand
2336.Aq tab
2337characters to
2338.Aq space
2339when inserting, replacing or shifting text, autoindenting,
2340indenting with
2341.Aq Ic control-T ,
2342outdenting with
2343.Aq Ic control-D ,
2344or
2345when filtering lines with the
2346.Cm !\&
2347command.
2348.It Cm exrc , ex Bq off
2349Read the startup files in the local directory.
2350.It Cm extended Bq off
2351Use extended regular expressions
2352.Pq EREs
2353rather than basic regular expressions
2354.Pq BREs .
2355See
2356.Xr re_format 7
2357for more information on regular expressions.
2358.It Cm filec Bq Aq tab
2359Set the character to perform file path completion on the colon command line.
2360.It Cm fileencoding , fe Bq auto detect
2361Set the encoding of the current file.
2362.It Cm flash Bq on
2363Flash the screen instead of beeping the keyboard on error.
2364.It Cm hardtabs, ht Bq 0
2365Set the spacing between hardware tab settings.
2366This option currently has no effect.
2367.It Cm iclower Bq off
2368Makes all regular expressions case-insensitive,
2369as long as an upper-case letter does not appear in the search string.
2370.It Cm ignorecase , ic Bq off
2371Ignore case differences in regular expressions.
2372.It Cm inputencoding , ie Bq locale
2373Set the encoding of your input characters.
2374.It Cm keytime Bq 6
2375The tenths of a second
2376.Nm ex Ns / Ns Nm vi
2377waits for a subsequent key to complete a key mapping.
2378.It Cm leftright Bq off
2379.Nm vi
2380only.
2381Do left-right scrolling.
2382.It Cm lines , li Bq 24
2383.Nm vi
2384only.
2385Set the number of lines in the screen.
2386.It Cm lisp Bq off
2387.Nm vi
2388only.
2389Modify various search commands and options to work with Lisp.
2390This option is not yet implemented.
2391.It Cm list Bq off
2392Display lines in an unambiguous fashion.
2393.It Cm lock Bq on
2394Attempt to get an exclusive lock on any file being edited, read or written.
2395.It Cm magic Bq on
2396When turned off, all regular expression characters except for
2397.Sq \(ha
2398and
2399.Sq \(Do
2400are treated as ordinary characters.
2401Preceding individual characters by
2402.Sq \e
2403re-enables them.
2404.It Cm matchchars Bq []{}()
2405Character pairs looked for by the
2406.Cm %
2407command.
2408.It Cm matchtime Bq 7
2409.Nm vi
2410only.
2411The tenths of a second
2412.Nm ex Ns / Ns Nm vi
2413pauses on the matching character when the
2414.Cm showmatch
2415option is set.
2416.It Cm mesg Bq on
2417Permit messages from other users.
2418.It Cm msgcat Bq /usr/share/vi/catalog/
2419Selects a message catalog to be used to display error and informational
2420messages in a specified language.
2421.It Cm modelines , modeline Bq off
2422Read the first and last few lines of each file for
2423.Nm ex
2424commands.
2425This option will never be implemented.
2426.It Cm noprint Bq \&"\&"
2427Characters that are never handled as printable characters.
2428.It Cm number , nu Bq off
2429Precede each line displayed with its current line number.
2430.It Cm octal Bq off
2431Display unknown characters as octal numbers, instead of the default
2432hexadecimal.
2433.It Cm open Bq on
2434.Nm ex
2435only.
2436If this option is not set, the
2437.Cm open
2438and
2439.Cm visual
2440commands are disallowed.
2441.It Cm optimize , opt Bq on
2442.Nm vi
2443only.
2444Optimize text throughput to dumb terminals.
2445This option is not yet implemented.
2446.It Cm paragraphs , para Bq "IPLPPPQPP LIpplpipbp"
2447.Nm vi
2448only.
2449Define additional paragraph boundaries for the
2450.Cm {\&
2451and
2452.Cm }\&
2453commands.
2454.It Cm path Bq \&"\&"
2455Define additional directories to search for files being edited.
2456.It Cm print Bq \&"\&"
2457Characters that are always handled as printable characters.
2458.It Cm prompt Bq on
2459.Nm ex
2460only.
2461Display a command prompt.
2462.It Cm readonly , ro Bq off
2463Mark the file and session as read-only.
2464.It Cm recdir Bq /var/tmp/vi.recover
2465The directory where recovery files are stored.
2466.It Cm redraw , re Bq off
2467.Nm vi
2468only.
2469Simulate an intelligent terminal on a dumb one.
2470This option is not yet implemented.
2471.It Cm remap Bq on
2472Remap keys until resolved.
2473.It Cm report Bq 5
2474Set the number of lines about which the editor reports changes or yanks.
2475.It Cm ruler Bq off
2476.Nm vi
2477only.
2478Display a row/column ruler on the colon command line.
2479.It Cm scroll , scr Bq "window size / 2"
2480Set the number of lines scrolled.
2481.It Cm searchincr Bq off
2482Makes the
2483.Cm /
2484and
2485.Cm ?\&
2486commands incremental.
2487.It Cm sections , sect Bq "NHSHH HUnhsh"
2488.Nm vi
2489only.
2490Define additional section boundaries for the
2491.Cm [[
2492and
2493.Cm ]]
2494commands.
2495.It Cm secure Bq off
2496Turns off all access to external programs.
2497.It Cm shell , sh Bo environment variable Ev SHELL , or Pa /bin/sh Bc
2498Select the shell used by the editor.
2499.It Cm shellmeta Bq \(ti{[*?$\`\(aq\&"\e
2500Set the meta characters checked to determine if file name expansion
2501is necessary.
2502.It Cm shiftwidth , sw Bq 8
2503Set the autoindent and shift command indentation width.
2504.It Cm showmatch , sm Bq off
2505.Nm vi
2506only.
2507Note the left matching characters when the right ones are inserted.
2508.It Cm showmode , smd Bq off
2509.Nm vi
2510only.
2511Display the current editor mode and a
2512.Dq modified
2513flag.
2514.It Cm sidescroll Bq 16
2515.Nm vi
2516only.
2517Set the amount a left-right scroll will shift.
2518.It Cm slowopen , slow Bq off
2519Delay display updating during text input.
2520This option is not yet implemented.
2521.It Cm sourceany Bq off
2522Read startup files not owned by the current user.
2523This option will never be implemented.
2524.It Cm tabstop , ts Bq 8
2525This option sets tab widths for the editor display.
2526.It Cm taglength , tl Bq 0
2527Set the number of significant characters in tag names.
2528.It Cm tags , tag Bq tags
2529Set the list of tags files.
2530.It Xo
2531.Cm term , ttytype , tty
2532.Bq environment variable Ev TERM
2533.Xc
2534Set the terminal type.
2535.It Cm terse Bq off
2536This option has historically made editor messages less verbose.
2537It has no effect in this implementation.
2538.It Cm tildeop Bq off
2539Modify the
2540.Cm \(ti
2541command to take an associated motion.
2542.It Cm timeout , to Bq on
2543Time out on keys which may be mapped.
2544.It Cm ttywerase Bq off
2545.Nm vi
2546only.
2547Select an alternate erase algorithm.
2548.It Cm verbose Bq off
2549.Nm vi
2550only.
2551Display an error message for every error.
2552.It Cm w300 Bq no default
2553.Nm vi
2554only.
2555Set the window size if the baud rate is less than 1200 baud.
2556.It Cm w1200 Bq no default
2557.Nm vi
2558only.
2559Set the window size if the baud rate is equal to 1200 baud.
2560.It Cm w9600 Bq no default
2561.Nm vi
2562only.
2563Set the window size if the baud rate is greater than 1200 baud.
2564.It Cm warn Bq on
2565.Nm ex
2566only.
2567This option causes a warning message to be printed on the terminal
2568if the file has been modified since it was last written, before a
2569.Cm !\&
2570command.
2571.It Xo
2572.Cm window , w , wi
2573.Bq environment variable Ev LINES No \(mi 1
2574.Xc
2575Set the window size for the screen.
2576.It Cm windowname Bq off
2577Change the icon/window name to the current file name.
2578.It Cm wraplen , wl Bq 0
2579.Nm vi
2580only.
2581Break lines automatically,
2582the specified number of columns from the left-hand margin.
2583If both the
2584.Cm wraplen
2585and
2586.Cm wrapmargin
2587edit options are set, the
2588.Cm wrapmargin
2589value is used.
2590.It Cm wrapmargin , wm Bq 0
2591.Nm vi
2592only.
2593Break lines automatically,
2594the specified number of columns from the right-hand margin.
2595If both the
2596.Cm wraplen
2597and
2598.Cm wrapmargin
2599edit options are set, the
2600.Cm wrapmargin
2601value is used.
2602.It Cm wrapscan , ws Bq on
2603Set searches to wrap around the end or beginning of the file.
2604.It Cm writeany , wa Bq off
2605Turn off file-overwriting checks.
2606.El
2607.Sh ENVIRONMENT
2608.Bl -tag -width "COLUMNS"
2609.It Ev COLUMNS
2610The number of columns on the screen.
2611This value overrides any system or terminal specific values.
2612If the
2613.Ev COLUMNS
2614environment variable is not set when
2615.Nm ex Ns / Ns Nm vi
2616runs, or the
2617.Cm columns
2618option is explicitly reset by the user,
2619.Nm ex Ns / Ns Nm vi
2620enters the value into the environment.
2621.It Ev EXINIT
2622A list of
2623.Nm ex
2624startup commands, read after
2625.Pa /etc/vi.exrc
2626unless the variable
2627.Ev NEXINIT
2628is also set.
2629.It Ev HOME
2630The user's home directory, used as the initial directory path for the startup
2631.Pa $HOME/.nexrc
2632and
2633.Pa $HOME/.exrc
2634files.
2635This value is also used as the default directory for the
2636.Cm cd
2637command.
2638.It Ev LINES
2639The number of rows on the screen.
2640This value overrides any system or terminal specific values.
2641If the
2642.Ev LINES
2643environment variable is not set when
2644.Nm ex Ns / Ns Nm vi
2645runs, or the
2646.Cm lines
2647option is explicitly reset by the user,
2648.Nm ex Ns / Ns Nm vi
2649enters the value into the environment.
2650.It Ev NEXINIT
2651A list of
2652.Nm ex
2653startup commands, read after
2654.Pa /etc/vi.exrc .
2655.It Ev SHELL
2656The user's shell of choice
2657.Pq see also the Cm shell No option .
2658.It Ev TERM
2659The user's terminal type.
2660The default is the type
2661.Dq unknown .
2662If the
2663.Ev TERM
2664environment variable is not set when
2665.Nm ex Ns / Ns Nm vi
2666runs, or the
2667.Cm term
2668option is explicitly reset by the user,
2669.Nm ex Ns / Ns Nm vi
2670enters the value into the environment.
2671.It Ev TMPDIR
2672The location used to store temporary files
2673.Pq see also the Cm directory No edit option .
2674.El
2675.Sh ASYNCHRONOUS EVENTS
2676.Bl -tag -width "SIGWINCH" -compact
2677.It Dv SIGALRM
2678.Nm vi Ns / Ns Nm ex
2679uses this signal for periodic backups of file modifications and to display
2680.Dq busy
2681messages when operations are likely to take a long time.
2682.Pp
2683.It Dv SIGHUP
2684.It Dv SIGTERM
2685If the current buffer has changed since it was last written in its entirety,
2686the editor attempts to save the modified file so it can be later recovered.
2687See the
2688.Nm vi Ns / Ns Nm ex
2689reference manual section
2690.Sx Recovery
2691for more information.
2692.Pp
2693.It Dv SIGINT
2694When an interrupt occurs, the current operation is halted
2695and the editor returns to the command level.
2696If interrupted during text input,
2697the text already input is resolved into the file as if the text
2698input had been normally terminated.
2699.Pp
2700.It Dv SIGWINCH
2701The screen is resized.
2702See the
2703.Nm vi Ns / Ns Nm ex
2704reference manual section
2705.Sx Sizing the Screen
2706for more information.
2707.\" .Pp
2708.\" .It Dv SIGCONT
2709.\" .It Dv SIGTSTP
2710.\" .Nm vi Ns / Ns Nm ex
2711.\" ignores these signals.
2712.El
2713.Sh FILES
2714.Bl -tag -width "/var/tmp/vi.recover"
2715.It Pa /bin/sh
2716The default user shell.
2717.It Pa /etc/vi.exrc
2718System-wide
2719.Nm vi
2720startup file.
2721It is read for
2722.Nm ex
2723commands first in the startup sequence.
2724Must be owned by root or the user,
2725and writable only by the owner.
2726.It Pa /tmp
2727Temporary file directory.
2728.It Pa /var/tmp/vi.recover
2729The default recovery file directory.
2730.It Pa $HOME/.nexrc
2731First choice for user's home directory startup file, read for
2732.Nm ex
2733commands right after
2734.Pa /etc/vi.exrc
2735unless either
2736.Ev NEXINIT
2737or
2738.Ev EXINIT
2739are set.
2740Must be owned by root or the user,
2741and writable only by the owner.
2742.It Pa $HOME/.exrc
2743Second choice for user's home directory startup file, read for
2744.Nm ex
2745commands under the same conditions as
2746.Pa $HOME/.nexrc .
2747.It Pa .nexrc
2748First choice for local directory startup file, read for
2749.Nm ex
2750commands at the end of the startup sequence if the
2751.Cm exrc
2752option was turned on earlier.
2753Must be owned by the user
2754and writable only by the owner.
2755.It Pa .exrc
2756Second choice for local directory startup file, read for
2757.Nm ex
2758commands under the same conditions as
2759.Pa .nexrc .
2760.El
2761.Sh EXIT STATUS
2762The
2763.Nm ex
2764and
2765.Nm vi
2766utilities exit 0 on success,
2767and \*(Gt0 if an error occurs.
2768.Sh SEE ALSO
2769.Xr ctags 1 ,
2770.Xr iconv 1 ,
2771.Xr re_format 7
2772.Rs
2773.%T vi/ex reference manual
2774.%U https://docs.freebsd.org/44doc/usd/13.viref/paper.pdf
2775.Re
2776.Sh STANDARDS
2777.Nm nex Ns / Ns Nm nvi
2778is close to
2779.St -p1003.1-2008 .
2780That document differs from historical
2781.Nm ex Ns / Ns Nm vi
2782practice in several places; there are changes to be made on both sides.
2783.Sh HISTORY
2784The
2785.Nm ex
2786editor first appeared in
2787.Bx 1 .
2788The
2789.Nm nex Ns / Ns Nm nvi
2790replacements for the
2791.Nm ex Ns / Ns Nm vi
2792editor first appeared in
2793.Bx 4.4 .
2794.Sh AUTHORS
2795.An Bill Joy
2796wrote the original version of
2797.Nm ex
2798in 1977.
2799