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