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