1.\" $NetBSD: sed.1,v 1.18 2002/02/08 01:36:32 ross Exp $ 2.\" 3.\" Copyright (c) 1992, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the Institute of Electrical and Electronics Engineers, Inc. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the University of 20.\" California, Berkeley and its contributors. 21.\" 4. Neither the name of the University nor the names of its contributors 22.\" may be used to endorse or promote products derived from this software 23.\" without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 29.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35.\" SUCH DAMAGE. 36.\" 37.\" @(#)sed.1 8.2 (Berkeley) 12/30/93 38.\" 39.Dd December 30, 1993 40.Dt SED 1 41.Os 42.Sh NAME 43.Nm sed 44.Nd stream editor 45.Sh SYNOPSIS 46.Nm 47.Op Fl anE 48.Ar command 49.Op Ar file ... 50.Nm "" 51.Op Fl anE 52.Op Fl e Ar command 53.Op Fl f Ar command_file 54.Op Ar file ... 55.Sh DESCRIPTION 56The 57.Nm 58utility reads the specified files, or the standard input if no files 59are specified, modifying the input as specified by a list of commands. 60The input is then written to the standard output. 61.Pp 62A single command may be specified as the first argument to 63.Nm "" . 64Multiple commands may be specified by using the 65.Fl e 66or 67.Fl f 68options. 69All commands are applied to the input in the order they are specified 70regardless of their origin. 71.Pp 72The following options are available: 73.Bl -tag -width indent 74.It Fl a 75The files listed as parameters for the 76.Dq w 77functions are created (or truncated) before any processing begins, 78by default. 79The 80.Fl a 81option causes 82.Nm 83to delay opening each file until a command containing the related 84.Dq w 85function is applied to a line of input. 86.It Fl e Ar command 87Append the editing commands specified by the 88.Ar command 89argument 90to the list of commands. 91.It Fl f Ar command_file 92Append the editing commands found in the file 93.Ar command_file 94to the list of commands. 95The editing commands should each be listed on a separate line. 96.It Fl n 97By default, each line of input is echoed to the standard output after 98all of the commands have been applied to it. 99The 100.Fl n 101option suppresses this behavior. 102.It Fl E 103Enables the use of extended regular expressions instead of the 104usual basic regular expression syntax. 105.El 106.Pp 107The form of a 108.Nm 109command is as follows: 110.sp 111.Dl [address[,address]]function[arguments] 112.sp 113Whitespace may be inserted before the first address and the function 114portions of the command. 115.Pp 116Normally, 117.Nm 118cyclically copies a line of input, not including its terminating newline 119character, into a 120.Em "pattern space" , 121(unless there is something left after a 122.Dq D 123function), 124applies all of the commands with addresses that select that pattern space, 125copies the pattern space to the standard output, appending a newline, and 126deletes the pattern space. 127.Pp 128Some of the functions use a 129.Em "hold space" 130to save all or part of the pattern space for subsequent retrieval. 131.Sh SED ADDRESSES 132An address is not required, but if specified must be a number (that counts 133input lines 134cumulatively across input files), a dollar 135.Po 136.Dq $ 137.Pc 138character that addresses the last line of input, or a context address 139(which consists of a regular expression preceded and followed by a 140delimiter). 141.Pp 142A command line with no addresses selects every pattern space. 143.Pp 144A command line with one address selects all of the pattern spaces 145that match the address. 146.Pp 147A command line with two addresses selects the inclusive range from 148the first pattern space that matches the first address through the next 149pattern space that matches the second. 150(If the second address is a number less than or equal to the line number 151first selected, only that line is selected.) 152Starting at the first line following the selected range, 153.Nm 154starts looking again for the first address. 155.Pp 156Editing commands can be applied to non-selected pattern spaces by use 157of the exclamation character 158.Po 159.Dq ! 160.Pc 161function. 162.Sh SED REGULAR EXPRESSIONS 163The 164.Nm 165regular expressions are basic regular expressions (BRE's, see 166.Xr regex 3 167for more information). 168In addition, 169.Nm 170has the following two additions to BRE's: 171.sp 172.Bl -enum -compact 173.It 174In a context address, any character other than a backslash 175.Po 176.Dq \e 177.Pc 178or newline character may be used to delimit the regular expression 179by prefixing the first use of that delimiter with a backslash. 180Also, putting a backslash character before the delimiting character 181causes the character to be treated literally. 182For example, in the context address \exabc\exdefx, the RE delimiter 183is an 184.Dq x 185and the second 186.Dq x 187stands for itself, so that the regular expression is 188.Dq abcxdef . 189.sp 190.It 191The escape sequence \en matches a newline character embedded in the 192pattern space. 193You can't, however, use a literal newline character in an address or 194in the substitute command. 195.El 196.Pp 197One special feature of 198.Nm 199regular expressions is that they can default to the last regular 200expression used. 201If a regular expression is empty, i.e. just the delimiter characters 202are specified, the last regular expression encountered is used instead. 203The last regular expression is defined as the last regular expression 204used as part of an address or substitute command, and at run-time, not 205compile-time. 206For example, the command 207.Dq /abc/s//XXX/ 208will substitute 209.Dq XXX 210for the pattern 211.Dq abc . 212.Sh SED FUNCTIONS 213In the following list of commands, the maximum number of permissible 214addresses for each command is indicated by [0addr], [1addr], or [2addr], 215representing zero, one, or two addresses. 216.Pp 217The argument 218.Em text 219consists of one or more lines. 220To embed a newline in the text, precede it with a backslash. 221Other backslashes in text are deleted and the following character 222taken literally. 223.Pp 224The 225.Dq r 226and 227.Dq w 228functions take an optional file parameter, which should be separated 229from the function letter by white space. 230Each file given as an argument to 231.Nm 232is created (or its contents truncated) before any input processing begins. 233.Pp 234The 235.Dq b , 236.Dq r , 237.Dq s , 238.Dq t , 239.Dq w , 240.Dq y , 241.Dq ! , 242and 243.Dq \&: 244functions all accept additional arguments. 245The following synopses indicate which arguments have to be separated from 246the function letters by white space characters. 247.Pp 248Two of the functions take a function-list. 249This is a list of 250.Nm 251functions separated by newlines, as follows: 252.Bd -literal -offset indent 253{ function 254 function 255 ... 256 function 257} 258.Ed 259.Pp 260The 261.Dq { 262can be preceded by white space and can be followed by white space. 263The function can be preceded by white space. 264The terminating 265.Dq } 266must be preceded by a newline or optional white space. 267.sp 268.Bl -tag -width "XXXXXX" -compact 269.It [2addr] function-list 270Execute function-list only when the pattern space is selected. 271.sp 272.It [1addr]a\e 273.It text 274.br 275Write 276.Em text 277to standard output immediately before each attempt to read a line of input, 278whether by executing the 279.Dq N 280function or by beginning a new cycle. 281.sp 282.It [2addr]b[label] 283Branch to the 284.Dq \&: 285function with the specified label. 286If the label is not specified, branch to the end of the script. 287.sp 288.It [2addr]c\e 289.It text 290.br 291Delete the pattern space. 292With 0 or 1 address or at the end of a 2-address range, 293.Em text 294is written to the standard output. 295.sp 296.It [2addr]d 297Delete the pattern space and start the next cycle. 298.sp 299.It [2addr]D 300Delete the initial segment of the pattern space through the first 301newline character and start the next cycle. 302.sp 303.It [2addr]g 304Replace the contents of the pattern space with the contents of the 305hold space. 306.sp 307.It [2addr]G 308Append a newline character followed by the contents of the hold space 309to the pattern space. 310.sp 311.It [2addr]h 312Replace the contents of the hold space with the contents of the 313pattern space. 314.sp 315.It [2addr]H 316Append a newline character followed by the contents of the pattern space 317to the hold space. 318.sp 319.It [1addr]i\e 320.It text 321.br 322Write 323.Em text 324to the standard output. 325.sp 326.It [2addr]l 327(The letter ell.) 328Write the pattern space to the standard output in a visually unambiguous 329form. 330This form is as follows: 331.sp 332.Bl -tag -width "carriage-returnXX" -offset indent -compact 333.It backslash 334\e\e 335.It alert 336\ea 337.It form-feed 338\ef 339.It newline 340\en 341.It carriage-return 342\er 343.It tab 344\et 345.It vertical tab 346\ev 347.El 348.Pp 349Nonprintable characters are written as three-digit octal numbers (with a 350preceding backslash) for each byte in the character (most significant byte 351first). 352Long lines are folded, with the point of folding indicated by displaying 353a backslash followed by a newline. 354The end of each line is marked with a 355.Dq $ . 356.sp 357.It [2addr]n 358Write the pattern space to the standard output if the default output has 359not been suppressed, and replace the pattern space with the next line of 360input. (Does not begin a new cycle.) 361.sp 362.It [2addr]N 363Append the next line of input to the pattern space, using an embedded 364newline character to separate the appended material from the original 365contents. 366Note that the current line number changes. 367.sp 368.It [2addr]p 369Write the pattern space to standard output. 370.sp 371.It [2addr]P 372Write the pattern space, up to the first newline character to the 373standard output. 374.sp 375.It [1addr]q 376Branch to the end of the script and quit without starting a new cycle. 377.sp 378.It [1addr]r file 379Copy the contents of 380.Em file 381to the standard output immediately before the next attempt to read a 382line of input. 383If 384.Em file 385cannot be read for any reason, it is silently ignored and no error 386condition is set. 387.sp 388.It [2addr]s/regular expression/replacement/flags 389Substitute the replacement string for the first instance of the regular 390expression in the pattern space. 391Any character other than backslash or newline can be used instead of 392a slash to delimit the RE and the replacement. 393Within the RE and the replacement, the RE delimiter itself can be used as 394a literal character if it is preceded by a backslash. 395.Pp 396An ampersand 397.Po 398.Dq \*[Am] 399.Pc 400appearing in the replacement is replaced by the string matching the RE. 401The special meaning of 402.Dq \*[Am] 403in this context can be suppressed by preceding it by a backslash. 404The string 405.Dq \e# , 406where 407.Dq # 408is a digit, is replaced by the text matched 409by the corresponding backreference expression (see 410.Xr re_format 7 ) . 411.Pp 412A line can be split by substituting a newline character into it. 413To specify a newline character in the replacement string, precede it with 414a backslash. 415.Pp 416The value of 417.Em flags 418in the substitute function is zero or more of the following: 419.Bl -tag -width "XXXXXX" -offset indent 420.It "0 ... 9" 421Make the substitution only for the N'th occurrence of the regular 422expression in the pattern space. 423.It g 424Make the substitution for all non-overlapping matches of the 425regular expression, not just the first one. 426.It p 427Write the pattern space to standard output if a replacement was made. 428If the replacement string is identical to that which it replaces, it 429is still considered to have been a replacement. 430.It w Em file 431Append the pattern space to 432.Em file 433if a replacement was made. 434If the replacement string is identical to that which it replaces, it 435is still considered to have been a replacement. 436.El 437.sp 438.It [2addr]t [label] 439Branch to the 440.Dq \&: 441function bearing the label if any substitutions have been made since the 442most recent reading of an input line or execution of a 443.Dq t 444function. 445If no label is specified, branch to the end of the script. 446.sp 447.It [2addr]w Em file 448Append the pattern space to the 449.Em file . 450.sp 451.It [2addr]x 452Swap the contents of the pattern and hold spaces. 453.sp 454.It [2addr]y/string1/string2/ 455Replace all occurrences of characters in 456.Em string1 457in the pattern space with the corresponding characters from 458.Em string2 . 459Any character other than a backslash or newline can be used instead of 460a slash to delimit the strings. 461Within 462.Em string1 463and 464.Em string2 , 465a backslash followed by any character other than a newline is that literal 466character, and a backslash followed by an ``n'' is replaced by a newline 467character. 468.sp 469.It [2addr]!function 470.It [2addr]!function-list 471Apply the function or function-list only to the lines that are 472.Em not 473selected by the address(es). 474.sp 475.It [0addr]:label 476This function does nothing; it bears a label to which the 477.Dq b 478and 479.Dq t 480commands may branch. 481.sp 482.It [1addr]= 483Write the line number to the standard output followed by a newline 484character. 485.sp 486.It [0addr] 487Empty lines are ignored. 488.sp 489.It [0addr]# 490The 491.Dq # 492and the remainder of the line are ignored (treated as a comment), with 493the single exception that if the first two characters in the file are 494.Dq #n , 495the default output is suppressed. 496This is the same as specifying the 497.Fl n 498option on the command line. 499.El 500.Pp 501The 502.Nm 503utility exits 0 on success and \*[Gt]0 if an error occurs. 504.Sh SEE ALSO 505.Xr awk 1 , 506.Xr ed 1 , 507.Xr grep 1 , 508.Xr regex 3 , 509.Xr re_format 7 510.Sh STANDARDS 511The 512.Nm 513function is expected to be a superset of the 514.St -p1003.2 515specification. 516.Sh HISTORY 517A 518.Nm 519command appeared in 520.At v7 . 521