Annotation of src/usr.bin/sed/sed.1, Revision 1.33
1.33 ! djm 1: .\" $OpenBSD: sed.1,v 1.32 2009/02/08 17:15:10 jmc Exp $
1.12 aaron 2: .\"
1.1 deraadt 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.
1.17 millert 17: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 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: .\" from: @(#)sed.1 8.2 (Berkeley) 12/30/93
34: .\"
1.33 ! djm 35: .Dd $Mdocdate: February 8 2009 $
1.1 deraadt 36: .Dt SED 1
37: .Os
38: .Sh NAME
39: .Nm sed
40: .Nd stream editor
41: .Sh SYNOPSIS
42: .Nm sed
1.33 ! djm 43: .Op Fl Eanru
1.1 deraadt 44: .Ar command
1.29 sobrado 45: .Op Ar
1.1 deraadt 46: .Nm sed
1.33 ! djm 47: .Op Fl aEnru
1.1 deraadt 48: .Op Fl e Ar command
49: .Op Fl f Ar command_file
1.29 sobrado 50: .Op Ar
1.1 deraadt 51: .Sh DESCRIPTION
52: The
1.8 aaron 53: .Nm
1.1 deraadt 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 sed .
1.25 jmc 60: Multiple commands may be specified
61: separated by newlines or semicolons,
62: or by using the
1.1 deraadt 63: .Fl e
64: or
65: .Fl f
66: options.
67: All commands are applied to the input in the order they are specified
68: regardless of their origin.
69: .Pp
1.10 aaron 70: The options are as follows:
1.16 aaron 71: .Bl -tag -width Ds
1.33 ! djm 72: .It Fl E
! 73: Interpret regular expressions using the POSIX extended regular expression
! 74: syntax (documented in
! 75: .Xr re_format 7 ).
! 76: The default behaviour is to use the POSIX basic regular expression syntax.
1.1 deraadt 77: .It Fl a
78: The files listed as parameters for the
1.8 aaron 79: .Ql w
1.1 deraadt 80: functions are created (or truncated) before any processing begins,
81: by default.
82: The
83: .Fl a
84: option causes
1.8 aaron 85: .Nm
1.1 deraadt 86: to delay opening each file until a command containing the related
1.8 aaron 87: .Ql w
1.1 deraadt 88: function is applied to a line of input.
89: .It Fl e Ar command
90: Append the editing commands specified by the
91: .Ar command
92: argument
93: to the list of commands.
94: .It Fl f Ar command_file
95: Append the editing commands found in the file
96: .Ar command_file
97: to the list of commands.
98: The editing commands should each be listed on a separate line.
1.33 ! djm 99: .It Fl r
! 100: is an alias for
! 101: .Fl E
! 102: (enable POSIX extended regular exressions) for compatibility with GNU sed.
1.1 deraadt 103: .It Fl n
104: By default, each line of input is echoed to the standard output after
105: all of the commands have been applied to it.
106: The
107: .Fl n
108: option suppresses this behavior.
1.26 ray 109: .It Fl u
110: Force output to be line buffered,
111: printing each line as it becomes available.
112: By default, output is line buffered when standard output is a terminal
113: and block buffered otherwise.
114: See
115: .Xr setbuf 3
116: for a more detailed explanation.
1.1 deraadt 117: .El
118: .Pp
119: The form of a
1.8 aaron 120: .Nm
1.1 deraadt 121: command is as follows:
1.21 jmc 122: .Pp
1.1 deraadt 123: .Dl [address[,address]]function[arguments]
1.21 jmc 124: .Pp
1.1 deraadt 125: Whitespace may be inserted before the first address and the function
126: portions of the command.
127: .Pp
128: Normally,
1.8 aaron 129: .Nm
1.1 deraadt 130: cyclically copies a line of input, not including its terminating newline
131: character, into a
1.21 jmc 132: .Em pattern space ,
1.1 deraadt 133: (unless there is something left after a
1.8 aaron 134: .Sq D
1.1 deraadt 135: function),
136: applies all of the commands with addresses that select that pattern space,
137: copies the pattern space to the standard output, appending a newline, and
138: deletes the pattern space.
139: .Pp
140: Some of the functions use a
1.21 jmc 141: .Em hold space
1.1 deraadt 142: to save all or part of the pattern space for subsequent retrieval.
1.21 jmc 143: .Sh SED ADDRESSES
1.1 deraadt 144: An address is not required, but if specified must be a number (that counts
145: input lines
1.21 jmc 146: cumulatively across input files), a dollar character
1.8 aaron 147: .Pq Ql $
1.21 jmc 148: that addresses the last line of input, or a context address
1.1 deraadt 149: (which consists of a regular expression preceded and followed by a
150: delimiter).
151: .Pp
152: A command line with no addresses selects every pattern space.
153: .Pp
154: A command line with one address selects all of the pattern spaces
155: that match the address.
156: .Pp
157: A command line with two addresses selects the inclusive range from
158: the first pattern space that matches the first address through the next
159: pattern space that matches the second.
160: (If the second address is a number less than or equal to the line number
161: first selected, only that line is selected.)
162: Starting at the first line following the selected range,
1.8 aaron 163: .Nm
1.1 deraadt 164: starts looking again for the first address.
165: .Pp
166: Editing commands can be applied to non-selected pattern spaces by use
167: of the exclamation character
1.18 jmc 168: .Pq Ql \&!
1.1 deraadt 169: function.
1.21 jmc 170: .Sh SED REGULAR EXPRESSIONS
1.1 deraadt 171: The
1.8 aaron 172: .Nm
1.23 jmc 173: regular expressions are basic regular expressions
174: .Pq BREs .
175: See
1.19 jmc 176: .Xr re_format 7
1.23 jmc 177: for more information on regular expressions.
1.1 deraadt 178: In addition,
1.8 aaron 179: .Nm
1.23 jmc 180: has the following two additions to BREs:
1.21 jmc 181: .Pp
1.1 deraadt 182: .Bl -enum -compact
183: .It
184: In a context address, any character other than a backslash
1.8 aaron 185: .Pq Ql \e
1.1 deraadt 186: or newline character may be used to delimit the regular expression.
1.30 jmc 187: The opening delimiter should be preceded by a backslash
188: unless it is a slash.
189: Putting a backslash character before the delimiting character
1.1 deraadt 190: causes the character to be treated literally.
191: For example, in the context address \exabc\exdefx, the RE delimiter
192: is an
1.8 aaron 193: .Sq x
1.1 deraadt 194: and the second
1.8 aaron 195: .Sq x
1.1 deraadt 196: stands for itself, so that the regular expression is
197: .Dq abcxdef .
1.21 jmc 198: .Pp
1.1 deraadt 199: .It
200: The escape sequence \en matches a newline character embedded in the
201: pattern space.
202: You can't, however, use a literal newline character in an address or
203: in the substitute command.
204: .El
205: .Pp
206: One special feature of
1.8 aaron 207: .Nm
1.1 deraadt 208: regular expressions is that they can default to the last regular
209: expression used.
1.13 aaron 210: If a regular expression is empty, i.e., just the delimiter characters
1.1 deraadt 211: are specified, the last regular expression encountered is used instead.
212: The last regular expression is defined as the last regular expression
213: used as part of an address or substitute command, and at run-time, not
214: compile-time.
215: For example, the command
216: .Dq /abc/s//XXX/
217: will substitute
218: .Dq XXX
219: for the pattern
220: .Dq abc .
1.21 jmc 221: .Sh SED FUNCTIONS
1.1 deraadt 222: In the following list of commands, the maximum number of permissible
223: addresses for each command is indicated by [0addr], [1addr], or [2addr],
224: representing zero, one, or two addresses.
225: .Pp
226: The argument
227: .Em text
228: consists of one or more lines.
229: To embed a newline in the text, precede it with a backslash.
230: Other backslashes in text are deleted and the following character
231: taken literally.
232: .Pp
233: The
1.8 aaron 234: .Sq r
1.1 deraadt 235: and
1.8 aaron 236: .Sq w
1.1 deraadt 237: functions take an optional file parameter, which should be separated
1.9 aaron 238: from the function letter by whitespace.
1.1 deraadt 239: Each file given as an argument to
1.8 aaron 240: .Nm
1.1 deraadt 241: is created (or its contents truncated) before any input processing begins.
242: .Pp
243: The
1.8 aaron 244: .Sq b ,
245: .Sq r ,
246: .Sq s ,
247: .Sq t ,
248: .Sq w ,
249: .Sq y ,
1.18 jmc 250: .Ql \&! ,
1.1 deraadt 251: and
1.8 aaron 252: .Ql \&:
1.1 deraadt 253: functions all accept additional arguments.
254: The following synopses indicate which arguments have to be separated from
1.9 aaron 255: the function letters by whitespace characters.
1.1 deraadt 256: .Pp
257: Two of the functions take a function-list.
258: This is a list of
1.8 aaron 259: .Nm
1.1 deraadt 260: functions separated by newlines, as follows:
261: .Bd -literal -offset indent
262: { function
263: function
264: ...
265: function
266: }
267: .Ed
268: .Pp
269: The
1.8 aaron 270: .Ql {
1.9 aaron 271: can be preceded or followed by whitespace.
272: The function can be preceded by whitespace as well.
1.1 deraadt 273: The terminating
1.8 aaron 274: .Ql }
1.9 aaron 275: must be preceded by a newline or optional whitespace.
1.21 jmc 276: .Pp
277: .Bl -tag -width "XXXXXXXX" -compact
1.15 aaron 278: .It [2addr] Em function-list
279: Execute
280: .Em function-list
281: only when the pattern space is selected.
1.21 jmc 282: .Pp
1.20 jmc 283: .It [1addr] Ns Em a Ns \e
1.15 aaron 284: .It Em text
1.21 jmc 285: .Pp
1.1 deraadt 286: Write
287: .Em text
288: to standard output immediately before each attempt to read a line of input,
289: whether by executing the
1.8 aaron 290: .Sq N
1.1 deraadt 291: function or by beginning a new cycle.
1.21 jmc 292: .Pp
1.20 jmc 293: .It [2addr] Ns Em b Ns [label]
1.1 deraadt 294: Branch to the
1.8 aaron 295: .Sq \&:
1.1 deraadt 296: function with the specified label.
297: If the label is not specified, branch to the end of the script.
1.21 jmc 298: .Pp
1.20 jmc 299: .It [2addr] Ns Em c Ns \e
1.15 aaron 300: .It Em text
1.21 jmc 301: .Pp
1.1 deraadt 302: Delete the pattern space.
303: With 0 or 1 address or at the end of a 2-address range,
304: .Em text
305: is written to the standard output.
1.21 jmc 306: .Pp
1.15 aaron 307: .It [2addr] Ns Em d
1.1 deraadt 308: Delete the pattern space and start the next cycle.
1.21 jmc 309: .Pp
1.15 aaron 310: .It [2addr] Ns Em D
1.1 deraadt 311: Delete the initial segment of the pattern space through the first
312: newline character and start the next cycle.
1.21 jmc 313: .Pp
1.15 aaron 314: .It [2addr] Ns Em g
1.1 deraadt 315: Replace the contents of the pattern space with the contents of the
316: hold space.
1.21 jmc 317: .Pp
1.15 aaron 318: .It [2addr] Ns Em G
1.1 deraadt 319: Append a newline character followed by the contents of the hold space
320: to the pattern space.
1.21 jmc 321: .Pp
1.15 aaron 322: .It [2addr] Ns Em h
1.1 deraadt 323: Replace the contents of the hold space with the contents of the
324: pattern space.
1.21 jmc 325: .Pp
1.15 aaron 326: .It [2addr] Ns Em H
1.1 deraadt 327: Append a newline character followed by the contents of the pattern space
328: to the hold space.
1.21 jmc 329: .Pp
1.20 jmc 330: .It [1addr] Ns Em i Ns \e
1.15 aaron 331: .It Em text
1.21 jmc 332: .Pp
1.1 deraadt 333: Write
334: .Em text
335: to the standard output.
1.21 jmc 336: .Pp
1.15 aaron 337: .It [2addr] Ns Em l
1.1 deraadt 338: (The letter ell.)
339: Write the pattern space to the standard output in a visually unambiguous
340: form.
341: This form is as follows:
1.21 jmc 342: .Pp
1.1 deraadt 343: .Bl -tag -width "carriage-returnXX" -offset indent -compact
344: .It backslash
1.3 deraadt 345: \e\e
1.1 deraadt 346: .It alert
347: \ea
1.31 millert 348: .It backspace
349: \eb
1.1 deraadt 350: .It form-feed
351: \ef
352: .It carriage-return
353: \er
354: .It tab
355: \et
356: .It vertical tab
357: \ev
358: .El
359: .Pp
1.15 aaron 360: Non-printable characters are written as three-digit octal numbers (with a
1.1 deraadt 361: preceding backslash) for each byte in the character (most significant byte
362: first).
363: Long lines are folded, with the point of folding indicated by displaying
364: a backslash followed by a newline.
365: The end of each line is marked with a
1.8 aaron 366: .Ql $ .
1.21 jmc 367: .Pp
1.15 aaron 368: .It [2addr] Ns Em n
1.1 deraadt 369: Write the pattern space to the standard output if the default output has
370: not been suppressed, and replace the pattern space with the next line of
371: input.
1.21 jmc 372: .Pp
1.15 aaron 373: .It [2addr] Ns Em N
1.1 deraadt 374: Append the next line of input to the pattern space, using an embedded
375: newline character to separate the appended material from the original
376: contents.
377: Note that the current line number changes.
1.21 jmc 378: .Pp
1.15 aaron 379: .It [2addr] Ns Em p
1.1 deraadt 380: Write the pattern space to standard output.
1.21 jmc 381: .Pp
1.15 aaron 382: .It [2addr] Ns Em P
1.1 deraadt 383: Write the pattern space, up to the first newline character to the
384: standard output.
1.21 jmc 385: .Pp
1.15 aaron 386: .It [1addr] Ns Em q
1.1 deraadt 387: Branch to the end of the script and quit without starting a new cycle.
1.21 jmc 388: .Pp
1.15 aaron 389: .It [1addr] Ns Em r file
1.1 deraadt 390: Copy the contents of
391: .Em file
392: to the standard output immediately before the next attempt to read a
393: line of input.
394: If
395: .Em file
396: cannot be read for any reason, it is silently ignored and no error
397: condition is set.
1.21 jmc 398: .Pp
1.20 jmc 399: .It [2addr] Ns Em s Ns /re/replacement/flags
1.1 deraadt 400: Substitute the replacement string for the first instance of the regular
401: expression in the pattern space.
402: Any character other than backslash or newline can be used instead of
403: a slash to delimit the RE and the replacement.
404: Within the RE and the replacement, the RE delimiter itself can be used as
405: a literal character if it is preceded by a backslash.
406: .Pp
407: An ampersand
1.8 aaron 408: .Pq Ql &
1.1 deraadt 409: appearing in the replacement is replaced by the string matching the RE.
410: The special meaning of
1.8 aaron 411: .Ql &
1.1 deraadt 412: in this context can be suppressed by preceding it by a backslash.
413: The string
1.8 aaron 414: .Ql \e# ,
1.1 deraadt 415: where
1.8 aaron 416: .Ql #
1.1 deraadt 417: is a digit, is replaced by the text matched
418: by the corresponding backreference expression (see
1.14 aaron 419: .Xr re_format 7 ) .
1.1 deraadt 420: .Pp
421: A line can be split by substituting a newline character into it.
422: To specify a newline character in the replacement string, precede it with
423: a backslash.
424: .Pp
425: The value of
426: .Em flags
427: in the substitute function is zero or more of the following:
428: .Bl -tag -width "XXXXXX" -offset indent
1.21 jmc 429: .It 0 ... 9
1.1 deraadt 430: Make the substitution only for the N'th occurrence of the regular
431: expression in the pattern space.
432: .It g
433: Make the substitution for all non-overlapping matches of the
434: regular expression, not just the first one.
435: .It p
436: Write the pattern space to standard output if a replacement was made.
437: If the replacement string is identical to that which it replaces, it
438: is still considered to have been a replacement.
439: .It w Em file
440: Append the pattern space to
441: .Em file
442: if a replacement was made.
443: If the replacement string is identical to that which it replaces, it
444: is still considered to have been a replacement.
445: .El
1.21 jmc 446: .Pp
1.20 jmc 447: .It [2addr] Ns Em t Ns [label]
1.1 deraadt 448: Branch to the
1.8 aaron 449: .Ql \&:
1.1 deraadt 450: function bearing the label if any substitutions have been made since the
451: most recent reading of an input line or execution of a
1.8 aaron 452: .Sq t
1.1 deraadt 453: function.
454: If no label is specified, branch to the end of the script.
1.21 jmc 455: .Pp
1.15 aaron 456: .It [2addr] Ns Em w file
1.1 deraadt 457: Append the pattern space to the
458: .Em file .
1.21 jmc 459: .Pp
1.15 aaron 460: .It [2addr] Ns Em x
1.1 deraadt 461: Swap the contents of the pattern and hold spaces.
1.21 jmc 462: .Pp
1.20 jmc 463: .It [2addr] Ns Em y Ns /string1/string2/
1.1 deraadt 464: Replace all occurrences of characters in
465: .Em string1
466: in the pattern space with the corresponding characters from
467: .Em string2 .
468: Any character other than a backslash or newline can be used instead of
469: a slash to delimit the strings.
470: Within
471: .Em string1
472: and
473: .Em string2 ,
474: a backslash followed by any character other than a newline is that literal
1.8 aaron 475: character, and a backslash followed by an
476: .Sq n
477: is replaced by a newline character.
1.21 jmc 478: .Pp
1.15 aaron 479: .Sm off
1.21 jmc 480: .It Xo [2addr] Em !function No ,\ \&[2addr]
1.15 aaron 481: .Em !function-list
482: .Xc
483: .Sm on
1.1 deraadt 484: Apply the function or function-list only to the lines that are
485: .Em not
486: selected by the address(es).
1.21 jmc 487: .Pp
488: .It [0addr] Ns Em \&: Ns label
1.1 deraadt 489: This function does nothing; it bears a label to which the
1.8 aaron 490: .Sq b
1.1 deraadt 491: and
1.8 aaron 492: .Sq t
1.1 deraadt 493: commands may branch.
1.21 jmc 494: .Pp
1.15 aaron 495: .It [1addr] Ns Em =
496: Write the line number to the standard output followed by a newline character.
1.21 jmc 497: .Pp
1.1 deraadt 498: .It [0addr]
499: Empty lines are ignored.
1.21 jmc 500: .Pp
1.15 aaron 501: .It [0addr] Ns Em #
1.1 deraadt 502: The
1.8 aaron 503: .Ql #
1.1 deraadt 504: and the remainder of the line are ignored (treated as a comment), with
505: the single exception that if the first two characters in the file are
1.8 aaron 506: .Ql #n ,
1.1 deraadt 507: the default output is suppressed.
508: This is the same as specifying the
509: .Fl n
510: option on the command line.
511: .El
512: .Pp
1.24 jmc 513: .Ex -std sed
1.1 deraadt 514: .Sh SEE ALSO
515: .Xr awk 1 ,
516: .Xr ed 1 ,
517: .Xr grep 1 ,
518: .Xr regex 3 ,
1.26 ray 519: .Xr setbuf 3 ,
1.1 deraadt 520: .Xr re_format 7
1.21 jmc 521: .Pp
1.22 jmc 522: "SED \(em A Non-interactive Text Editor",
523: .Pa /usr/share/doc/usd/15.sed/ .
1.1 deraadt 524: .Sh STANDARDS
525: The
1.8 aaron 526: .Nm
1.25 jmc 527: utility is compliant with the
1.32 jmc 528: .St -p1003.1-2008
1.1 deraadt 529: specification.
1.25 jmc 530: .Pp
1.26 ray 531: The flags
1.33 ! djm 532: .Op Fl aEru
1.27 jmc 533: are extensions to that specification.
1.25 jmc 534: .Pp
535: The use of newlines to separate multiple commands on the command line
536: is non-portable;
537: the use of newlines to separate multiple commands within a command file
538: .Pq Fl f Ar command_file
539: is portable.
1.11 aaron 540: .Sh HISTORY
541: A
542: .Nm
543: command appeared in
544: .At v7 .
1.25 jmc 545: .Sh CAVEATS
546: The use of semicolons to separate multiple commands
547: is not permitted for the following commands:
548: .Cm a , b , c ,
549: .Cm i , r , t ,
550: .Cm w , \&: ,
551: and
552: .Cm # .
![[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