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