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