usr.bin/vi/docs/vi.ref

   1 .\" Copyright (c) 1994
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)vi.ref      8.19 (Berkeley) 3/18/94
  33 .\"
  34 .Dd "March 18, 1994"
  35 .Dt "EX/VI REFERENCE MANUAL" 1
  36 .Os
  37 .Sh NAME
  38 .Nm ex, vi, view
  39 .Nd text editors
  40 .Sh DESCRIPTION
  41 .Nm \&Vi
  42 is a screen oriented text editor.
  43 .Nm \&Ex
  44 is a line-oriented text editor.
  45 .Nm \&Ex
  46 and
  47 .Nm \&vi
  48 are different interfaces to the same program,
  49 and it is possible to switch back and forth during an edit session.
  50 .Nm View
  51 is the equivalent of using the
  52 .Fl R
  53 (read-only) option of
  54 .Nm \&vi .
  55 .Pp
  56 This reference manual is the one provided with the
  57 .Nm nex/nvi
  58 versions of the
  59 .Nm ex/vi
  60 text editors.
  61 .Nm Nex/nvi
  62 are intended as bug-for-bug compatible replacements for the original
  63 Fourth Berkeley Software Distribution (4BSD)
  64 .Nm \&ex
  65 and
  66 .Nm \&vi
  67 programs.
  68 This reference manual is accompanied by a traditional-style manual page.
  69 That manual page describes the functionality found in
  70 .Nm ex/vi
  71 in far less detail than the description here.
  72 In addition, it describes the system interface to
  73 .Nm ex/vi ,
  74 e.g. command line options, environmental variables, and similar things.
  75 .Pp
  76 This reference is intended for users already familiar with
  77 .Nm ex/vi .
  78 Anyone else should almost certainly read a good tutorial on the
  79 editor first.
  80 If you're in an unfamiliar environment, and you absolutely have to
  81 get work done immediately, see the section entitled FAST STARTUP
  82 in the manual page.
  83 It's probably enough to get you going.
  84 .Pp
  85 For the rest of this reference,
  86 .Nm nex/nvi
  87 is used only when it's necessary to distinguish it from the historic
  88 implementations of
  89 .Nm ex/vi .
  90 .Sh ADDITIONAL FEATURES
  91 There are a few features in
  92 .Nm nex/nvi
  93 that are not found in historic versions of
  94 .Nm ex/vi .
  95 A list of those features is as follows:
  96 .Bl -tag -width indent
  97 .It "8-bit clean data, large lines, files"
  98 .Nm \&Nvi/nex
  99 will edit any format file.
 100 Line lengths are limited by available memory,
 101 and file sizes are limited by available disk space.
 102 The command
 103 .Dq "^Vx[0-9A-Fa-f]* ,"
 104 in input mode, will insert any
 105 legal character value into the text.
 106 .It "Split screens"
 107 The command
 108 .Dq ":sp[lit] [file ...]"
 109 splits the screen in vi mode.
 110 The key
 111 .Dq "^W"
 112 switches between the foreground screens,
 113 and the
 114 .Dq ":resize count"
 115 command can be used to grow or shrink a particular screen.
 116 .It "Background and foreground screens"
 117 The command
 118 .Dq ":bg"
 119 backgrounds the current screen,
 120 and the command
 121 .Dq ":fg [file]"
 122 foregrounds the backgrounded screen
 123 that is editing the specified file, or, by default, the first background
 124 screen on the queue.
 125 The command
 126 .Dq ":di[splay] s[creens]"
 127 lists the background screens.
 128 .It "Shell screens"
 129 The command
 130 .Dq ":sc[ript] [file ...]"
 131 runs a shell in the screen.
 132 Editing is unchanged, with the exception that a <carriage-return>
 133 enters the current line (stripped of any prompt) as input to the
 134 shell.
 135 .It "Tag stacks"
 136 Tags are now maintained in a stack.
 137 The command
 138 .Dq "^T"
 139 returns to the previous tag location.
 140 The command
 141 .Dq ":tagpop [number \| file]"
 142 returns to the most recent tag
 143 location by default, or, optionally to a specific tag number in the
 144 tag stack, or the most recent tag from the specified file.
 145 Use the command
 146 .Dq ":di[splay] t[ags]"
 147 to view the tags stack.
 148 The command
 149 .Dq ":tagtop"
 150 returns to the top of the tag stack.
 151 .It "New displays"
 152 The command
 153 .Dq ":di[splay] b[uffers] \| s[creens] \| t[ags]"
 154 can be
 155 used to display, respectively, the current cut buffers,
 156 the backgrounded screens, and the tags stack.
 157 .It "Infinite undo"
 158 The changes made during an edit session may be rolled backward and
 159 forward.
 160 A '.' command immediately after a 'u' command continues either forward
 161 or backward depending on whether the 'u' command was an undo or a redo.
 162 .It "Usage information"
 163 The command
 164 .Dq ":exu[sage] [cmd]"
 165 and
 166 .Dq "viu[sage] [key]"
 167 provide usage
 168 information for all of the ex and vi commands by default, or, optionally,
 169 for a specific command or key.
 170 .It "Extended regular expressions"
 171 The
 172 .Dq ":set extended"
 173 command treats search and other command regular
 174 expressions as extended (egrep(1) style) regular expressions.
 175 .It "Word search"
 176 The command
 177 .Dq "^A"
 178 searches for the word referenced by the cursor.
 179 .It "Number increment"
 180 The command
 181 .Dq "#"
 182 increments the number referenced by the cursor.
 183 .It "Previous file"
 184 The command
 185 .Dq ":prev[ious][!]"
 186 edits the previous file from the
 187 argument list.
 188 .It "Left-Right scrolling"
 189 The command
 190 .Dq ":set leftright"
 191 makes
 192 .Nm nvi
 193 do left-right screen scrolling, instead of the traditional
 194 .Nm \&vi
 195 line wrapping.
 196 .Sh RECOVERY
 197 There is no recovery program for
 198 .Nm nvi ,
 199 nor does
 200 .Nm nvi
 201 run setuid.
 202 Users may recover any file which they may read, and the superuser
 203 may recover any edit session.
 204 .Pp
 205 Edit sessions are backed by files in
 206 .Pa /var/tmp/vi.recover ,
 207 and are named
 208 .Dq "vi.XXXX" ,
 209 where
 210 .Dq "XXXX"
 211 is a number related to the process id.
 212 When a file is first modified, a second file, which contains an
 213 email message for the user, is created, and is named
 214 .Dq "recover.XXXX" ,
 215 where, again,
 216 .Dq "XXXX"
 217 is associated with the process id.
 218 Both files are removed at the end of a normal edit session,
 219 but will remain if the edit session is abnormally terminated
 220 or the user enters the ex/vi
 221 .Dq "preserve"
 222 command.
 223 The use of the
 224 .Pa /var/tmp
 225 directory may be changed setting the
 226 .Sy recdir
 227 option in the user's or system startup information.
 228 .Pp
 229 The recovery directory should have the
 230 .Dq "sticky-bit"
 231 set so that only the owners of files may remove them.
 232 If this is not possible on the system, then a pseudo-user should
 233 own the recovery directory.
 234 The recovery directory must be both read and write-able by
 235 any user.
 236 .Pp
 237 The recovery file has all of the necessary information in it to enable the
 238 user to recover the edit session.
 239 In addition, it has all of the necessary email headers for sendmail.
 240 When the system is rebooted, all of the files in
 241 .Pa /var/tmp/vi.recover
 242 named
 243 .Dq "recover.XXXX"
 244 should be sent by email,
 245 using the
 246 .Fl t
 247 flag of sendmail (or a similar mechanism in other mailers).
 248 A simple way to do this is to insert the following script into your
 249 .Pa /etc/rc.local
 250 (or other startup) file:
 251 .ne 7v
 252 .Bd -literal -offset indent -compact
 253 # Recover nvi editor files.
 254 virecovery=`echo /var/tmp/vi.recover/recover.*`
 255 if [ "$virecovery" != "/var/tmp/vi.recover/recover.*" ]; then
 256         echo 'Recovering vi editor sessions'
 257         for i in $virecovery; do
 258                 sendmail -t < $i
 259         done
 260 fi
 261 .Ed
 262 .Pp
 263 If
 264 .Nm ex/vi
 265 receives a hangup (SIGHUP) signal, it will email the recovery
 266 information to the user itself.
 267 .Pp
 268 If you don't have the sendmail program on your system, the source file
 269 .Pa nvi/recover.c
 270 will have to be modified to use your local mail delivery programs.
 271 .Sh STARTUP INFORMATION
 272 .Nm Ex/vi
 273 interprets one of two possible environmental variables and reads up
 274 to three of five possible files during startup.
 275 The variables and files are expected to contain
 276 .Nm \&ex
 277 commands, not
 278 .Nm \&vi
 279 commands.
 280 In addition, they are interpreted
 281 .Em before
 282 the file to be edited is read, and therefore many
 283 .Nm \&ex
 284 commands may not be used.
 285 Generally, any command that requires output to the screen or that
 286 needs a file upon which to operate, will cause an error if included
 287 in a startup file or environmental variable.
 288 .Pp
 289 First, the file
 290 .Pa /etc/vi.exrc
 291 is read.
 292 Second, the environmental variable
 293 .Ev NEXINIT
 294 (or the variable
 295 .Ev EXINIT ,
 296 if
 297 .Ev NEXINIT
 298 isn't set) is interpreted.
 299 Third, if neither
 300 .Ev NEXINIT
 301 or
 302 .Ev EXINIT
 303 was set, the file
 304 .Pa $HOME/.nexrc
 305 (or the file
 306 .Pa $HOME/.exrc ,
 307 if
 308 .Pa $HOME/.nexrc
 309 doesn't exist) is read.
 310 Fourth, the file
 311 .Pa .nexrc
 312 (or the file
 313 .Pa .exrc ,
 314 if
 315 .Pa .nexrc
 316 doesn't exist) is read.
 317 .Pp
 318 Startup files will not be read if they are owned by anyone other
 319 than the real user-id of the user running
 320 .Nm \&vi ,
 321 (or by
 322 .Dq root
 323 in the case of the file
 324 .Pa /etc/vi.exrc )
 325 or if they are writable by anyone other than the owner.
 326 Home directory startup files (i.e.
 327 .Pa $HOME/.nexrc
 328 and
 329 .Pa $HOME/.exrc )
 330 will not be read if the
 331 .Dq HOME
 332 environmental variable is not set.
 333 Local startup files (i.e.
 334 .Pa .nexrc
 335 and
 336 .Pa .exrc )
 337 will not be read if the
 338 .Sy exrc
 339 option is turned off in the
 340 .Pa /etc/vi.exrc ,
 341 .Pa $HOME/.nexrc ,
 342 or
 343 .Pa $HOME/.exrc
 344 files, or in the
 345 .Ev NEXINIT
 346 or
 347 .Ev EXINIT
 348 environmental variables.
 349 It is not an error for any of the startup environmental variables
 350 or files not to exist.
 351 .Pp
 352 Because the
 353 .Nm \&ex
 354 command set supported by
 355 .Nm nex/nvi
 356 is a superset of the command set supported by most historical implementations
 357 of
 358 .Nm \&ex ,
 359 .Nm nex/nvi
 360 can use the startup files created for the historical implementations,
 361 but the converse is often not true.
 362 .Sh SIZING THE SCREEN
 363 The size of the screen can be set in a number of ways.
 364 .Nm Ex/vi
 365 takes the following steps until values are obtained for both the
 366 number of rows and number of columns in the screen.
 367 .sp
 368 .Bl -enum -compact
 369 .It
 370 If the environmental variable
 371 .Ev LINES
 372 exists, it is used to specify the number of rows in the screen.
 373 .It
 374 If the environmental variable
 375 .Ev COLUMNS
 376 exists, it is used to specify the number of columns in the screen.
 377 .It
 378 The TIOCGWINSZ
 379 .Xr ioctl 2
 380 is attempted on the standard error file descriptor.
 381 .It
 382 The termcap entry is checked for the
 383 .Dq \&li
 384 entry (rows) and the
 385 .Dq \&co
 386 entry (columns).
 387 .It
 388 The number of rows is set to 24, and the number of columns is set
 389 to 80.
 390 .El
 391 .Pp
 392 If a window change size signal (SIGWINCH) is received,
 393 the same steps are taken with the exception that the first two steps
 394 are skipped.
 395 .Sh REGULAR EXPRESSIONS AND REPLACEMENT STRINGS
 396 Regular expressions are used in line addresses,
 397 as the first part of
 398 .Sy substitute ,
 399 .Sy global ,
 400 and
 401 .Sy vglobal
 402 commands,
 403 and in search patterns.
 404 .Pp
 405 The regular expressions supported by
 406 .Nm \&ex
 407 and
 408 .Nm \&vi
 409 are, by default, the Basic Regular Expressions (BRE's) described in the
 410 IEEE POSIX Standard 1003.2.
 411 The
 412 .Sy extended
 413 option causes all regular expressions to be interpreted as the Extended
 414 Regular Expressions (ERE's) described by the same standard.
 415 (See
 416 .Xr re_format 7
 417 for more information.
 418 Generally speaking, BRE's are
 419 .Xr ed 1
 420 and
 421 .Xr grep 1
 422 style regular expressions, and ERE's are
 423 .Xr egrep 1
 424 style regular expressions.)
 425 .Pp
 426 There are some special strings and characters that can be used in
 427 RE's:
 428 .Bl -enum -compact
 429 .It
 430 An empty RE (e.g.
 431 .Dq \&// )
 432 is equivalent to the last RE used.
 433 .It
 434 The construct
 435 .Dq \e<
 436 matches the beginning of a word.
 437 .It
 438 The construct
 439 .Dq \e>
 440 matches the end of a word.
 441 .It
 442 The character
 443 .Dq \&~
 444 matches the replacement part of the last
 445 .Sy substitute
 446 command.
 447 .El
 448 .Pp
 449 When the
 450 .Sy magic
 451 option is
 452 .Em not
 453 set,
 454 the only characters with special meanings are
 455 .Dq \&^
 456 at the beginning of an RE,
 457 .Dq \&$
 458 at the end of an RE, and the escaping character
 459 .Dq \&\e .
 460 The characters
 461 .Dq \&. ,
 462 .Dq \&* ,
 463 .Dq \&[ ,
 464 and
 465 .Dq \&~
 466 are treated as ordinary characters unless preceded by a
 467 .Dq \&\e ;
 468 when preceded by a
 469 .Dq \&\e
 470 they regain their special meaning.
 471 .Pp
 472 Replacement strings are the second part of a
 473 .Sy substitute
 474 command.
 475 .Pp
 476 The character
 477 .Dq \&&
 478 (or
 479 .Dq \e&
 480 if the
 481 .Sy magic
 482 option is
 483 .Em not
 484 set) in the replacement string stands for the text matched by the RE
 485 that's being replaced.
 486 The character
 487 .Dq \&~
 488 (or
 489 .Dq \e~
 490 if the
 491 .Sy magic
 492 option is
 493 .Em not
 494 set) stands for the replacement part of the previous
 495 .Sy substitute
 496 command.
 497 .Pp
 498 The string
 499 .Dq \e# ,
 500 where
 501 .Dq \&#
 502 is an integer value from 1 to 9, stands for the text matched by
 503 the portion of the RE enclosed in the #'th set of escaped parentheses,
 504 e.g.
 505 .Dq \e(
 506 and
 507 .Dq \e) .
 508 For example,
 509 .Dq "s/abc\e(.*\e)def/\e1/"
 510 deletes the strings
 511 .Dq abc
 512 and
 513 .Dq def
 514 from the matched pattern.
 515 .Pp
 516 The strings
 517 .Dq \el ,
 518 .Dq \eu ,
 519 .Dq \eL ,
 520 and
 521 .Dq \eU
 522 can be used to modify the case of elements in the replacement string.
 523 The string
 524 .Dq \el
 525 causes the next character to be converted to lowercase; the string
 526 .Dq \eu
 527 behaves similarly, but converts to uppercase.
 528 The strings
 529 .Dq \eL
 530 causes characters up to the end of the string or the next occurrence of
 531 the strings
 532 .Dq \ee
 533 or
 534 .Dq \eE
 535 to be converted to lowercase; the string
 536 .Dq \eU
 537 behaves similarly, but converts to uppercase.
 538 .Pp
 539 In
 540 .Nm \&vi ,
 541 inserting a <control-M> into the replacement string will cause the
 542 matched line to be split into two lines at that point.
 543 .Sh SET OPTIONS
 544 #include <set.opt.roff>