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