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