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