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