usr.bin/sed/sed.1

   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
  52 The
  53 .Nm
  54 utility reads the specified files, or the standard input if no files
  55 are specified, modifying the input as specified by a list of commands.
  56 The input is then written to the standard output.
  57 .Pp
  58 A single command may be specified as the first argument to
  59 .Nm .
  60 Multiple commands may be specified by using the
  61 .Fl e
  62 or
  63 .Fl f
  64 options.
  65 All commands are applied to the input in the order they are specified
  66 regardless of their origin.
  67 .Pp
  68 The following options are available:
  69 .Bl -tag -width indent
  70 .It Fl a
  71 The files listed as parameters for the
  72 .Dq w
  73 functions are created (or truncated) before any processing begins,
  74 by default.
  75 The
  76 .Fl a
  77 option causes
  78 .Nm
  79 to delay opening each file until a command containing the related
  80 .Dq w
  81 function is applied to a line of input.
  82 .It Fl E
  83 Enables the use of extended regular expressions instead of the
  84 usual basic regular expression syntax.
  85 .It Fl e Ar command
  86 Append the editing commands specified by the
  87 .Ar command
  88 argument
  89 to the list of commands.
  90 .It Fl f Ar command_file
  91 Append the editing commands found in the file
  92 .Ar command_file
  93 to the list of commands.
  94 The editing commands should each be listed on a separate line.
  95 .It Fl n
  96 By default, each line of input is echoed to the standard output after
  97 all of the commands have been applied to it.
  98 The
  99 .Fl n
 100 option suppresses this behavior.
 101 .It Fl r
 102 Identical to
 103 .Fl E ,
 104 present for compatibility with GNU sed.
 105 .El
 106 .Pp
 107 The form of a
 108 .Nm
 109 command is as follows:
 110 .sp
 111 .Dl [address[,address]]function[arguments]
 112 .sp
 113 Whitespace may be inserted before the first address and the function
 114 portions of the command.
 115 .Pp
 116 Normally,
 117 .Nm
 118 cyclically copies a line of input, not including its terminating newline
 119 character, into a
 120 .Em "pattern space" ,
 121 (unless there is something left after a
 122 .Dq D
 123 function),
 124 applies all of the commands with addresses that select that pattern space,
 125 copies the pattern space to the standard output, appending a newline, and
 126 deletes the pattern space.
 127 .Pp
 128 Some of the functions use a
 129 .Em "hold space"
 130 to save all or part of the pattern space for subsequent retrieval.
 131 .Sh SED ADDRESSES
 132 An address is not required, but if specified must be a number (that counts
 133 input lines
 134 cumulatively across input files), a dollar
 135 .Po
 136 .Dq $
 137 .Pc
 138 character that addresses the last line of input, or a context address
 139 (which consists of a regular expression preceded and followed by a
 140 delimiter).
 141 .Pp
 142 A command line with no addresses selects every pattern space.
 143 .Pp
 144 A command line with one address selects all of the pattern spaces
 145 that match the address.
 146 .Pp
 147 A command line with two addresses selects the inclusive range from
 148 the first pattern space that matches the first address through the next
 149 pattern space that matches the second.
 150 (If the second address is a number less than or equal to the line number
 151 first selected, only that line is selected.)
 152 Starting at the first line following the selected range,
 153 .Nm
 154 starts looking again for the first address.
 155 .Pp
 156 Editing commands can be applied to non-selected pattern spaces by use
 157 of the exclamation character
 158 .Pq Dq \&!
 159 function.
 160 .Sh SED REGULAR EXPRESSIONS
 161 The
 162 .Nm
 163 regular expressions are basic regular expressions (BRE's, see
 164 .Xr re_format 7
 165 for more information).
 166 In addition,
 167 .Nm
 168 has the following two additions to BRE's:
 169 .sp
 170 .Bl -enum -compact
 171 .It
 172 In a context address, any character other than a backslash
 173 .Po
 174 .Dq \e
 175 .Pc
 176 or newline character may be used to delimit the regular expression
 177 by prefixing the first use of that delimiter with a backslash.
 178 Also, putting a backslash character before the delimiting character
 179 causes the character to be treated literally.
 180 For example, in the context address \exabc\exdefx, the RE delimiter
 181 is an
 182 .Dq x
 183 and the second
 184 .Dq x
 185 stands for itself, so that the regular expression is
 186 .Dq abcxdef .
 187 .sp
 188 .It
 189 The escape sequence \en matches a newline character embedded in the
 190 pattern space.
 191 You can't, however, use a literal newline character in an address or
 192 in the substitute command.
 193 .El
 194 .Pp
 195 One special feature of
 196 .Nm
 197 regular expressions is that they can default to the last regular
 198 expression used.
 199 If a regular expression is empty, i.e. just the delimiter characters
 200 are specified, the last regular expression encountered is used instead.
 201 The last regular expression is defined as the last regular expression
 202 used as part of an address or substitute command, and at run-time, not
 203 compile-time.
 204 For example, the command
 205 .Dq /abc/s//XXX/
 206 will substitute
 207 .Dq XXX
 208 for the pattern
 209 .Dq abc .
 210 .Sh SED FUNCTIONS
 211 In the following list of commands, the maximum number of permissible
 212 addresses for each command is indicated by [0addr], [1addr], or [2addr],
 213 representing zero, one, or two addresses.
 214 .Pp
 215 The argument
 216 .Em text
 217 consists of one or more lines.
 218 To embed a newline in the text, precede it with a backslash.
 219 Other backslashes in text are deleted and the following character
 220 taken literally.
 221 .Pp
 222 The
 223 .Dq r
 224 and
 225 .Dq w
 226 functions take an optional file parameter, which should be separated
 227 from the function letter by white space.
 228 Each file given as an argument to
 229 .Nm
 230 is created (or its contents truncated) before any input processing begins.
 231 .Pp
 232 The
 233 .Dq b ,
 234 .Dq r ,
 235 .Dq s ,
 236 .Dq t ,
 237 .Dq w ,
 238 .Dq y ,
 239 .Dq \&! ,
 240 and
 241 .Dq \&:
 242 functions all accept additional arguments.
 243 The following synopses indicate which arguments have to be separated from
 244 the function letters by white space characters.
 245 .Pp
 246 Two of the functions take a function-list.
 247 This is a list of
 248 .Nm
 249 functions separated by newlines, as follows:
 250 .Bd -literal -offset indent
 251 { function
 252   function
 253   ...
 254   function
 255 }
 256 .Ed
 257 .Pp
 258 The
 259 .Dq {
 260 can be preceded by white space and can be followed by white space.
 261 The function can be preceded by white space.
 262 The terminating
 263 .Dq }
 264 must be preceded by a newline (and optionally white space).
 265 .sp
 266 .Bl -tag -width "XXXXXX" -compact
 267 .It [2addr] function-list
 268 Execute function-list only when the pattern space is selected.
 269 .sp
 270 .It [1addr]a\e
 271 .It text
 272 .br
 273 Write
 274 .Em text
 275 to standard output immediately before each attempt to read a line of input,
 276 whether by executing the
 277 .Dq N
 278 function or by beginning a new cycle.
 279 .sp
 280 .It [2addr]b[label]
 281 Branch to the
 282 .Dq \&:
 283 function with the specified label.
 284 If the label is not specified, branch to the end of the script.
 285 .sp
 286 .It [2addr]c\e
 287 .It text
 288 .br
 289 Delete the pattern space.
 290 With 0 or 1 address or at the end of a 2-address range,
 291 .Em text
 292 is written to the standard output.
 293 .sp
 294 .It [2addr]d
 295 Delete the pattern space and start the next cycle.
 296 .sp
 297 .It [2addr]D
 298 Delete the initial segment of the pattern space through the first
 299 newline character and start the next cycle.
 300 .sp
 301 .It [2addr]g
 302 Replace the contents of the pattern space with the contents of the
 303 hold space.
 304 .sp
 305 .It [2addr]G
 306 Append a newline character followed by the contents of the hold space
 307 to the pattern space.
 308 .sp
 309 .It [2addr]h
 310 Replace the contents of the hold space with the contents of the
 311 pattern space.
 312 .sp
 313 .It [2addr]H
 314 Append a newline character followed by the contents of the pattern space
 315 to the hold space.
 316 .sp
 317 .It [1addr]i\e
 318 .It text
 319 .br
 320 Write
 321 .Em text
 322 to the standard output.
 323 .sp
 324 .It [2addr]l
 325 (The letter ell.)
 326 Write the pattern space to the standard output in a visually unambiguous
 327 form.
 328 This 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
 347 Nonprintable characters are written as three-digit octal numbers (with a
 348 preceding backslash) for each byte in the character (most significant byte
 349 first).
 350 Long lines are folded, with the point of folding indicated by displaying
 351 a backslash followed by a newline.
 352 The end of each line is marked with a
 353 .Dq $ .
 354 .sp
 355 .It [2addr]n
 356 Write the pattern space to the standard output if the default output has
 357 not been suppressed, and replace the pattern space with the next line of
 358 input. (Does not begin a new cycle.)
 359 .sp
 360 .It [2addr]N
 361 Append the next line of input to the pattern space, using an embedded
 362 newline character to separate the appended material from the original
 363 contents.
 364 Note that the current line number changes.
 365 .sp
 366 .It [2addr]p
 367 Write the pattern space to standard output.
 368 .sp
 369 .It [2addr]P
 370 Write the pattern space, up to the first newline character to the
 371 standard output.
 372 .sp
 373 .It [1addr]q
 374 Branch to the end of the script and quit without starting a new cycle.
 375 .sp
 376 .It [1addr]r file
 377 Copy the contents of
 378 .Em file
 379 to the standard output immediately before the next attempt to read a
 380 line of input.
 381 If
 382 .Em file
 383 cannot be read for any reason, it is silently ignored and no error
 384 condition is set.
 385 .sp
 386 .It [2addr]s/regular expression/replacement/flags
 387 Substitute the replacement string for the first instance of the regular
 388 expression in the pattern space.
 389 Any character other than backslash or newline can be used instead of
 390 a slash to delimit the RE and the replacement.
 391 Within the RE and the replacement, the RE delimiter itself can be used as
 392 a literal character if it is preceded by a backslash.
 393 .Pp
 394 An ampersand
 395 .Po
 396 .Dq \*[Am]
 397 .Pc
 398 appearing in the replacement is replaced by the string matching the RE.
 399 The special meaning of
 400 .Dq \*[Am]
 401 in this context can be suppressed by preceding it by a backslash.
 402 The string
 403 .Dq \e# ,
 404 where
 405 .Dq #
 406 is a digit, is replaced by the text matched
 407 by the corresponding backreference expression (see
 408 .Xr re_format 7 ) .
 409 .Pp
 410 A line can be split by substituting a newline character into it.
 411 To specify a newline character in the replacement string, precede it with
 412 a backslash.
 413 .Pp
 414 The value of
 415 .Em flags
 416 in the substitute function is zero or more of the following:
 417 .Bl -tag -width "XXXXXX" -offset indent
 418 .It "0 ... 9"
 419 Make the substitution only for the N'th occurrence of the regular
 420 expression in the pattern space.
 421 .It g
 422 Make the substitution for all non-overlapping matches of the
 423 regular expression, not just the first one.
 424 .It p
 425 Write the pattern space to standard output if a replacement was made.
 426 If the replacement string is identical to that which it replaces, it
 427 is still considered to have been a replacement.
 428 .It w Em file
 429 Append the pattern space to
 430 .Em file
 431 if a replacement was made.
 432 If the replacement string is identical to that which it replaces, it
 433 is still considered to have been a replacement.
 434 .El
 435 .sp
 436 .It [2addr]t [label]
 437 Branch to the
 438 .Dq \&:
 439 function bearing the label if any substitutions have been made since the
 440 most recent reading of an input line or execution of a
 441 .Dq t
 442 function.
 443 If no label is specified, branch to the end of the script.
 444 .sp
 445 .It [2addr]w Em file
 446 Append the pattern space to the
 447 .Em file .
 448 .sp
 449 .It [2addr]x
 450 Swap the contents of the pattern and hold spaces.
 451 .sp
 452 .It [2addr]y/string1/string2/
 453 Replace all occurrences of characters in
 454 .Em string1
 455 in the pattern space with the corresponding characters from
 456 .Em string2 .
 457 Any character other than a backslash or newline can be used instead of
 458 a slash to delimit the strings.
 459 Within
 460 .Em string1
 461 and
 462 .Em string2 ,
 463 a backslash followed by any character other than a newline is that literal
 464 character, and a backslash followed by an ``n'' is replaced by a newline
 465 character.
 466 .sp
 467 .It [2addr]!function
 468 .It [2addr]!function-list
 469 Apply the function or function-list only to the lines that are
 470 .Em not
 471 selected by the address(es).
 472 .sp
 473 .It [0addr]:label
 474 This function does nothing; it bears a label to which the
 475 .Dq b
 476 and
 477 .Dq t
 478 commands may branch.
 479 .sp
 480 .It [1addr]=
 481 Write the line number to the standard output followed by a newline
 482 character.
 483 .sp
 484 .It [0addr]
 485 Empty lines are ignored.
 486 .sp
 487 .It [0addr]#
 488 The
 489 .Dq #
 490 and the remainder of the line are ignored (treated as a comment), with
 491 the single exception that if the first two characters in the file are
 492 .Dq #n ,
 493 the default output is suppressed.
 494 This is the same as specifying the
 495 .Fl n
 496 option on the command line.
 497 .El
 498 .Pp
 499 The
 500 .Nm
 501 utility 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
 509 The
 510 .Nm
 511 function is expected to be a superset of the
 512 .St -p1003.2
 513 specification.
 514 .Sh HISTORY
 515 A
 516 .Nm
 517 command appeared in
 518 .At v7 .