1.\" $FreeBSD$ 2.Dd May 21, 1993 3.Dt ED 1 4.Os 5.Sh NAME 6.Nm ed , 7.Nm red 8.Nd text editor 9.Sh SYNOPSIS 10.Nm 11.Op Fl 12.Op Fl sx 13.Op Fl p Ar string 14.Op Ar file 15.LP 16.Nm red 17.Op Fl 18.Op Fl sx 19.Op Fl p Ar string 20.Op Ar file 21.Sh DESCRIPTION 22The 23.Nm 24utility is a line-oriented text editor. 25It is used to create, display, modify and otherwise manipulate text 26files. 27When invoked as 28.Nm red , 29the editor runs in 30.Qq restricted 31mode, in which the only difference is that the editor restricts the 32use of filenames which start with 33.Ql \&! 34(interpreted as shell commands by 35.Nm ed ) 36or contain a 37.Ql \&/ . 38Note that editing outside of the current directory is only prohibited 39if the user does not have write access to the current directory. 40If a user has write access to the current directory, then symbolic 41links can be created in the current directory, in which case 42.Nm red 43will not stop the user from editing the file that the symbolic link 44points to. 45.Pp 46If invoked with a 47.Ar file 48argument, then a copy of 49.Ar file 50is read into the editor's buffer. 51Changes are made to this copy and not directly to 52.Ar file 53itself. 54Upon quitting 55.Nm , 56any changes not explicitly saved with a 57.Em w 58command are lost. 59.Pp 60Editing is done in two distinct modes: 61.Em command 62and 63.Em input . 64When first invoked, 65.Nm 66is in command mode. 67In this mode commands are read from the standard input and 68executed to manipulate the contents of the editor buffer. 69A typical command might look like: 70.Pp 71.Sm off 72.Cm ,s No / Em old Xo 73.No / Em new 74.No / Cm g 75.Xc 76.Sm on 77.Pp 78which replaces all occurrences of the string 79.Em old 80with 81.Em new . 82.Pp 83When an input command, such as 84.Em a 85(append), 86.Em i 87(insert) or 88.Em c 89(change), is given, 90.Nm 91enters input mode. This is the primary means 92of adding text to a file. 93In this mode, no commands are available; 94instead, the standard input is written 95directly to the editor buffer. Lines consist of text up to and 96including a 97.Em newline 98character. 99Input mode is terminated by 100entering a single period 101.Pq Em .\& 102on a line. 103.Pp 104All 105.Nm 106commands operate on whole lines or ranges of lines; e.g., 107the 108.Em d 109command deletes lines; the 110.Em m 111command moves lines, and so on. 112It is possible to modify only a portion of a line by means of replacement, 113as in the example above. However even here, the 114.Em s 115command is applied to whole lines at a time. 116.Pp 117In general, 118.Nm 119commands consist of zero or more line addresses, followed by a single 120character command and possibly additional parameters; i.e., 121commands have the structure: 122.Pp 123.Sm off 124.Xo 125.Op Ar address Op , Ar address 126.Ar command Op Ar parameters 127.Xc 128.Sm on 129.Pp 130The address(es) indicate the line or range of lines to be affected by the 131command. If fewer addresses are given than the command accepts, then 132default addresses are supplied. 133.Sh OPTIONS 134The following options are available: 135.Bl -tag -width indent 136.It Fl s 137Suppress diagnostics. 138This should be used if 139.Nm Ns 's 140standard input is from a script. 141.It Fl x 142Prompt for an encryption key to be used in subsequent reads and writes 143(see the 144.Em x 145command). 146.It Fl p Ar string 147Specify a command prompt. This may be toggled on and off with the 148.Em P 149command. 150.It Ar file 151Specify the name of a file to read. If 152.Ar file 153is prefixed with a 154bang (!), then it is interpreted as a shell command. In this case, 155what is read is 156the standard output of 157.Ar file 158executed via 159.Xr sh 1 . 160To read a file whose name begins with a bang, prefix the 161name with a backslash (\\). 162The default filename is set to 163.Ar file 164only if it is not prefixed with a bang. 165.El 166.Sh LINE ADDRESSING 167An address represents the number of a line in the buffer. 168The 169.Nm 170utility maintains a 171.Em current address 172which is 173typically supplied to commands as the default address when none is specified. 174When a file is first read, the current address is set to the last line 175of the file. In general, the current address is set to the last line 176affected by a command. 177.Pp 178A line address is 179constructed from one of the bases in the list below, optionally followed 180by a numeric offset. The offset may include any combination 181of digits, operators (i.e., 182.Em + , 183.Em - 184and 185.Em ^ ) 186and whitespace. 187Addresses are read from left to right, and their values are computed 188relative to the current address. 189.Pp 190One exception to the rule that addresses represent line numbers is the 191address 192.Em 0 193(zero). 194This means "before the first line," 195and is legal wherever it makes sense. 196.Pp 197An address range is two addresses separated either by a comma or 198semi-colon. 199The value of the first address in a range cannot exceed the 200value of the second. If only one address is given in a range, then 201the second address is set to the given address. If an 202.Em n Ns -tuple 203of addresses is given where 204.Em "n\ >\ 2" , 205then the corresponding range is determined by the last two addresses in 206the 207.Em n Ns -tuple . 208If only one address is expected, then the last address is used. 209.Pp 210Each address in a comma-delimited range is interpreted relative to the 211current address. In a semi-colon-delimited range, the first address is 212used to set the current address, and the second address is interpreted 213relative to the first. 214.Pp 215The following address symbols are recognized: 216.Bl -tag -width indent 217.It . 218The current line (address) in the buffer. 219.It $ 220The last line in the buffer. 221.It n 222The 223.Em n Ns th, 224line in the buffer 225where 226.Em n 227is a number in the range 228.Em [0,$] . 229.It - or ^ 230The previous line. 231This is equivalent to 232.Em -1 233and may be repeated with cumulative effect. 234.It -n or ^n 235The 236.Em n Ns th 237previous line, where 238.Em n 239is a non-negative number. 240.It + 241The next line. 242This is equivalent to 243.Em +1 244and may be repeated with cumulative effect. 245.It +n 246The 247.Em n Ns th 248next line, where 249.Em n 250is a non-negative number. 251.It , or % 252The first through last lines in the buffer. This is equivalent to 253the address range 254.Em 1,$ . 255.It ; 256The current through last lines in the buffer. This is equivalent to 257the address range 258.Em .,$ . 259.It /re/ 260The next line containing the regular expression 261.Em re . 262The search wraps to the beginning of the buffer and continues down to the 263current line, if necessary. 264// repeats the last search. 265.It ?re? 266The 267previous line containing the regular expression 268.Em re . 269The search wraps to the end of the buffer and continues up to the 270current line, if necessary. 271?? repeats the last search. 272.It 'lc 273The 274line previously marked by a 275.Em k 276(mark) command, where 277.Em lc 278is a lower case letter. 279.El 280.Sh REGULAR EXPRESSIONS 281Regular expressions are patterns used in selecting text. 282For example, the command: 283.Pp 284.Sm off 285.Cm g No / Em string Xo 286.No / 287.Xc 288.Sm on 289.Pp 290prints all lines containing 291.Em string . 292Regular expressions are also 293used by the 294.Em s 295command for selecting old text to be replaced with new. 296.Pp 297In addition to a specifying string literals, regular expressions can 298represent 299classes of strings. Strings thus represented are said to be matched 300by the corresponding regular expression. 301If it is possible for a regular expression 302to match several strings in a line, then the left-most longest match is 303the one selected. 304.Pp 305The following symbols are used in constructing regular expressions: 306.Bl -tag -width indent 307.It c 308Any character 309.Em c 310not listed below, including `{', '}', `(', `)', `<' and `>', 311matches itself. 312.It Pf \e c 313Any backslash-escaped character 314.Em c , 315except for `{', '}', `(', `)', `<' and `>', 316matches itself. 317.It . 318Match any single character. 319.It Op char-class 320Match any single character in 321.Em char-class . 322To include a `]' 323in 324.Em char-class , 325it must be the first character. 326A range of characters may be specified by separating the end characters 327of the range with a `-', e.g., `a-z' specifies the lower case characters. 328The following literal expressions can also be used in 329.Em char-class 330to specify sets of characters: 331.Pp 332.Bl -column "[:alnum:]" "[:cntrl:]" "[:lower:]" "[:xdigit:]" -compact 333.It [:alnum:] Ta [:cntrl:] Ta [:lower:] Ta [:space:] 334.It [:alpha:] Ta [:digit:] Ta [:print:] Ta [:upper:] 335.It [:blank:] Ta [:graph:] Ta [:punct:] Ta [:xdigit:] 336.El 337.Pp 338If `-' appears as the first or last 339character of 340.Em char-class , 341then it matches itself. 342All other characters in 343.Em char-class 344match themselves. 345.Pp 346Patterns in 347.Em char-class 348of the form: 349.Pp 350.Bl -item -compact -offset 2n 351.It 352.Op \&. Ns Ar col-elm Ns .\& 353or, 354.It 355.Op = Ns Ar col-elm Ns = 356.El 357.Pp 358where 359.Ar col-elm 360is a 361.Em collating element 362are interpreted according to 363.Xr locale 5 364(not currently supported). 365See 366.Xr regex 3 367for an explanation of these constructs. 368.It Op ^char-class 369Match any single character, other than newline, not in 370.Em char-class . 371.Em Char-class 372is defined 373as above. 374.It ^ 375If 376.Em ^ 377is the first character of a regular expression, then it 378anchors the regular expression to the beginning of a line. 379Otherwise, it matches itself. 380.It $ 381If 382.Em $ 383is the last character of a regular expression, it 384anchors the regular expression to the end of a line. 385Otherwise, it matches itself. 386.It Pf \e < 387Anchor the single character regular expression or subexpression 388immediately following it to the beginning of a word. 389(This may not be available) 390.It Pf \e > 391Anchor the single character regular expression or subexpression 392immediately following it to the end of a word. 393(This may not be available) 394.It Pf \e (re\e) 395Define a subexpression 396.Em re . 397Subexpressions may be nested. 398A subsequent backreference of the form 399.Pf \e Em n , 400where 401.Em n 402is a number in the range [1,9], expands to the text matched by the 403.Em n Ns th 404subexpression. 405For example, the regular expression `\e(.*\e)\e1' matches any string 406consisting of identical adjacent substrings. 407Subexpressions are ordered relative to 408their left delimiter. 409.It * 410Match the single character regular expression or subexpression 411immediately preceding it zero or more times. If 412.Em * 413is the first 414character of a regular expression or subexpression, then it matches 415itself. The 416.Em * 417operator sometimes yields unexpected results. 418For example, the regular expression `b*' matches the beginning of 419the string `abbb' (as opposed to the substring `bbb'), since a null match 420is the only left-most match. 421.It \e{n,m\e} or \e{n,\e} or \e{n\e} 422Match the single character regular expression or subexpression 423immediately preceding it at least 424.Em n 425and at most 426.Em m 427times. 428If 429.Em m 430is omitted, then it matches at least 431.Em n 432times. 433If the comma is also omitted, then it matches exactly 434.Em n 435times. 436.El 437.Pp 438Additional regular expression operators may be defined depending on the 439particular 440.Xr regex 3 441implementation. 442.Sh COMMANDS 443All 444.Nm 445commands are single characters, though some require additional parameters. 446If a command's parameters extend over several lines, then 447each line except for the last 448must be terminated with a backslash (\\). 449.Pp 450In general, at most one command is allowed per line. 451However, most commands accept a print suffix, which is any of 452.Em p 453(print), 454.Em l 455(list), 456or 457.Em n 458(enumerate), 459to print the last line affected by the command. 460.Pp 461An interrupt (typically ^C) has the effect of aborting the current command 462and returning the editor to command mode. 463.Pp 464The 465.Nm 466utility 467recognizes the following commands. The commands are shown together with 468the default address or address range supplied if none is 469specified (in parenthesis). 470.Bl -tag -width indent 471.It (.)a 472Append text to the buffer after the addressed line. 473Text is entered in input mode. 474The current address is set to last line entered. 475.It (.,.)c 476Change lines in the buffer. The addressed lines are deleted 477from the buffer, and text is appended in their place. 478Text is entered in input mode. 479The current address is set to last line entered. 480.It (.,.)d 481Delete the addressed lines from the buffer. 482If there is a line after the deleted range, then the current address is set 483to this line. 484Otherwise the current address is set to the line 485before the deleted range. 486.It e Ar file 487Edit 488.Ar file , 489and sets the default filename. 490If 491.Ar file 492is not specified, then the default filename is used. 493Any lines in the buffer are deleted before 494the new file is read. 495The current address is set to the last line read. 496.It e Ar !command 497Edit the standard output of 498.Ar !command , 499(see 500.Ar !command 501below). 502The default filename is unchanged. 503Any lines in the buffer are deleted before the output of 504.Ar command 505is read. 506The current address is set to the last line read. 507.It E Ar file 508Edit 509.Ar file 510unconditionally. 511This is similar to the 512.Em e 513command, 514except that unwritten changes are discarded without warning. 515The current address is set to the last line read. 516.It f Ar file 517Set the default filename to 518.Ar file . 519If 520.Ar file 521is not specified, then the default unescaped filename is printed. 522.It (1,$)g/re/command-list 523Apply 524.Ar command-list 525to each of the addressed lines matching a regular expression 526.Ar re . 527The current address is set to the 528line currently matched before 529.Ar command-list 530is executed. 531At the end of the 532.Em g 533command, the current address is set to the last line affected by 534.Ar command-list . 535.Pp 536Each command in 537.Ar command-list 538must be on a separate line, 539and every line except for the last must be terminated by a backslash 540(\\). 541Any commands are allowed, except for 542.Em g , 543.Em G , 544.Em v , 545and 546.Em V . 547A newline alone in 548.Ar command-list 549is equivalent to a 550.Em p 551command. 552.It (1,$)G/re/ 553Interactively edit the addressed lines matching a regular expression 554.Ar re . 555For each matching line, 556the line is printed, 557the current address is set, 558and the user is prompted to enter a 559.Ar command-list . 560At the end of the 561.Em G 562command, the current address 563is set to the last line affected by (the last) 564.Ar command-list . 565.Pp 566The format of 567.Ar command-list 568is the same as that of the 569.Em g 570command. A newline alone acts as a null command list. 571A single `&' repeats the last non-null command list. 572.It H 573Toggle the printing of error explanations. 574By default, explanations are not printed. 575It is recommended that ed scripts begin with this command to 576aid in debugging. 577.It h 578Print an explanation of the last error. 579.It (.)i 580Insert text in the buffer before the current line. 581Text is entered in input mode. 582The current address is set to the last line entered. 583.It (.,.+1)j 584Join the addressed lines. The addressed lines are 585deleted from the buffer and replaced by a single 586line containing their joined text. 587The current address is set to the resultant line. 588.It (.)klc 589Mark a line with a lower case letter 590.Em lc . 591The line can then be addressed as 592.Em 'lc 593(i.e., a single quote followed by 594.Em lc ) 595in subsequent commands. The mark is not cleared until the line is 596deleted or otherwise modified. 597.It (.,.)l 598Print the addressed lines unambiguously. 599If a single line fills for than one screen (as might be the case 600when viewing a binary file, for instance), a `--More--' 601prompt is printed on the last line. 602The 603.Nm 604utility waits until the RETURN key is pressed 605before displaying the next screen. 606The current address is set to the last line 607printed. 608.It (.,.)m(.) 609Move lines in the buffer. The addressed lines are moved to after the 610right-hand destination address, which may be the address 611.Em 0 612(zero). 613The current address is set to the 614last line moved. 615.It (.,.)n 616Print the addressed lines along with 617their line numbers. The current address is set to the last line 618printed. 619.It (.,.)p 620Print the addressed lines. 621The current address is set to the last line 622printed. 623.It P 624Toggle the command prompt on and off. 625Unless a prompt was specified by with command-line option 626.Fl p Ar string , 627the command prompt is by default turned off. 628.It q 629Quit 630.Nm . 631.It Q 632Quit 633.Nm 634unconditionally. 635This is similar to the 636.Em q 637command, 638except that unwritten changes are discarded without warning. 639.It ($)r Ar file 640Read 641.Ar file 642to after the addressed line. If 643.Ar file 644is not specified, then the default 645filename is used. If there was no default filename prior to the command, 646then the default filename is set to 647.Ar file . 648Otherwise, the default filename is unchanged. 649The current address is set to the last line read. 650.It ($)r Ar !command 651Read 652to after the addressed line 653the standard output of 654.Ar !command , 655(see the 656.Ar !command 657below). 658The default filename is unchanged. 659The current address is set to the last line read. 660.It (.,.)s/re/replacement/ 661.It (.,.)s/re/replacement/g 662.It (.,.)s/re/replacement/n 663Replace text in the addressed lines 664matching a regular expression 665.Ar re 666with 667.Ar replacement . 668By default, only the first match in each line is replaced. 669If the 670.Em g 671(global) suffix is given, then every match to be replaced. 672The 673.Em n 674suffix, where 675.Em n 676is a positive number, causes only the 677.Em n Ns th 678match to be replaced. 679It is an error if no substitutions are performed on any of the addressed 680lines. 681The current address is set the last line affected. 682.Pp 683.Ar Re 684and 685.Ar replacement 686may be delimited by any character other than space and newline 687(see the 688.Em s 689command below). 690If one or two of the last delimiters is omitted, then the last line 691affected is printed as though the print suffix 692.Em p 693were specified. 694.Pp 695An unescaped `&' in 696.Ar replacement 697is replaced by the currently matched text. 698The character sequence 699.Em \em , 700where 701.Em m 702is a number in the range [1,9], is replaced by the 703.Em m th 704backreference expression of the matched text. 705If 706.Ar replacement 707consists of a single `%', then 708.Ar replacement 709from the last substitution is used. 710Newlines may be embedded in 711.Ar replacement 712if they are escaped with a backslash (\\). 713.It (.,.)s 714Repeat the last substitution. 715This form of the 716.Em s 717command accepts a count suffix 718.Em n , 719or any combination of the characters 720.Em r , 721.Em g , 722and 723.Em p . 724If a count suffix 725.Em n 726is given, then only the 727.Em n Ns th 728match is replaced. 729The 730.Em r 731suffix causes 732the regular expression of the last search to be used instead of the 733that of the last substitution. 734The 735.Em g 736suffix toggles the global suffix of the last substitution. 737The 738.Em p 739suffix toggles the print suffix of the last substitution 740The current address is set to the last line affected. 741.It (.,.)t(.) 742Copy (i.e., transfer) the addressed lines to after the right-hand 743destination address, which may be the address 744.Em 0 745(zero). 746The current address is set to the last line 747copied. 748.It u 749Undo the last command and restores the current address 750to what it was before the command. 751The global commands 752.Em g , 753.Em G , 754.Em v , 755and 756.Em V . 757are treated as a single command by undo. 758.Em u 759is its own inverse. 760.It (1,$)v/re/command-list 761Apply 762.Ar command-list 763to each of the addressed lines not matching a regular expression 764.Ar re . 765This is similar to the 766.Em g 767command. 768.It (1,$)V/re/ 769Interactively edit the addressed lines not matching a regular expression 770.Ar re . 771This is similar to the 772.Em G 773command. 774.It (1,$)w Ar file 775Write the addressed lines to 776.Ar file . 777Any previous contents of 778.Ar file 779is lost without warning. 780If there is no default filename, then the default filename is set to 781.Ar file , 782otherwise it is unchanged. If no filename is specified, then the default 783filename is used. 784The current address is unchanged. 785.It (1,$)wq Ar file 786Write the addressed lines to 787.Ar file , 788and then executes a 789.Em q 790command. 791.It (1,$)w Ar !command 792Write the addressed lines to the standard input of 793.Ar !command , 794(see the 795.Em !command 796below). 797The default filename and current address are unchanged. 798.It (1,$)W Ar file 799Append the addressed lines to the end of 800.Ar file . 801This is similar to the 802.Em w 803command, expect that the previous contents of file is not clobbered. 804The current address is unchanged. 805.It x 806Prompt for an encryption key which is used in subsequent reads and 807writes. If a newline alone is entered as the key, then encryption is 808turned off. Otherwise, echoing is disabled while a key is read. 809Encryption/decryption is done using the 810.Xr bdes 1 811algorithm. 812.It Pf (.+1)z n 813Scroll 814.Ar n 815lines at a time starting at addressed line. If 816.Ar n 817is not specified, then the current window size is used. 818The current address is set to the last line printed. 819.It !command 820Execute 821.Ar command 822via 823.Xr sh 1 . 824If the first character of 825.Ar command 826is `!', then it is replaced by text of the 827previous 828.Ar !command . 829The 830.Nm 831utility does not process 832.Ar command 833for backslash (\\) escapes. 834However, an unescaped 835.Em % 836is replaced by the default filename. 837When the shell returns from execution, a `!' 838is printed to the standard output. 839The current line is unchanged. 840.It ($)= 841Print the line number of the addressed line. 842.It (.+1)newline 843Print the addressed line, and sets the current address to 844that line. 845.El 846.Sh FILES 847.Bl -tag -width /tmp/ed.* -compact 848.It /tmp/ed.* 849buffer file 850.It ed.hup 851the file to which 852.Nm 853attempts to write the buffer if the terminal hangs up 854.El 855.Sh SEE ALSO 856.Xr bdes 1 , 857.Xr sed 1 , 858.Xr sh 1 , 859.Xr vi 1 , 860.Xr regex 3 861.Pp 862USD:12-13 863.Rs 864.%A B. W. Kernighan 865.%A P. J. Plauger 866.%B Software Tools in Pascal 867.%O Addison-Wesley 868.%D 1981 869.Re 870.Sh LIMITATIONS 871The 872.Nm 873utility processes 874.Ar file 875arguments for backslash escapes, i.e., in a filename, 876any characters preceded by a backslash (\\) are 877interpreted literally. 878.Pp 879If a text (non-binary) file is not terminated by a newline character, 880then 881.Nm 882appends one on reading/writing it. In the case of a binary file, 883.Nm 884does not append a newline on reading/writing. 885.Pp 886per line overhead: 4 ints 887.Sh DIAGNOSTICS 888When an error occurs, 889.Nm 890prints a `?' and either returns to command mode 891or exits if its input is from a script. 892An explanation of the last error can be 893printed with the 894.Em h 895(help) command. 896.Pp 897Since the 898.Em g 899(global) command masks any errors from failed searches and substitutions, 900it can be used to perform conditional operations in scripts; e.g., 901.Pp 902.Sm off 903.Cm g No / Em old Xo 904.No / Cm s 905.No // Em new 906.No / 907.Xc 908.Sm on 909.Pp 910replaces any occurrences of 911.Em old 912with 913.Em new . 914If the 915.Em u 916(undo) command occurs in a global command list, then 917the command list is executed only once. 918.Pp 919If diagnostics are not disabled, attempting to quit 920.Nm 921or edit another file before writing a modified buffer 922results in an error. 923If the command is entered a second time, it succeeds, 924but any changes to the buffer are lost. 925.Sh HISTORY 926An 927.Nm 928command appeared in 929Version 1 AT&T UNIX. 930