usr.bin/sed/sed.1

   1 .\"     $NetBSD: sed.1,v 1.32 2013/05/29 15:05:43 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 May 29, 2013
  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, with nothing between the delimiter
 200 characters, 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 Start the next cycle.
 294 .sp
 295 .It [2addr]d
 296 Delete the pattern space and start the next cycle.
 297 .sp
 298 .It [2addr]D
 299 Delete the initial segment of the pattern space through the first
 300 newline character and start the next cycle.
 301 .sp
 302 .It [2addr]g
 303 Replace the contents of the pattern space with the contents of the
 304 hold space.
 305 .sp
 306 .It [2addr]G
 307 Append a newline character followed by the contents of the hold space
 308 to the pattern space.
 309 .sp
 310 .It [2addr]h
 311 Replace the contents of the hold space with the contents of the
 312 pattern space.
 313 .sp
 314 .It [2addr]H
 315 Append a newline character followed by the contents of the pattern space
 316 to the hold space.
 317 .sp
 318 .It [1addr]i\e
 319 .It text
 320 .br
 321 Write
 322 .Em text
 323 to the standard output.
 324 .sp
 325 .It [2addr]l
 326 (The letter ell.)
 327 Write the pattern space to the standard output in a visually unambiguous
 328 form.
 329 This form is as follows:
 330 .sp
 331 .Bl -tag -width "carriage-returnXX" -offset indent -compact
 332 .It backslash
 333 \e\e
 334 .It alert
 335 \ea
 336 .It form-feed
 337 \ef
 338 .It newline
 339 \en
 340 .It carriage-return
 341 \er
 342 .It tab
 343 \et
 344 .It vertical tab
 345 \ev
 346 .El
 347 .Pp
 348 Nonprintable characters are written as three-digit octal numbers (with a
 349 preceding backslash) for each byte in the character (most significant byte
 350 first).
 351 Long lines are folded, with the point of folding indicated by displaying
 352 a backslash followed by a newline.
 353 The end of each line is marked with a
 354 .Dq $ .
 355 .sp
 356 .It [2addr]n
 357 Write the pattern space to the standard output if the default output has
 358 not been suppressed, and replace the pattern space with the next line of
 359 input. (Does not begin a new cycle.)
 360 .sp
 361 .It [2addr]N
 362 Append the next line of input to the pattern space, using an embedded
 363 newline character to separate the appended material from the original
 364 contents.
 365 Note that the current line number changes.
 366 .sp
 367 .It [2addr]p
 368 Write the pattern space to standard output.
 369 .sp
 370 .It [2addr]P
 371 Write the pattern space, up to the first newline character to the
 372 standard output.
 373 .sp
 374 .It [1addr]q
 375 Branch to the end of the script and quit without starting a new cycle.
 376 .sp
 377 .It [1addr]r file
 378 Copy the contents of
 379 .Em file
 380 to the standard output immediately before the next attempt to read a
 381 line of input.
 382 If
 383 .Em file
 384 cannot be read for any reason, it is silently ignored and no error
 385 condition is set.
 386 .sp
 387 .It [2addr]s/regular expression/replacement/flags
 388 Substitute the replacement string for the first instance of the regular
 389 expression in the pattern space.
 390 Any character other than backslash or newline can be used instead of
 391 a slash to delimit the RE and the replacement.
 392 Within the RE and the replacement, the RE delimiter itself can be used as
 393 a literal character if it is preceded by a backslash.
 394 .Pp
 395 An ampersand
 396 .Po
 397 .Dq \*[Am]
 398 .Pc
 399 appearing in the replacement is replaced by the string matching the RE.
 400 The special meaning of
 401 .Dq \*[Am]
 402 in this context can be suppressed by preceding it by a backslash.
 403 The string
 404 .Dq \e# ,
 405 where
 406 .Dq #
 407 is a digit, is replaced by the text matched
 408 by the corresponding backreference expression (see
 409 .Xr re_format 7 ) .
 410 .Pp
 411 A line can be split by substituting a newline character into it.
 412 To specify a newline character in the replacement string, precede it with
 413 a backslash.
 414 .Pp
 415 The value of
 416 .Em flags
 417 in the substitute function is zero or more of the following:
 418 .Bl -tag -width "XXXXXX" -offset indent
 419 .It "0 ... 9"
 420 Make the substitution only for the N'th occurrence of the regular
 421 expression in the pattern space.
 422 .It g
 423 Make the substitution for all non-overlapping matches of the
 424 regular expression, not just the first one.
 425 .It p
 426 Write the pattern space to standard output if a replacement was made.
 427 If the replacement string is identical to that which it replaces, it
 428 is still considered to have been a replacement.
 429 .It w Em file
 430 Append the pattern space to
 431 .Em file
 432 if a replacement was made.
 433 If the replacement string is identical to that which it replaces, it
 434 is still considered to have been a replacement.
 435 .El
 436 .sp
 437 .It [2addr]t [label]
 438 Branch to the
 439 .Dq \&:
 440 function bearing the label if any substitutions have been made since the
 441 most recent reading of an input line or execution of a
 442 .Dq t
 443 function.
 444 If no label is specified, branch to the end of the script.
 445 .sp
 446 .It [2addr]w Em file
 447 Append the pattern space to the
 448 .Em file .
 449 .sp
 450 .It [2addr]x
 451 Swap the contents of the pattern and hold spaces.
 452 .sp
 453 .It [2addr]y/string1/string2/
 454 Replace all occurrences of characters in
 455 .Em string1
 456 in the pattern space with the corresponding characters from
 457 .Em string2 .
 458 Any character other than a backslash or newline can be used instead of
 459 a slash to delimit the strings.
 460 Within
 461 .Em string1
 462 and
 463 .Em string2 ,
 464 a backslash followed by any character other than a newline is that literal
 465 character, and a backslash followed by an ``n'' is replaced by a newline
 466 character.
 467 .sp
 468 .It [2addr]!function
 469 .It [2addr]!function-list
 470 Apply the function or function-list only to the lines that are
 471 .Em not
 472 selected by the address(es).
 473 .sp
 474 .It [0addr]:label
 475 This function does nothing; it bears a label to which the
 476 .Dq b
 477 and
 478 .Dq t
 479 commands may branch.
 480 .sp
 481 .It [1addr]=
 482 Write the line number to the standard output followed by a newline
 483 character.
 484 .sp
 485 .It [0addr]
 486 Empty lines are ignored.
 487 .sp
 488 .It [0addr]#
 489 The
 490 .Dq #
 491 and the remainder of the line are ignored (treated as a comment), with
 492 the single exception that if the first two characters in the file are
 493 .Dq #n ,
 494 the default output is suppressed.
 495 This is the same as specifying the
 496 .Fl n
 497 option on the command line.
 498 .El
 499 .Pp
 500 The
 501 .Nm
 502 utility exits 0 on success and \*[Gt]0 if an error occurs.
 503 .Sh SEE ALSO
 504 .Xr awk 1 ,
 505 .Xr ed 1 ,
 506 .Xr grep 1 ,
 507 .Xr tr 1 ,
 508 .Xr regex 3 ,
 509 .Xr re_format 7
 510 .Sh STANDARDS
 511 The
 512 .Nm
 513 function is expected to be a superset of the
 514 .St -p1003.2
 515 specification.
 516 .Sh HISTORY
 517 A
 518 .Nm
 519 command appeared in
 520 .At v7 .