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