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