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