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