Vi/Ex Reference Manual
Keith Bostic
Computer Science Division
Department of Electrical Engineering and Computer Science
University of California, Berkeley
Berkeley, California 94720
March 14, 1997
Abstract
This document is the reference guide for the 4.4BSD implementations of nex/nvi, which are implementations of the historic Berkeley ex/vi editors.
Licensing
Copyright (c) 1991, 1992, 1993, 1994
The Regents of the University of California. All Rights Reserved.
Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996
Keith Bostic. All Rights Reserved.
The vi program is freely redistributable. You are welcome to copy,
modify and share it with others under the conditions listed in the
LICENSE file. If any company (not individual!) finds vi sufficiently
useful that you would have purchased it, or if any company wishes to
redistribute it, contributions to the authors would be appreciated.
Acknowledgements
Bruce Englar encouraged the early development of the historic ex/vi editor. Peter Kessler helped bring sanity to version 2's command layout. Bill Joy wrote versions 1 and 2.0 through 2.7, and created the framework that users see in the present editor. Mark Horton added macros and other features and made ex/vi work on a large number of terminals and Unix systems.
Nvi is originally derived from software contributed to the University of California, Berkeley by Steve Kirkendall, the author of the vi clone elvis.
IEEE Standard Portable Operating System Interface for Computer Environments (POSIX) 1003.2 style Regular Expression support was done by Henry Spencer.
The curses library was originally done by Ken Arnold. Scrolling and reworking for nvi was done by Elan Amir.
George Neville-Neil added the Tcl interpreter, and Sven Verdoolaege added the Perl interpreter.
Rob Mayoff added Cscope support.
The Institute of Electrical and Electronics Engineers has given us permission to reprint portions of their documentation. Portions of this document are reprinted and reproduced from IEEE Std 1003.2-1992, IEEE Standard Portable Operating System Interface for Computer Environments (POSIX), copyright 1992 by the Institute of Electrical and Electronics Engineers, Inc.
The financial support of UUNET Communications Services is gratefully acknowledged.
Vi is a screen oriented text editor. Ex is a line-oriented text editor. Ex and vi are different interfaces to the same program, and it is possible to switch back and forth during an edit session. View is the equivalent of using the -R (read-only) option of vi.
This reference manual is the one provided with the nex/nvi versions of the ex/vi text editors. Nex/nvi are intended as bug-for-bug compatible replacements for the original Fourth Berkeley Software Distribution (4BSD) ex/vi programs. This reference manual is accompanied by a traditional-style manual page. That manual page describes the functionality found in ex/vi in far less detail than the description here. In addition, it describes the system interface to ex/vi, e.g. command line options, session recovery, signals, environmental variables, and similar things.
This reference is intended for users already familiar with ex/vi. Anyone else should almost certainly read a good tutorial on the editor first. If you are in an unfamiliar environment, and you absolutely have to get work done immediately, see the section entitled ``Fast Startup'' in the manual page. It is probably enough to get you started.
There are a few features in nex/nvi that are not found in historic versions of ex/vi. Some of the more interesting of those features are briefly described in the next section, entitled ``Additional Features''. For the rest of this document, nex/nvi is used only when it is necessary to distinguish it from the historic implementations of ex/vi.
Future versions of this software will be periodically made available by anonymous ftp, and can be retrieved from ftp.cs.berkeley.edu, in the directory ucb/4bsd.
There are a few features in nex/nvi that are not found in historic versions of ex/vi. Some of the more interesting of these are as follows:
Ex/vi interprets one of two possible environmental variables and reads up to three of five possible files during startup. The variables and files are expected to contain ex commands, not vi commands. In addition, they are interpreted before the file to be edited is read, and therefore many ex commands may not be used. Generally, any command that requires output to the screen or that needs a file upon which to operate, will cause an error if included in a startup file or environmental variable.
Because the ex command set supported by nex/nvi is a superset of the command set supported by historical implementations of ex, nex/nvi can use the startup files created for the historical implementations, but the converse may not be true.
If the -s (the historic - option) is specified, or if standard input is redirected from a file, all environmental variables and startup files are ignored.
Otherwise, startup files and environmental variables are handled in the following order:
When the $HOME directory is being used for both nex/nvi and an historic implementation of ex/vi, a possible solution is to put nex/nvi specific commands in the .nexrc file, along with a :source $HOME/.exrc command to read in the commands common to both implementations.
No startup file is read if it is writable by anyone other than its owner.
It is not an error for any of the startup environmental variables or files not to exist.
Once all environmental variables are interpreted, and all startup files are read, the first file to be edited is read in (or a temporary file is created). Then, any commands specified using the -c option are executed, in the context of that file.
There is no recovery program for nex/nvi, nor does nex/nvi run setuid. Recovery files are created readable and writable by the owner only. Users may recover any file which they can read, and the superuser may recover any edit session.
Edit sessions are backed by files in the directory named by the recdir option (the directory /var/tmp/vi.recover by default), and are named ``vi.XXXXXX'', where ``XXXXXX'' is a number related to the process ID. When a file is first modified, a second recovery file containing an email message for the user is created, and is named ``recover.XXXXXX'', where, again, ``XXXXXX'' is associated with the process ID. Both files are removed at the end of a normal edit session, but will remain if the edit session is abnormally terminated or the user runs the ex preserve command.
The recdir option may be set in either the user's or system's startup information, changing the recovery directory. (Note, however, that if a memory based file system is used as the backup directory, each system reboot will delete all of the recovery files! The same caution applies to directories such as /tmp which are cleared of their contents by a system reboot, or /usr/tmp which is periodically cleared of old files on many systems.)
The recovery directory should be owned by root, or at least by a pseudo-user. In addition, if directory ``sticky-bit'' semantics are available, the directory should have the sticky-bit set so that files may only be removed by their owners. The recovery directory must be read, write, and executable by any user, i.e. mode 1777.
If the recovery directory does not exist, ex/vi will attempt to create it. This can result in the recovery directory being owned by a normal user, which means that that user will be able to remove other user's recovery and backup files. This is annoying, but is not a security issue as the user cannot otherwise access or modify the files.
The recovery file has all of the necessary information in it to enable the user to recover the edit session. In addition, it has all of the necessary email headers for sendmail(8). When the system is rebooted, all of the files in /var/tmp/vi.recover named ``recover.XXXXXX'' should be sent to their owners, by email, using the -t option of sendmail (or a similar mechanism in other mailers). If ex/vi receives a hangup (SIGHUP) signal, or the user executes the ex preserve command, ex/vi will automatically email the recovery information to the user.
If your system does not have the sendmail utility (or a mailer program which supports its interface) the source file nvi/common/recover.c will have to be modified to use your local mail delivery programs. Note, if nex/nvi is changed to use another mailer, it is important to remember that the owner of the file given to the mailer is the nex/nvi user, so nothing in the file should be trusted as it may have been modified in an effort to compromise the system.
Finally, the owner execute bit is set on backup files when they are created, and unset when they are first modified, e.g. backup files that have no associated email recovery file will have this bit set. (There is also a small window where empty files can be created and not yet have this bit set. This is due to the method in which the files are created.) Such files should be deleted when the system reboots.
A simple way to do this cleanup is to run the Bourne shell script recover, from your /etc/rc.local (or other system startup) file. The script should work with the historic Bourne shell, a POSIX 1003.2 shell or the Korn shell. The recover script is installed as part of the nex/nvi installation process.
Consult the manual page for details on recovering preserved or aborted editing sessions.
The size of the screen can be set in a number of ways. Ex/vi takes the following steps until values are obtained for both the number of rows and number of columns in the screen.
If a window change size signal (SIGWINCH) is received, the new window size is retrieved using the TIOCGWINSZ ioctl(2) call, and all other information is ignored.
In both ex and vi printable characters as defined by isprint(3) are displayed using the local character set.
Non-printable characters, for which iscntrl(3) returns true, and which are less than octal \040, are displayed as the string ``^<character>'', where <character> is the character that is the original character's value offset from the ``@'' character. For example, the octal character \001 is displayed as ``^A''. If iscntrl(3) returns true for the octal character \177, it is displayed as the string ``^?''. All other characters are displayed as either hexadecimal values, in the form ``0x<high-halfbyte> ... 0x<low-halfbyte>'', or as octal values, in the form ``\<high-one-or-two-bits> ... \<low-three-bits>''. The display of unknown characters is based on the value of the octal option.
In vi command mode, the cursor is always positioned on the last column of characters which take up more than one column on the screen. In vi text input mode, the cursor is positioned on the first column of characters which take up more than one column on the screen.
Nvi supports multiple screens by dividing the window into regions. It also supports stacks of screens by permitting the user to change the set of screens that are currently displayed.
The Edit, Ex, Fg, Next, Previous, Tag and Visual (in vi mode) commands divide the current screen into two regions of approximately equal size and then perform their usual action in a new screen area. If the cursor is in the lower half of the screen, the screen will split up, i.e. the new screen will be above the old one. If the cursor is in the upper half of the screen, the new screen will be below the old one.
When more than one screen is editing a file, changes in any screen are reflected in all other screens editing the same file. Exiting a screen without saving any changes (or explicitly discarding them) is permitted until the last screen editing the file is exited, at which time the changes must be saved or discarded.
The resize command permits resizing of individual screens. Screens may be grown, shrunk or set to an absolute number of rows.
The ^W command is used to switch between screens. Each ^W moves to the next lower screen in the window, or to the first screen in the window if there are no lower screens.
The bg command ``backgrounds'' the current screen. The screen disappears from the window, and the rows it occupied are taken over by a neighboring screen. It is an error to attempt to background the only screen in the window.
The display screens command displays the names of the files associated with the current backgrounded screens in the window.
The fg [file] command moves the specified screen from the list of backgrounded screens to the foreground. If no file argument is specified, the first screen on the list is foregrounded. By default, foregrounding consists of backgrounding the current screen, and replacing its space in the window with the foregrounded screen.
Capitalizing the first letter of the command, i.e. Fg, will foreground the backgrounded screen in a new screen instead of swapping it with the current screen.
If the last foregrounded screen in the window is exited, and there are backgrounded screens, the first screen on the list of backgrounded screens takes over the window.
Nvi supports the historic vi tag command <control-]>, and the historic ex tag command tag. These commands change the current file context to a new location, based on information found in the tags files. If you are unfamiliar with these commands, you should review their description in the ex and vi commands section of this manual. For additional information on tags files, see the discussion of the tags edit option and the system ctags(1) manual page.
In addition, nvi supports the notion of ``tags stacks'', using the <control-T> command. The <control-T> command returns the user to the previous context, i.e., the last place from which a <control-]> or tag command was entered. These three commands provide the basic functionality which allows you to use vi to review source code in a structured manner.
Nvi also provides two other basic ex commands for tag support: tagpop and tagtop. The tagpop command is identical to the <control-T> command, with the additional functionality that you may specify that modifications to the current file are to be discarded. This cannot be done using the <control-T> command. The tagtop command discards all of the contexts that have been pushed onto the tag stack, returning to the context from which the first <control-]> or tag command was entered.
The historic ctags(1) tags file format supports only a single location per tag, normally the function declaration or structure or string definition. More sophisticated source code tools often provide multiple locations per tag, e.g., a list of the places from which a function is called or a string definition is used. An example of this functionality is the System V source code tool, cscope.
Cscope creates a database of information on source code files, and supports a query language for that information as described in the cscope(1) manual page. Nvi contains an interface to the cscope query language which permits you to query cscope and then sequentially step through the locations in the sources files which cscope returns. There are two nvi commands which support this ability to step through multiple locations. They are the ex commands tagnext and tagprev. The tagnext command moves to the next location for the current tag. The tagprev command moves to the previous location for the current tag. (See the tagnext and tagprev command discussion in the ex commands section of this manual for more information.) At any time during this sequential walk, you may use the <control-]>, tag or cscope commands to move to a new tag context, and then use the <control-T> or tagpop commands to return and continue stepping through the locations for this tag. This is similar to the previous model of a simple tag stack, except that each entry in the tag stack may have more than one file context that is of interest.
Although there is no widely distributed version of ctags(1) that creates tags files with multiple locations per tag, nvi has been written to understand the obvious extension to the historic tags file format, i.e., more than a single line in the tags file with the same initial tag name. If you wish to extend your ctags implementation or other tool with which you build tags files, this extension should be simple and will require no changes to nvi.
The nvi and cscope interface is based on the new ex command cscope, which has five subcommands: add, find, help, kill and reset. The subcommand find itself has eight subcommands: c, d, e, f, g, i, s and t.
After nvi attaches to a new database, all subsequent cscope queries will be asked of that database. The result of any single query is the collection of response to the query from all of the attached databases.
If the ``CSCOPE_DIRS'' environmental variable is set when nvi is run, it is expected to be a <colon> or <blank>-separated list of cscope databases or directories containing cscope databases, to which the user wishes to attach.
The find command pushes the current location onto the tags stack, and switches to the first location resulting from the query, if the query returned at least one result.
File names returned by the cscope query, if not absolute paths, are searched for relative to the directory where the cscope database is located. In addition, if the file ``cscope.tpath'' appears in the same directory as the cscope database, it is expected to contain a colon-separated list of directory names where files referenced by its associated cscope database may be found.
The find subcommand is one of the following: