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