| blob | 137af30fcbabb1fbaff11a6db3d85479dc2e6974 |
1 .TH sed 1 "March 30, 2006"
2 .SH NAME
3 sed \- the stream editor
4 .SH SYNOPSIS
5 sed [-n] [-g] [-e script ] [-f sfile ] [ file ] ...
6 .SH DESCRIPTION
7 Sed copies the named files (standard input default) to the standard
8 output, edited according to a script of commands.
9 .P
10 An -e option supplies a single edit command from the next argument;
11 if there are several of these they are executed in the order in which
12 they appear. If there is just one -e option and no -f 's, the -e flag
13 may be omitted.
14 .P
15 An -f option causes commands to be taken from the file "sfile"; if
16 there are several of these they are executed in the order in which
17 they appear; -e and -f commands may be mixed.
18 .P
19 The -g option causes sed to act as though every substitute command
20 in the script has a g suffix.
21 .P
22 The -n option suppresses the default output.
23 .P
24 A script consists of commands, one per line, of the following form:
26 [address [, address] ] function [arguments]
28 Normally sed cyclically copies a line of input into a current text
29 buffer, then applies all commands whose addresses select the buffer in
30 sequence, then copies the buffer to standard output and clears it.
31 .P
32 The -n option suppresses normal output (so that only p and w output
33 is done). Also, some commands (n, N) do their own line reads, and some
34 others (d, D) cause all commands following in the script to be skipped
35 (the D command also suppresses the clearing of the current text buffer
36 that would normally occur before the next cycle).
37 .P
38 It is also helpful to know that there's a second buffer (called the `hold
39 space' that can be copied or appended to or from or swapped with
40 the current text buffer.
41 .P
42 An address is: a decimal numeral (which matches the line it numbers where line
43 numbers start at 1 and run cumulatively across files), or a `$' that addresses
44 the last line of input, or a context address, which is a `/regular
45 expression/', in the style of ed (1) modified thus:
46 .P
47 .TP 5
48 (1)
49 The escape sequence `\\n' matches a newline embedded in the buffer,
50 and `\\t' matches a tab.
51 .TP 5
52 (2)
53 A command line with no addresses selects every buffer.
54 .TP 5
55 (3)
56 A command line with one address selects every buffer that matches
57 that address.
58 .TP 5
59 (4)
60 A command line with two addresses selects the inclusive range from
61 the first input buffer that matches the first address through the
62 next input buffer that matches the second. (If the second address
63 is a number less than or equal to the line number first selected,
64 only one line is selected.) Once the second address is matched sed
65 starts looking for the first one again; thus, any number of these
66 ranges will be matched.
67 .P
68 The negation operator '!' can prefix a command to apply it to every
69 line not selected by the address(es).
70 .P
71 In the following list of functions, the maximum number of addresses
72 permitted for each function is indicated in parentheses.
73 .P
74 An argument denoted "text" consists of one or more lines, with all
75 but the last ending with `\' to hide the newline.
76 .P
77 Backslashes in text are treated like backslashes in the replacement
78 string of an `s' command and may be used to protect initial whitespace
79 (blanks and tabs) against the stripping that is done on every line of
80 the script.
81 .P
82 An argument denoted "rfile" or "wfile" must be last on the command
83 line. Each wfile is created before processing begins. There can be at
84 most 10 distinct wfile arguments.
85 .TP 5
86 a "text" (1)
87 Append. Place text on output before reading the next input line.
88 .TP 5
89 b "label" (2)
90 Branch to the `:' command bearing the label. If no label is given,
91 branch to the end of the script.
92 .TP 5
93 c "text" (2)
94 Change. Delete the current text buffer. With 0 or 1 address, or at
95 the end of a 2-address range, place text on the output. Start the next
96 cycle.
97 .TP 5
98 d (2)
99 Delete the current text buffer. Start the next cycle.
100 .TP 5
101 D (2)
102 Delete the first line of the current text buffer (all chars up to the
103 first newline). Start the next cycle.
104 .TP 5
105 g (2)
106 Replace the contents of the current text buffer with the contents of
107 the hold space.
108 .TP 5
109 G (2)
110 Append the contents of the hold space to the current text buffer.
111 .TP 5
112 h (2)
113 Copy the current text buffer into the hold space.
114 .TP 5
115 H (2)
116 Append a copy of the current text buffer to the hold space.
117 .TP 5
118 i "text" (1)
119 Insert. Place text on the standard output.
120 .TP 5
121 l (2)
122 List. Sends the pattern space to standard output. A "w" option may
123 follow as in the s command below. Non-printable characters expand to:
125 \\b -- backspace (ASCII 08)
126 \\t -- tab (ASCII 09)
127 \\n -- newline (ASCII 10)
128 \\r -- return (ASCII 13)
129 \\e -- escape (ASCII 27)
130 \\xx -- the ASCII character corresponding to 2 hex digits xx.
131 .TP 5
132 Dump. Hex-dump the pattern space to standard output.
133 .TP 5
134 n (2)
135 Copy the current text buffer to standard output. Read the next line
136 of input into it.
137 .TP 5
138 N (2)
139 Append the next line of input to the current text buffer, inserting
140 an embedded newline between the two. The current line number changes.
141 .TP 5
142 p (2)
143 Print. Copy the current text buffer to the standard output.
144 .TP 5
145 P (2)
146 Copy the first line of the current text buffer (all chars up to the
147 first newline) to standard output.
148 .TP 5
149 q (1)
150 Quit. Branch to the end of the script. Do not start a new cycle.
151 .TP 5
152 r "rfile" (1)
153 Read the contents of rfile. Place them on the output before reading
154 the next input line.
155 .TP 5
156 s /regular expression/replacement/flags (2)
157 Substitute the replacement for instances of the regular expression
158 in the current text buffer. Any character may be used instead of `/'.
159 For a fuller description see ed (1).
160 Flags is zero or more of the following:
162 g -- Global. Substitute for all nonoverlapping instances of the string
163 rather than just the first one.
165 p -- Print the pattern space if a replacement was made.
167 w -- Write. Append the current text buffer to a file argument as in a
168 w command if a replacement is made. Standard output is used if no
169 file argument is given
171 .TP 5
172 t "label" (2)
173 Branch-if-test. Branch to the : command with the given label if any
174 substitutes have been made since the most recent read of an input line
175 or execution of a `t'or `T'. If no label is given, branch to the end
176 of the script.
177 .TP 5
178 T "label" (2)
179 Branch-on-error. Branch to the : command with the given label if no
180 substitutes have succeeded since the last input line or t or T command.
181 Branch to the end of the script if no label is given.
182 .TP 5
183 w "wfile" (2)
184 Write. Append the current text buffer to wfile .
185 .TP 5
186 W "wfile" (2)
187 Write first line. Append first line of the current text buffer
188 to wfile.
189 .TP 5
190 x (2)
191 Exchange the contents of the current text buffer and hold space.
192 .TP 5
193 y /string1/string2/ (2)
194 Translate. Replace each occurrence of a character in string1 with
195 the corresponding character in string2. The lengths of these strings
196 must be equal.
197 .TP 5
198 ! "command" (2)
199 All-but. Apply the function (or group, if function is `{') only to
200 lines not selected by the address(es).
201 .TP 5
202 : "label" (0)
203 This command does nothing but hold a label for `b' and `t' commands
204 to branch to.
205 .TP 5
206 = (1)
207 Place the current line number on the standard output as a line.
208 .TP 5
209 { (2)
210 Execute the following commands through a matching `}' only when the
211 current line matches the address or address range given.
212 .P
213 An empty command is ignored.
214 .P
215 .SH PORTABILITY
216 This tool was reverse-engineered from BSD 4.1 UNIX sed, and (as far
217 as the author's knowledge and tests can determine) is compatible with
218 it. All documented features of BSD 4.1 sed are supported.
219 .P
220 One undocumented feature (a leading 'n' in the first comment having
221 the same effect as an -n command-line option) has been omitted.
222 .P
223 The following bugs and limitations have been fixed:
224 .TP 5
225 *
226 There is no hidden length limit (40 in BSD sed) on w file names.
227 .TP 5
228 *
229 There is no limit (8 in BSD sed) on the length of labels.
230 .TP 5
231 *
232 The exchange command now works for long pattern and hold spaces.
233 .P
234 The following enhancements to existing commands have been made:
235 .TP 5
236 *
237 a, i commands don't insist on a leading backslash-\\n in the text.
238 .TP 5
239 *
240 r, w commands don't insist on whitespace before the filename.
241 .TP 5
242 *
243 The g, p and P options on s commands may be given in any order.
244 .P
245 Some enhancements to regular-expression syntax have been made:
246 .TP 5
247 *
248 \\t is recognized in REs (and elswhere) as an escape for tab.
249 .TP 5
250 *
251 In an RE, + calls for 1..n repeats of the previous pattern.
252 .P
253 The following are completely new features:
254 .TP 5
255 *
256 The l command (list, undocumented and weaker in BSD)
257 .TP 5
258 The 'L' command (hex dump).
259 .TP 5
260 *
261 The W command (write first line of pattern space to file).
262 .TP 5
263 *
264 The T command (branch on last substitute failed).
265 .TP 5
266 *
267 Trailing comments are now allowed on command lines.
268 .P
269 In addition, sed's error messages have been made more specific and
270 informative.
271 .P
272 The implementation is also significantly smaller and faster than
273 BSD 4.1 sed. It uses only the standard I/O library and exit(3).
274 .P
275 .SH SEE ALSO
276 .P
277 ed(1), grep(1), awk(1), lex(1), regexp(5)
278 .P
279 .SH AUTHOR
280 Eric S. Raymond <esr@snark.thyrsus.com> and Rene Rebe <rene@exactcode.de>.
281 This program is distributed under the GPL.