1.\" $FreeBSD: head/bin/ed/ed.1 281997 2015-04-26 10:03:05Z bapt $ 2.Dd July 3, 2004 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.Nm red 16.Op Fl 17.Op Fl sx 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 x 145Prompt for an encryption key to be used in subsequent reads and writes 146(see the 147.Em x 148command). 149.It Fl p Ar string 150Specify a command prompt. 151This may be toggled on and off with the 152.Em P 153command. 154.It Ar file 155Specify the name of a file to read. 156If 157.Ar file 158is prefixed with a 159bang (!), then it is interpreted as a shell command. 160In this case, 161what is read is 162the standard output of 163.Ar file 164executed via 165.Xr sh 1 . 166To read a file whose name begins with a bang, prefix the 167name with a backslash (\\). 168The default filename is set to 169.Ar file 170only if it is not prefixed with a bang. 171.El 172.Sh LINE ADDRESSING 173An address represents the number of a line in the buffer. 174The 175.Nm 176utility maintains a 177.Em current address 178which is 179typically supplied to commands as the default address when none is specified. 180When a file is first read, the current address is set to the last line 181of the file. 182In general, the current address is set to the last line 183affected by a command. 184.Pp 185A line address is 186constructed from one of the bases in the list below, optionally followed 187by a numeric offset. 188The offset may include any combination 189of digits, operators (i.e., 190.Em + , 191.Em - 192and 193.Em ^ ) 194and whitespace. 195Addresses are read from left to right, and their values are computed 196relative to the current address. 197.Pp 198One exception to the rule that addresses represent line numbers is the 199address 200.Em 0 201(zero). 202This means "before the first line," 203and is legal wherever it makes sense. 204.Pp 205An address range is two addresses separated either by a comma or 206semi-colon. 207The value of the first address in a range cannot exceed the 208value of the second. 209If only one address is given in a range, then 210the second address is set to the given address. 211If an 212.Em n Ns -tuple 213of addresses is given where 214.Em "n\ >\ 2" , 215then the corresponding range is determined by the last two addresses in 216the 217.Em n Ns -tuple . 218If only one address is expected, then the last address is used. 219.Pp 220Each address in a comma-delimited range is interpreted relative to the 221current address. 222In a semi-colon-delimited range, the first address is 223used to set the current address, and the second address is interpreted 224relative to the first. 225.Pp 226The following address symbols are recognized: 227.Bl -tag -width indent 228.It . 229The current line (address) in the buffer. 230.It $ 231The last line in the buffer. 232.It n 233The 234.Em n Ns th 235line in the buffer 236where 237.Em n 238is a number in the range 239.Em [0,$] . 240.It - or ^ 241The previous line. 242This is equivalent to 243.Em -1 244and may be repeated with cumulative effect. 245.It -n or ^n 246The 247.Em n Ns th 248previous line, where 249.Em n 250is a non-negative number. 251.It + 252The next line. 253This is equivalent to 254.Em +1 255and may be repeated with cumulative effect. 256.It +n 257The 258.Em n Ns th 259next line, where 260.Em n 261is a non-negative number. 262.It , or % 263The first through last lines in the buffer. 264This is equivalent to 265the address range 266.Em 1,$ . 267.It ; 268The current through last lines in the buffer. 269This is equivalent to 270the address range 271.Em .,$ . 272.It /re/ 273The next line containing the regular expression 274.Em re . 275The search wraps to the beginning of the buffer and continues down to the 276current line, if necessary. 277// repeats the last search. 278.It ?re? 279The 280previous line containing the regular expression 281.Em re . 282The search wraps to the end of the buffer and continues up to the 283current line, if necessary. 284?? repeats the last search. 285.It 'lc 286The 287line previously marked by a 288.Em k 289(mark) command, where 290.Em lc 291is a lower case letter. 292.El 293.Sh REGULAR EXPRESSIONS 294Regular expressions are patterns used in selecting text. 295For example, the command: 296.Pp 297.Sm off 298.Cm g No / Em string Xo 299.No / 300.Xc 301.Sm on 302.Pp 303prints all lines containing 304.Em string . 305Regular expressions are also 306used by the 307.Em s 308command for selecting old text to be replaced with new. 309.Pp 310In addition to a specifying string literals, regular expressions can 311represent 312classes of strings. 313Strings thus represented are said to be matched 314by the corresponding regular expression. 315If it is possible for a regular expression 316to match several strings in a line, then the left-most longest match is 317the one selected. 318.Pp 319The following symbols are used in constructing regular expressions: 320.Bl -tag -width indent 321.It c 322Any character 323.Em c 324not listed below, including 325.Ql \&{ , 326.Ql \&} , 327.Ql \&( , 328.Ql \&) , 329.Ql < 330and 331.Ql > , 332matches itself. 333.It Pf \e c 334Any backslash-escaped character 335.Em c , 336except for 337.Ql \&{ , 338.Ql \&} , 339.Ql \&( , 340.Ql \&) , 341.Ql < 342and 343.Ql > , 344matches itself. 345.It . 346Match any single character. 347.It Op char-class 348Match any single character in 349.Em char-class . 350To include a 351.Ql \&] 352in 353.Em char-class , 354it must be the first character. 355A range of characters may be specified by separating the end characters 356of the range with a 357.Ql - , 358e.g., 359.Ql a-z 360specifies the lower case characters. 361The following literal expressions can also be used in 362.Em char-class 363to specify sets of characters: 364.Pp 365.Bl -column "[:alnum:]" "[:cntrl:]" "[:lower:]" "[:xdigit:]" -compact 366.It [:alnum:] Ta [:cntrl:] Ta [:lower:] Ta [:space:] 367.It [:alpha:] Ta [:digit:] Ta [:print:] Ta [:upper:] 368.It [:blank:] Ta [:graph:] Ta [:punct:] Ta [:xdigit:] 369.El 370.Pp 371If 372.Ql - 373appears as the first or last 374character of 375.Em char-class , 376then it matches itself. 377All other characters in 378.Em char-class 379match themselves. 380.Pp 381Patterns in 382.Em char-class 383of the form: 384.Pp 385.Bl -item -compact -offset 2n 386.It 387.Op \&. Ns Ar col-elm Ns .\& 388or, 389.It 390.Op = Ns Ar col-elm Ns = 391.El 392.Pp 393where 394.Ar col-elm 395is a 396.Em collating element 397are interpreted according to the current locale settings 398(not currently supported). 399See 400.Xr regex 3 401and 402.Xr re_format 7 403for an explanation of these constructs. 404.It Op ^char-class 405Match any single character, other than newline, not in 406.Em char-class . 407.Em Char-class 408is defined 409as above. 410.It ^ 411If 412.Em ^ 413is the first character of a regular expression, then it 414anchors the regular expression to the beginning of a line. 415Otherwise, it matches itself. 416.It $ 417If 418.Em $ 419is the last character of a regular expression, it 420anchors the regular expression to the end of a line. 421Otherwise, it matches itself. 422.It Pf \e < 423Anchor the single character regular expression or subexpression 424immediately following it to the beginning of a word. 425(This may not be available) 426.It Pf \e > 427Anchor the single character regular expression or subexpression 428immediately following it to the end of a word. 429(This may not be available) 430.It Pf \e (re\e) 431Define a subexpression 432.Em re . 433Subexpressions may be nested. 434A subsequent backreference of the form 435.Pf \e Em n , 436where 437.Em n 438is a number in the range [1,9], expands to the text matched by the 439.Em n Ns th 440subexpression. 441For example, the regular expression 442.Ql \e(.*\e)\e1 443matches any string 444consisting of identical adjacent substrings. 445Subexpressions are ordered relative to 446their left delimiter. 447.It * 448Match the single character regular expression or subexpression 449immediately preceding it zero or more times. 450If 451.Em * 452is the first 453character of a regular expression or subexpression, then it matches 454itself. 455The 456.Em * 457operator sometimes yields unexpected results. 458For example, the regular expression 459.Ql b* 460matches the beginning of 461the string 462.Ql abbb 463(as opposed to the substring 464.Ql bbb ) , 465since a null match 466is the only left-most match. 467.It \e{n,m\e} or \e{n,\e} or \e{n\e} 468Match the single character regular expression or subexpression 469immediately preceding it at least 470.Em n 471and at most 472.Em m 473times. 474If 475.Em m 476is omitted, then it matches at least 477.Em n 478times. 479If the comma is also omitted, then it matches exactly 480.Em n 481times. 482.El 483.Pp 484Additional regular expression operators may be defined depending on the 485particular 486.Xr regex 3 487implementation. 488.Sh COMMANDS 489All 490.Nm 491commands are single characters, though some require additional parameters. 492If a command's parameters extend over several lines, then 493each line except for the last 494must be terminated with a backslash (\\). 495.Pp 496In general, at most one command is allowed per line. 497However, most commands accept a print suffix, which is any of 498.Em p 499(print), 500.Em l 501(list), 502or 503.Em n 504(enumerate), 505to print the last line affected by the command. 506.Pp 507An interrupt (typically ^C) has the effect of aborting the current command 508and returning the editor to command mode. 509.Pp 510The 511.Nm 512utility 513recognizes the following commands. 514The commands are shown together with 515the default address or address range supplied if none is 516specified (in parentheses). 517.Bl -tag -width indent 518.It (.)a 519Append text to the buffer after the addressed line. 520Text is entered in input mode. 521The current address is set to last line entered. 522.It (.,.)c 523Change lines in the buffer. 524The addressed lines are deleted 525from the buffer, and text is appended in their place. 526Text is entered in input mode. 527The current address is set to last line entered. 528.It (.,.)d 529Delete the addressed lines from the buffer. 530If there is a line after the deleted range, then the current address is set 531to this line. 532Otherwise the current address is set to the line 533before the deleted range. 534.It e Ar file 535Edit 536.Ar file , 537and sets the default filename. 538If 539.Ar file 540is not specified, then the default filename is used. 541Any lines in the buffer are deleted before 542the new file is read. 543The current address is set to the last line read. 544.It e Ar !command 545Edit the standard output of 546.Ar !command , 547(see 548.Ar !command 549below). 550The default filename is unchanged. 551Any lines in the buffer are deleted before the output of 552.Ar command 553is read. 554The current address is set to the last line read. 555.It E Ar file 556Edit 557.Ar file 558unconditionally. 559This is similar to the 560.Em e 561command, 562except that unwritten changes are discarded without warning. 563The current address is set to the last line read. 564.It f Ar file 565Set the default filename to 566.Ar file . 567If 568.Ar file 569is not specified, then the default unescaped filename is printed. 570.It (1,$)g/re/command-list 571Apply 572.Ar command-list 573to each of the addressed lines matching a regular expression 574.Ar re . 575The current address is set to the 576line currently matched before 577.Ar command-list 578is executed. 579At the end of the 580.Em g 581command, the current address is set to the last line affected by 582.Ar command-list . 583.Pp 584Each command in 585.Ar command-list 586must be on a separate line, 587and every line except for the last must be terminated by a backslash 588(\\). 589Any commands are allowed, except for 590.Em g , 591.Em G , 592.Em v , 593and 594.Em V . 595A newline alone in 596.Ar command-list 597is equivalent to a 598.Em p 599command. 600.It (1,$)G/re/ 601Interactively edit the addressed lines matching a regular expression 602.Ar re . 603For each matching line, 604the line is printed, 605the current address is set, 606and the user is prompted to enter a 607.Ar command-list . 608At the end of the 609.Em G 610command, the current address 611is set to the last line affected by (the last) 612.Ar command-list . 613.Pp 614The format of 615.Ar command-list 616is the same as that of the 617.Em g 618command. 619A newline alone acts as a null command list. 620A single 621.Ql & 622repeats the last non-null command list. 623.It H 624Toggle the printing of error explanations. 625By default, explanations are not printed. 626It is recommended that 627.Nm 628scripts begin with this command to aid 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 more 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 ".Pa /tmp/ed.*" -compact 918.It Pa /tmp/ed.* 919buffer file 920.It Pa 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