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