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