1ED(1P)                     POSIX Programmer's Manual                    ED(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       ed — edit text
14

SYNOPSIS

16       ed [−p string] [−s] [file]
17

DESCRIPTION

19       The ed utility is a line-oriented text editor that uses two modes: com‐
20       mand  mode  and input mode.  In command mode the input characters shall
21       be interpreted as commands, and in input mode they shall be interpreted
22       as text. See the EXTENDED DESCRIPTION section.
23
24       If an operand is '−', the results are unspecified.
25

OPTIONS

27       The  ed  utility  shall  conform  to  the  Base  Definitions  volume of
28       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines, except  for  the
29       unspecified usage of '−'.
30
31       The following options shall be supported:
32
33       −p string Use  string  as  the  prompt  string when in command mode. By
34                 default, there shall be no prompt string.
35
36       −s        Suppress the writing of byte counts by e, E, r,  and  w  com‐
37                 mands and of the '!'  prompt after a !command.
38

OPERANDS

40       The following operand shall be supported:
41
42       file      If the file argument is given, ed shall simulate an e command
43                 on the file named by the  pathname,  file,  before  accepting
44                 commands from the standard input.
45

STDIN

47       The  standard  input  shall  be  a text file consisting of commands, as
48       described in the EXTENDED DESCRIPTION section.
49

INPUT FILES

51       The input files shall be text files.
52

ENVIRONMENT VARIABLES

54       The following environment variables shall affect the execution of ed:
55
56       HOME      Determine the pathname of the user's home directory.
57
58       LANG      Provide a default value for  the  internationalization  vari‐
59                 ables  that are unset or null. (See the Base Definitions vol‐
60                 ume of POSIX.1‐2008, Section 8.2, Internationalization  Vari‐
61                 ables  for  the  precedence of internationalization variables
62                 used to determine the values of locale categories.)
63
64       LC_ALL    If set to a non-empty string value, override  the  values  of
65                 all the other internationalization variables.
66
67       LC_COLLATE
68                 Determine  the locale for the behavior of ranges, equivalence
69                 classes, and multi-character collating elements within  regu‐
70                 lar expressions.
71
72       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
73                 bytes of text data as characters (for example, single-byte as
74                 opposed  to  multi-byte  characters  in  arguments  and input
75                 files) and the behavior of character classes  within  regular
76                 expressions.
77
78       LC_MESSAGES
79                 Determine the locale that should be used to affect the format
80                 and contents of diagnostic messages written to standard error
81                 and informative messages written to standard output.
82
83       NLSPATH   Determine the location of message catalogs for the processing
84                 of LC_MESSAGES.
85

ASYNCHRONOUS EVENTS

87       The ed utility shall take the standard action for all signals (see  the
88       ASYNCHRONOUS   EVENTS  section  in  Section  1.4,  Utility  Description
89       Defaults) with the following exceptions:
90
91       SIGINT    The ed utility shall interrupt its  current  activity,  write
92                 the  string  "?\n"  to standard output, and return to command
93                 mode (see the EXTENDED DESCRIPTION section).
94
95       SIGHUP    If the buffer is not empty and has  changed  since  the  last
96                 write,  the  ed  utility shall attempt to write a copy of the
97                 buffer in a file. First, the file named ed.hup in the current
98                 directory shall be used; if that fails, the file named ed.hup
99                 in the directory named by the HOME environment variable shall
100                 be used. In any case, the ed utility shall exit without writ‐
101                 ing the file to the currently remembered pathname and without
102                 returning to command mode.
103
104       SIGQUIT   The ed utility shall ignore this event.
105

STDOUT

107       Various  editing  commands  and the prompting feature (see −p) write to
108       standard output, as described in the EXTENDED DESCRIPTION section.
109

STDERR

111       The standard error shall be used only for diagnostic messages.
112

OUTPUT FILES

114       The output files shall be text files whose formats are dependent on the
115       editing commands given.
116

EXTENDED DESCRIPTION

118       The  ed  utility  shall  operate  on  a copy of the file it is editing;
119       changes made to the copy shall have no effect on the  file  until  a  w
120       (write) command is given. The copy of the text is called the buffer.
121
122       Commands  to  ed have a simple and regular structure: zero, one, or two
123       addresses followed by a single-character command, possibly followed  by
124       parameters  to  that command. These addresses specify one or more lines
125       in the buffer.  Every  command  that  requires  addresses  has  default
126       addresses,  so  that the addresses very often can be omitted. If the −p
127       option is specified, the prompt string shall  be  written  to  standard
128       output before each command is read.
129
130       In  general,  only  one  command can appear on a line. Certain commands
131       allow text to be input. This text is placed in the appropriate place in
132       the buffer. While ed is accepting text, it is said to be in input mode.
133       In this mode, no commands shall be recognized; all input is merely col‐
134       lected.  Input  mode is terminated by entering a line consisting of two
135       characters: a <period> ('.')  followed by a <newline>.   This  line  is
136       not considered part of the input text.
137
138   Regular Expressions in ed
139       The ed utility shall support basic regular expressions, as described in
140       the Base Definitions volume of POSIX.1‐2008, Section 9.3, Basic Regular
141       Expressions.   Since  regular  expressions  in  ed  are  always matched
142       against single lines (excluding the terminating <newline>  characters),
143       never against any larger section of text, there is no way for a regular
144       expression to match a <newline>.
145
146       A null RE shall be equivalent to the last RE encountered.
147
148       Regular expressions are used in addresses to specify lines, and in some
149       commands (for example, the s substitute command) to specify portions of
150       a line to be substituted.
151
152   Addresses in ed
153       Addressing in ed relates to the current line.  Generally,  the  current
154       line is the last line affected by a command. The current line number is
155       the address of the current line. If the edit buffer is not  empty,  the
156       initial  value  for the current line shall be the last line in the edit
157       buffer; otherwise, zero.
158
159       Addresses shall be constructed as follows:
160
161        1. The <period> character ('.')  shall address the current line.
162
163        2. The <dollar-sign> character ('$') shall address the  last  line  of
164           the edit buffer.
165
166        3. The  positive  decimal  number  n shall address the nth line of the
167           edit buffer.
168
169        4. The <apostrophe>-x character pair ("'x")  shall  address  the  line
170           marked  with  the mark name character x, which shall be a lowercase
171           letter from the portable character set. It shall be an error if the
172           character  has  not been set to mark a line or if the line that was
173           marked is not currently present in the edit buffer.
174
175        5. A BRE enclosed by <slash> characters ('/') shall address the  first
176           line  found  by searching forwards from the line following the cur‐
177           rent line toward the end of the edit buffer  and  stopping  at  the
178           first  line  for which the line excluding the terminating <newline>
179           matches the BRE. The BRE consisting of a null BRE  delimited  by  a
180           pair  of  <slash>  characters shall address the next line for which
181           the line excluding the terminating <newline> matches the  last  BRE
182           encountered.  In addition, the second <slash> can be omitted at the
183           end of a command line. Within the BRE, a  <backslash>-<slash>  pair
184           ("\/")  shall represent a literal <slash> instead of the BRE delim‐
185           iter. If necessary, the search shall wrap around to  the  beginning
186           of the buffer and continue up to and including the current line, so
187           that the entire buffer is searched.
188
189        6. A BRE enclosed by <question-mark> characters ('?')   shall  address
190           the first line found by searching backwards from the line preceding
191           the current line toward the beginning of the edit buffer and  stop‐
192           ping at the first line for which the line excluding the terminating
193           <newline> matches the BRE. The BRE consisting of a null BRE  delim‐
194           ited  by  a pair of <question-mark> characters ("??") shall address
195           the previous line for which  the  line  excluding  the  terminating
196           <newline> matches the last BRE encountered. In addition, the second
197           <question-mark> can be omitted at the end of a command line. Within
198           the  BRE, a <backslash>-<question-mark> pair ("\?") shall represent
199           a literal <question-mark> instead of the BRE delimiter.  If  neces‐
200           sary,  the  search  shall  wrap around to the end of the buffer and
201           continue up to and including the current line, so that  the  entire
202           buffer is searched.
203
204        7. A <plus-sign> ('+') or <hyphen> character ('−') followed by a deci‐
205           mal number shall address the current line plus or minus the number.
206           A  <plus-sign> or <hyphen> character not followed by a decimal num‐
207           ber shall address the current line plus or minus 1.
208
209       Addresses can be followed by zero or more address  offsets,  optionally
210       <blank>-separated.  Address offsets are constructed as follows:
211
212        *  A  <plus-sign>  or  <hyphen> character followed by a decimal number
213           shall add or subtract, respectively, the indicated number of  lines
214           to  or  from  the  address. A <plus-sign> or <hyphen> character not
215           followed by a decimal number shall add or subtract 1 to or from the
216           address.
217
218        *  A  decimal  number  shall  add the indicated number of lines to the
219           address.
220
221       It shall not be an error for an intermediate address value to  be  less
222       than zero or greater than the last line in the edit buffer. It shall be
223       an error for the final address value to be less than  zero  or  greater
224       than the last line in the edit buffer. It shall be an error if a search
225       for a BRE fails to find a matching line.
226
227       Commands accept zero, one, or two addresses. If more than the  required
228       number  of  addresses  are  provided  to  a  command that requires zero
229       addresses, it shall be an error. Otherwise, if more than  the  required
230       number  of addresses are provided to a command, the addresses specified
231       first shall be evaluated and then discarded until the maximum number of
232       valid addresses remain, for the specified command.
233
234       Addresses  shall  be  separated  from  each other by a <comma> (',') or
235       <semicolon> character (';').  In the case of a  <semicolon>  separator,
236       the  current  line  ('.')   shall be set to the first address, and only
237       then will the second address be calculated. This feature can be used to
238       determine  the  starting  line for forwards and backwards searches; see
239       rules 5. and 6.
240
241       Addresses can be omitted on either side of the <comma>  or  <semicolon>
242       separator,  in  which case the resulting address pairs shall be as fol‐
243       lows:
244
245                              ┌──────────┬─────────────┐
246Specified Resulting  
247                              ├──────────┼─────────────┤
248                              │,         │ 1 , $       │
249                              │, addr    │ 1 , addr    │
250                              │addr ,    │ addr , addr │
251                              │;         │ . ; $       │
252                              │; addr    │ . ; addr    │
253                              │addr ;    │ addr ; addr │
254                              └──────────┴─────────────┘
255       Any <blank> characters included between addresses, address  separators,
256       or address offsets shall be ignored.
257
258   Commands in ed
259       In  the  following list of ed commands, the default addresses are shown
260       in parentheses. The number of addresses shown in the default  shall  be
261       the number expected by the command. The parentheses are not part of the
262       address; they show that the given addresses are the default.
263
264       It is generally invalid for more than one command to appear on a  line.
265       However,  any  command (except e, E, f, q, Q, r, w, and !)  can be suf‐
266       fixed by the letter l, n, or p; in which case, except for the l, n, and
267       p commands, the command shall be executed and then the new current line
268       shall be written as described below under the l,  n,  and  p  commands.
269       When  an l, n, or p suffix is used with an l, n, or p command, the com‐
270       mand shall write to standard output  as  described  below,  but  it  is
271       unspecified  whether  the  suffix  writes the current line again in the
272       requested format or whether the suffix has no effect. For example,  the
273       pl  command  (base  p command with an l suffix) shall either write just
274       the current line or write it twice—once as specified for p and once  as
275       specified  for  l.  Also, the g, G, v, and V commands shall take a com‐
276       mand as a parameter.
277
278       Each address component can be preceded by zero or more <blank>  charac‐
279       ters.  The command letter can be preceded by zero or more <blank> char‐
280       acters. If a suffix letter (l, n, or p) is given, the application shall
281       ensure that it immediately follows the command.
282
283       The  e,  E, f, r, and w commands shall take an optional file parameter,
284       separated from the command letter by one or more <blank> characters.
285
286       If changes have been made in the buffer since the last w  command  that
287       wrote  the  entire buffer, ed shall warn the user if an attempt is made
288       to destroy the editor buffer via the e or q commands.  The  ed  utility
289       shall write the string:
290
291           "?\n"
292
293       (followed  by  an explanatory message if help mode has been enabled via
294       the H command) to standard output and shall continue  in  command  mode
295       with  the  current  line  number  unchanged.  If  the e or q command is
296       repeated with no intervening command, it shall take effect.
297
298       If  a  terminal  disconnect  (see  the  Base  Definitions   volume   of
299       POSIX.1‐2008,  Chapter 11, General Terminal Interface, Modem Disconnect
300       and Closing a Device Terminal), is detected:
301
302        *  If accompanied by a SIGHUP signal, the ed utility shall operate  as
303           described in the ASYNCHRONOUS EVENTS section for a SIGHUP signal.
304
305        *  If  not accompanied by a SIGHUP signal, the ed utility shall act as
306           if an end-of-file had been detected on standard input.
307
308       If an end-of-file is detected on standard input:
309
310        *  If the ed utility is in input mode, ed shall terminate  input  mode
311           and  return  to  command  mode.  It is unspecified if any partially
312           entered lines (that is, input text without a terminating <newline>)
313           are discarded from the input text.
314
315        *  If  the  ed utility is in command mode, it shall act as if a q com‐
316           mand had been entered.
317
318       If the closing delimiter of an RE or of a replacement string (for exam‐
319       ple,  '/')  in  a  g, G, s, v, or V command would be the last character
320       before a <newline>, that delimiter can be omitted, in  which  case  the
321       addressed  line  shall  be written. For example, the following pairs of
322       commands are equivalent:
323
324           s/s1/s2   s/s1/s2/p
325           g/s1      g/s1/p
326           ?s1       ?s1?
327
328       If an invalid command is entered, ed shall write the string:
329
330           "?\n"
331
332       (followed by an explanatory message if help mode has been  enabled  via
333       the  H  command)  to standard output and shall continue in command mode
334       with the current line number unchanged.
335
336   Append Command
337       Synopsis:
338                     (.)a
339                     <text>
340                     .
341
342       The a command shall read  the  given  text  and  append  it  after  the
343       addressed line; the current line number shall become the address of the
344       last inserted line or, if there were none, the addressed line.  Address
345       0  shall be valid for this command; it shall cause the appended text to
346       be placed at the beginning of the buffer.
347
348   Change Command
349       Synopsis:
350                     (.,.)c
351                     <text>
352                     .
353
354       The c command shall delete the addressed lines, then accept input  text
355       that replaces these lines; the current line shall be set to the address
356       of the last line input; or, if there were none, at the line  after  the
357       last  line  deleted; if the lines deleted were originally at the end of
358       the buffer, the current line number shall be set to the address of  the
359       new  last line; if no lines remain in the buffer, the current line num‐
360       ber shall be set to zero. Address 0 shall be valid for this command; it
361       shall be interpreted as if address 1 were specified.
362
363   Delete Command
364       Synopsis:
365                     (.,.)d
366
367       The  d  command  shall  delete the addressed lines from the buffer. The
368       address of the line after the last line deleted shall become  the  cur‐
369       rent  line  number;  if the lines deleted were originally at the end of
370       the buffer, the current line number shall be set to the address of  the
371       new  last line; if no lines remain in the buffer, the current line num‐
372       ber shall be set to zero.
373
374   Edit Command
375       Synopsis:
376                     e [file]
377
378       The e command shall delete the entire contents of the buffer  and  then
379       read  in  the file named by the pathname file.  The current line number
380       shall be set to the address of the last line of the buffer. If no path‐
381       name is given, the currently remembered pathname, if any, shall be used
382       (see the f command). The number of bytes read shall be written to stan‐
383       dard  output, unless the −s option was specified, in the following for‐
384       mat:
385
386           "%d\n", <number of bytes read>
387
388       The name file shall be remembered for possible use as a  default  path‐
389       name in subsequent e, E, r, and w commands. If file is replaced by '!',
390       the rest of the line shall be taken to be a shell  command  line  whose
391       output is to be read. Such a shell command line shall not be remembered
392       as the current file.  All marks shall be discarded upon the  completion
393       of  a  successful  e  command. If the buffer has changed since the last
394       time the entire buffer was  written,  the  user  shall  be  warned,  as
395       described previously.
396
397   Edit Without Checking Command
398       Synopsis:
399                     E [file]
400
401       The  E  command  shall possess all properties and restrictions of the e
402       command except that the editor shall  not  check  to  see  whether  any
403       changes have been made to the buffer since the last w command.
404
405   Filename Command
406       Synopsis:
407                     f [file]
408
409       If  file  is given, the f command shall change the currently remembered
410       pathname to file; whether the name is changed or  not,  it  shall  then
411       write  the (possibly new) currently remembered pathname to the standard
412       output in the following format:
413
414           "%s\n", <pathname>
415
416       The current line number shall be unchanged.
417
418   Global Command
419       Synopsis:
420                     (1,$)g/RE/command list
421
422       In the g command, the first step shall be to mark every line for  which
423       the  line  excluding  the  terminating  <newline> matches the given RE.
424       Then, going sequentially from the beginning of the file to the  end  of
425       the  file,  the  given  command  list shall be executed for each marked
426       line, with the current line number set to the address of that line. Any
427       line modified by the command list shall be unmarked. When the g command
428       completes, the current line number shall have the value assigned by the
429       last command in the command list.  If there were no matching lines, the
430       current line number shall not be changed. A single command or the first
431       of  a list of commands shall appear on the same line as the global com‐
432       mand. All lines of a multi-line list except  the  last  line  shall  be
433       ended with a <backslash> preceding the terminating <newline>; the a, i,
434       and c commands and associated input are permitted. The '.'  terminating
435       input  mode  can be omitted if it would be the last line of the command
436       list. An empty command list shall be equivalent to the p  command.  The
437       use  of  the  g,  G, v, V, and !  commands in the command list produces
438       undefined results. Any character other than <space> or <newline> can be
439       used  instead  of  a  <slash>  to delimit the RE. Within the RE, the RE
440       delimiter itself can be used as a literal character if it  is  preceded
441       by a <backslash>.
442
443   Interactive Global Command
444       Synopsis:
445                     (1,$)G/RE/
446
447       In  the G command, the first step shall be to mark every line for which
448       the line excluding the terminating  <newline>  matches  the  given  RE.
449       Then, for every such line, that line shall be written, the current line
450       number shall be set to the address of that line, and  any  one  command
451       (other  than one of the a, c, i, g, G, v, and V commands) shall be read
452       and executed. A <newline> shall act  as  a  null  command  (causing  no
453       action to be taken on the current line); an '&' shall cause the re-exe‐
454       cution of the most recent non-null command executed within the  current
455       invocation of G.  Note that the commands input as part of the execution
456       of the G command can address and affect any lines in  the  buffer.  Any
457       line  modified by the command shall be unmarked. The final value of the
458       current line number shall be the value set by the last command success‐
459       fully executed. (Note that the last command successfully executed shall
460       be the G command itself if a command fails or the null command is spec‐
461       ified.)  If there were no matching lines, the current line number shall
462       not be changed. The G command can be terminated by a SIGINT signal. Any
463       character  other  than  <space>  or  <newline> can be used instead of a
464       <slash> to delimit the RE and the replacement. Within the  RE,  the  RE
465       delimiter  itself  can be used as a literal character if it is preceded
466       by a <backslash>.
467
468   Help Command
469       Synopsis:
470                     h
471
472       The h command shall write a  short  message  to  standard  output  that
473       explains  the reason for the most recent '?'  notification. The current
474       line number shall be unchanged.
475
476   Help-Mode Command
477       Synopsis:
478                     H
479
480       The H command shall cause ed to enter a mode  in  which  help  messages
481       (see  the h command) shall be written to standard output for all subse‐
482       quent '?'  notifications. The H command  alternately  shall  turn  this
483       mode  on and off; it is initially off. If the help-mode is being turned
484       on, the H command also explains  the  previous  '?'   notification,  if
485       there was one. The current line number shall be unchanged.
486
487   Insert Command
488       Synopsis:
489                     (.)i
490                     <text>
491                     .
492
493       The  i  command  shall insert the given text before the addressed line;
494       the current line is set to the last inserted  line  or,  if  there  was
495       none,  to  the  addressed line. This command differs from the a command
496       only in the placement of the input text. Address 0 shall be  valid  for
497       this command; it shall be interpreted as if address 1 were specified.
498
499   Join Command
500       Synopsis:
501                     (.,.+1)j
502
503       The  j  command shall join contiguous lines by removing the appropriate
504       <newline> characters. If exactly one address  is  given,  this  command
505       shall do nothing. If lines are joined, the current line number shall be
506       set to the address of the joined line; otherwise, the current line num‐
507       ber shall be unchanged.
508
509   Mark Command
510       Synopsis:
511                     (.)kx
512
513       The  k  command  shall  mark  the addressed line with name x, which the
514       application shall ensure is a lowercase letter from the portable  char‐
515       acter  set. The address "'x" shall then refer to this line; the current
516       line number shall be unchanged.
517
518   List Command
519       Synopsis:
520                     (.,.)l
521
522       The l command shall write to standard output the addressed lines  in  a
523       visually  unambiguous  form.  The characters listed in the Base Defini‐
524       tions volume of POSIX.1‐2008, Table 5-1, Escape Sequences  and  Associ‐
525       ated  Actions ('\\', '\a', '\b', '\f', '\r', '\t', '\v') shall be writ‐
526       ten as the corresponding escape sequence; the '\n' in that table is not
527       applicable.  Non-printable characters not in the table shall be written
528       as one three-digit octal number (with a preceding  <backslash>  charac‐
529       ter) for each byte in the character (most significant byte first).
530
531       Long  lines  shall  be  folded,  with the point of folding indicated by
532       <newline> preceded by a <backslash>; the length at which folding occurs
533       is  unspecified,  but  should be appropriate for the output device. The
534       end of each line shall be marked with a '$', and '$' characters  within
535       the  text  shall be written with a preceding <backslash>.  An l command
536       can be appended to any other command other than e, E, f, q, Q, r, w, or
537       !.   The  current  line  number shall be set to the address of the last
538       line written.
539
540   Move Command
541       Synopsis:
542                     (.,.)maddress
543
544       The m command shall reposition  the  addressed  lines  after  the  line
545       addressed  by  address.  Address 0 shall be valid for address and cause
546       the addressed lines to be moved to the  beginning  of  the  buffer.  It
547       shall  be  an  error if address address falls within the range of moved
548       lines. The current line number shall be set to the address of the  last
549       line moved.
550
551   Number Command
552       Synopsis:
553                     (.,.)n
554
555       The  n command shall write to standard output the addressed lines, pre‐
556       ceding each line by its line number and a <tab>; the current line  num‐
557       ber shall be set to the address of the last line written. The n command
558       can be appended to any command other than e, E, f, q, Q, r, w, or !.
559
560   Print Command
561       Synopsis:
562                     (.,.)p
563
564       The p command shall write to standard output the addressed  lines;  the
565       current  line number shall be set to the address of the last line writ‐
566       ten. The p command can be appended to any command other than e,  E,  f,
567       q, Q, r, w, or !.
568
569   Prompt Command
570       Synopsis:
571                     P
572
573       The  P  command  shall  cause ed to prompt with an <asterisk> ('*') (or
574       string, if −p is specified) for all subsequent commands. The P  command
575       alternatively shall turn this mode on and off; it shall be initially on
576       if the −p option is specified; otherwise, off. The current line  number
577       shall be unchanged.
578
579   Quit Command
580       Synopsis:
581                     q
582
583       The  q  command shall cause ed to exit. If the buffer has changed since
584       the last time the entire buffer was written, the user shall be  warned,
585       as described previously.
586
587   Quit Without Checking Command
588       Synopsis:
589                     Q
590
591       The  Q  command shall cause ed to exit without checking whether changes
592       have been made in the buffer since the last w command.
593
594   Read Command
595       Synopsis:
596                     ($)r [file]
597
598       The r command shall read in the file named by  the  pathname  file  and
599       append  it  after the addressed line. If no file argument is given, the
600       currently remembered pathname, if any, shall be used (see the e  and  f
601       commands).  The  currently  remembered  pathname  shall  not be changed
602       unless there is no remembered pathname. Address 0 shall be valid for  r
603       and  shall cause the file to be read at the beginning of the buffer. If
604       the read is successful, and −s was not specified, the number  of  bytes
605       read shall be written to standard output in the following format:
606
607           "%d\n", <number of bytes read>
608
609       The  current  line  number shall be set to the address of the last line
610       read in. If file is replaced by '!', the rest  of  the  line  shall  be
611       taken  to  be  a  shell command line whose output is to be read. Such a
612       shell command line shall not be remembered as the current pathname.
613
614   Substitute Command
615       Synopsis:
616                     (.,.)s/RE/replacement/flags
617
618       The s command shall search each addressed line for an occurrence of the
619       specified  RE  and  replace  either  the  first or all (non-overlapped)
620       matched strings with the replacement; see the following description  of
621       the  g  suffix.  It  is  an  error  if  the substitution fails on every
622       addressed line. Any character other than <space> or  <newline>  can  be
623       used instead of a <slash> to delimit the RE and the replacement. Within
624       the RE, the RE delimiter itself can be used as a literal  character  if
625       it  is preceded by a <backslash>.  The current line shall be set to the
626       address of the last line on which a substitution occurred.
627
628       An <ampersand> ('&') appearing in the replacement shall be replaced  by
629       the string matching the RE on the current line.  The special meaning of
630       '&' in this context can be suppressed by preceding it  by  <backslash>.
631       As  a  more  general  feature, the characters '\n', where n is a digit,
632       shall be replaced by the text matched by the corresponding  back-refer‐
633       ence  expression.  If  the corresponding back-reference expression does
634       not match, then the characters '\n' shall  be  replaced  by  the  empty
635       string.  When  the  character '%' is the only character in the replace‐
636       ment, the replacement used in the most recent substitute command  shall
637       be  used as the replacement in the current substitute command; if there
638       was no previous substitute command, the use of '%' in this manner shall
639       be  an  error.  The  '%' shall lose its special meaning when it is in a
640       replacement string of more than one  character  or  is  preceded  by  a
641       <backslash>.   For each <backslash> encountered in scanning replacement
642       from beginning to end, the following character shall lose  its  special
643       meaning  (if  any).  It is unspecified what special meaning is given to
644       any character other than <backslash>, '&', '%', or digits.
645
646       A line can be split by substituting a <newline> into it.  The  applica‐
647       tion  shall  ensure it escapes the <newline> in the replacement by pre‐
648       ceding it by <backslash>.  Such substitution cannot be done as part  of
649       a  g  or  v  command list.  The current line number shall be set to the
650       address of the last line on which a substitution is  performed.  If  no
651       substitution  is performed, the current line number shall be unchanged.
652       If a line is split, a substitution shall be  considered  to  have  been
653       performed  on  each of the new lines for the purpose of determining the
654       new current line number. A substitution shall  be  considered  to  have
655       been  performed  even  if  the  replacement  string is identical to the
656       string that it replaces.
657
658       The application shall ensure that the value of flags is  zero  or  more
659       of:
660
661       count   Substitute  for  the countth occurrence only of the RE found on
662               each addressed line.
663
664       g       Globally substitute for all non-overlapping instances of the RE
665               rather  than just the first one. If both g and count are speci‐
666               fied, the results are unspecified.
667
668       l       Write to standard output the final line in which a substitution
669               was made. The line shall be written in the format specified for
670               the l command.
671
672       n       Write to standard output the final line in which a substitution
673               was made. The line shall be written in the format specified for
674               the n command.
675
676       p       Write to standard output the final line in which a substitution
677               was made. The line shall be written in the format specified for
678               the p command.
679
680   Copy Command
681       Synopsis:
682                     (.,.)taddress
683
684       The t command shall be equivalent to the m command, except that a  copy
685       of the addressed lines shall be placed after address address (which can
686       be 0); the current line number shall be set to the address of the  last
687       line added.
688
689   Undo Command
690       Synopsis:
691                     u
692
693       The  u command shall nullify the effect of the most recent command that
694       modified anything in the buffer, namely the most recent a, c, d, g,  i,
695       j, m, r, s, t, u, v, G, or V command. All changes made to the buffer by
696       a g, G, v, or V global command shall be undone as a single  change;  if
697       no changes were made by the global command (such as with g/RE/p), the u
698       command shall have no effect. The current line number shall be  set  to
699       the value it had immediately before the command being undone started.
700
701   Global Non-Matched Command
702       Synopsis:
703                     (1,$)v/RE/command list
704
705       This  command  shall  be equivalent to the global command g except that
706       the lines that are marked during the first  step  shall  be  those  for
707       which  the  line excluding the terminating <newline> does not match the
708       RE.
709
710   Interactive Global Not-Matched Command
711       Synopsis:
712                     (1,$)V/RE/
713
714       This command shall be equivalent to the interactive  global  command  G
715       except  that  the  lines that are marked during the first step shall be
716       those for which the line excluding the terminating <newline>  does  not
717       match the RE.
718
719   Write Command
720       Synopsis:
721                     (1,$)w [file]
722
723       The  w  command  shall write the addressed lines into the file named by
724       the pathname file.  The command shall create the file, if it  does  not
725       exist,  or  shall  replace  the contents of the existing file. The cur‐
726       rently remembered pathname shall not be  changed  unless  there  is  no
727       remembered pathname.  If no pathname is given, the currently remembered
728       pathname, if any, shall be used (see the e and f commands); the current
729       line  number shall be unchanged. If the command is successful, the num‐
730       ber of bytes written shall be written to standard output, unless the −s
731       option was specified, in the following format:
732
733           "%d\n", <number of bytes written>
734
735       If  file  begins  with '!', the rest of the line shall be taken to be a
736       shell command line whose standard input shall be the  addressed  lines.
737       Such  a shell command line shall not be remembered as the current path‐
738       name. This usage of the write command with '!'  shall not be considered
739       as a ``last w command that wrote the entire buffer'', as described pre‐
740       viously; thus, this alone shall not prevent the warning to the user  if
741       an  attempt  is  made  to destroy the editor buffer via the e or q com‐
742       mands.
743
744   Line Number Command
745       Synopsis:
746                     ($)=
747
748       The line number of the addressed line shall be written to standard out‐
749       put in the following format:
750
751           "%d\n", <line number>
752
753       The current line number shall be unchanged by this command.
754
755   Shell Escape Command
756       Synopsis:
757                     !command
758
759       The  remainder  of the line after the '!'  shall be sent to the command
760       interpreter to be interpreted as a shell command line. Within the  text
761       of  that  shell  command  line,  the  unescaped  character '%' shall be
762       replaced with the remembered pathname; if a '!'  appears as  the  first
763       character  of  the  command,  it shall be replaced with the text of the
764       previous shell command executed via '!'.  Thus, "!!" shall  repeat  the
765       previous  !command.  If  any replacements of '%' or '!'  are performed,
766       the modified line shall be written to the standard output  before  com‐
767       mand is executed. The !  command shall write:
768
769           "!\n"
770
771       to  standard output upon completion, unless the −s option is specified.
772       The current line number shall be unchanged.
773
774   Null Command
775       Synopsis:
776                     (.+1)
777
778       An address alone on a line shall cause the addressed line to  be  writ‐
779       ten.  A <newline> alone shall be equivalent to "+1p".  The current line
780       number shall be set to the address of the written line.
781

EXIT STATUS

783       The following exit values shall be returned:
784
785        0    Successful completion without any file or command errors.
786
787       >0    An error occurred.
788

CONSEQUENCES OF ERRORS

790       When an error in the input script is encountered, or when an  error  is
791       detected that is a consequence of the data (not) present in the file or
792       due to an external condition such as a read or write error:
793
794        *  If the standard input is a terminal device file, all input shall be
795           flushed, and a new command read.
796
797        *  If  the standard input is a regular file, ed shall terminate with a
798           non-zero exit status.
799
800       The following sections are informative.
801

APPLICATION USAGE

803       Because of the extremely terse nature of the  default  error  messages,
804       the  prudent  script writer begins the ed input commands with an H com‐
805       mand, so that if any errors do occur at least some clue as to the cause
806       is made available.
807
808       In  earlier  versions  of  this  standard,  an obsolescent option was
809       described. This is no longer specified. Applications should use the  −s
810       option.  Using  as  a file operand now produces unspecified results.
811       This allows implementations to continue to support the former  required
812       behavior.
813

EXAMPLES

815       None.
816

RATIONALE

818       The  initial  description of this utility was adapted from the SVID. It
819       contains some features not found in Version 7 or  BSD-derived  systems.
820       Some of the differences between the POSIX and BSD ed utilities include,
821       but need not be limited to:
822
823        *  The BSD option does not suppress the '!'  prompt after a !   com‐
824           mand.
825
826        *  BSD does not support the special meanings of the '%' and '!'  char‐
827           acters within a !  command.
828
829        *  BSD does not support the addresses ';' and ','.
830
831        *  BSD allows the command/suffix pairs pp, ll, and so  on,  which  are
832           unspecified in this volume of POSIX.1‐2008.
833
834        *  BSD does not support the '!'  character part of the e, r, or w com‐
835           mands.
836
837        *  A failed g command in BSD sets the line number  to  the  last  line
838           searched if there are no matches.
839
840        *  BSD does not default the command list to the p command.
841
842        *  BSD does not support the G, h, H, n, or V commands.
843
844        *  On  BSD,  if  there is no inserted text, the insert command changes
845           the current line to the referenced  line  −1;  that  is,  the  line
846           before the specified line.
847
848        *  On  BSD,  the  join  command with only a single address changes the
849           current line to that address.
850
851        *  BSD does not support the P command; moreover, in BSD it is  synony‐
852           mous with the p command.
853
854        *  BSD does not support the undo of the commands j, m, r, s, or t.
855
856        *  The  Version  7  ed command W, and the BSD ed commands W, wq, and z
857           are not present in this volume of POSIX.1‐2008.
858
859       The −s option was added to allow the functionality  of  the  removed  
860       option in a manner compatible with the Utility Syntax Guidelines.
861
862       In early proposals there was a limit, {ED_FILE_MAX}, that described the
863       historical limitations of some ed utilities in their handling of  large
864       files;  some  of  these have had problems with files larger than 100000
865       bytes. It was this limitation that  prompted  much  of  the  desire  to
866       include  a  split  command  in  this volume of POSIX.1‐2008. Since this
867       limit was removed, this volume of POSIX.1‐2008 requires that  implemen‐
868       tations  document the file size limits imposed by ed in the conformance
869       document. The limit {ED_LINE_MAX}  was  also  removed;  therefore,  the
870       global limit {LINE_MAX} is used for input and output lines.
871
872       The  manner  in which the l command writes non-printable characters was
873       changed to avoid the historical backspace-overstrike method.  On  video
874       display  terminals,  the overstrike is ambiguous because most terminals
875       simply replace overstruck characters, making the l  format  not  useful
876       for  its intended purpose of unambiguously understanding the content of
877       the line. The historical <backslash>-escapes were also ambiguous.  (The
878       string  "a\0011" could represent a line containing those six characters
879       or a line containing the three characters 'a', a  byte  with  a  binary
880       value  of  1,  and  a  1.)  In  the format required here, a <backslash>
881       appearing in the line is written as "\\" so that the  output  is  truly
882       unambiguous.  The  method of marking the ends of lines was adopted from
883       the ex editor and is required for any line ending  in  <space>  charac‐
884       ters; the '$' is placed on all lines so that a real '$' at the end of a
885       line cannot be misinterpreted.
886
887       Earlier versions of this  standard  allowed  for  implementations  with
888       bytes  other  than  eight bits, but this has been modified in this ver‐
889       sion.
890
891       The description of how a NUL is written was removed. The NUL  character
892       cannot  be  in  text  files, and this volume of POSIX.1‐2008 should not
893       dictate behavior in the case of undefined, erroneous input.
894
895       Unlike some of the other editing utilities, the filenames  accepted  by
896       the E, e, R, and r commands are not patterns.
897
898       Early  proposals  stated  that  the −p option worked only when standard
899       input was associated with a terminal device. This has been  changed  to
900       conform to historical implementations, thereby allowing applications to
901       interpose themselves between a user and the ed utility.
902
903       The form of the substitute command that uses the n suffix  was  limited
904       in  some historical documentation (where this was described incorrectly
905       as ``backreferencing''). This limit has been omitted because  there  is
906       no  reason  why  an editor processing lines of {LINE_MAX} length should
907       have this restriction. The command s/x/X/2047 should be able to substi‐
908       tute the 2047th occurrence of 'x' on a line.
909
910       The  use  of  printing commands with printing suffixes (such as pn, lp,
911       and so on) was made unspecified because BSD-based systems  allow  this,
912       whereas System V does not.
913
914       Some  BSD-based systems exit immediately upon receipt of end-of-file if
915       all of the lines in the file have been deleted. Since  this  volume  of
916       POSIX.1‐2008 refers to the q command in this instance, such behavior is
917       not allowed.
918
919       Some historical implementations returned exit status zero even if  com‐
920       mand  errors  had  occurred;  this  is  not  allowed  by this volume of
921       POSIX.1‐2008.
922
923       Some historical implementations contained a bug that allowed  a  single
924       <period> to be entered in input mode as <backslash> <period> <newline>.
925       This is not allowed by ed because there is no description  of  escaping
926       any of the characters in input mode; <backslash> characters are entered
927       into the buffer exactly as typed. The typical method of entering a sin‐
928       gle <period> has been to precede it with another character and then use
929       the substitute command to delete that character.
930
931       It is difficult under some modes of some versions of historical operat‐
932       ing  system terminal drivers to distinguish between an end-of-file con‐
933       dition and terminal disconnect. POSIX.1‐2008 does not require implemen‐
934       tations  to  distinguish between the two situations, which permits his‐
935       torical implementations of the ed utility on  historical  platforms  to
936       conform. Implementations are encouraged to distinguish between the two,
937       if possible, and take appropriate action on terminal disconnect.
938
939       Historically, ed accepted a zero address for the a and  r  commands  in
940       order  to  insert text at the start of the edit buffer. When the buffer
941       was empty the command .= returned zero. POSIX.1‐2008  requires  confor‐
942       mance to historical practice.
943
944       For  consistency  with the a and r commands and better user functional‐
945       ity, the i and c commands must also accept an address of  0,  in  which
946       case 0i is treated as 1i and likewise for the c command.
947
948       All of the following are valid addresses:
949
950       +++         Three lines after the current line.
951
952       /pattern/−  One line before the next occurrence of pattern.
953
954       −2          Two lines before the current line.
955
956       3 −−−− 2    Line one (note the intermediate negative address).
957
958       1 2 3       Line six.
959
960       Any  number  of addresses can be provided to commands taking addresses;
961       for example, "1,2,3,4,5p" prints lines 4 and  5,  because  two  is  the
962       greatest valid number of addresses accepted by the print command. This,
963       in combination with the <semicolon> delimiter, permits users to  create
964       commands  based  on ordered patterns in the file. For example, the com‐
965       mand "3;/foo/;+2p" will display the first line after line 3  that  con‐
966       tains  the  pattern foo, plus the next two lines. Note that the address
967       "3;" must still be evaluated before being discarded, because the search
968       origin for the "/foo/" command depends on this.
969
970       Historically,  ed  disallowed  address chains, as discussed above, con‐
971       sisting solely of <comma> or <semicolon> separators; for example, ",,,"
972       or  ";;;" were considered an error. For consistency of address specifi‐
973       cation, this restriction is removed. The following table lists some  of
974       the address forms now possible:
975
976           ┌────────┬───────┬───────┬────────────┬───────────────────────┐
977Address Addr1 Addr2 Status   Comment        
978           ├────────┼───────┼───────┼────────────┼───────────────────────┤
979           │7,      │   7   │   7   │ Historical │                       │
980           │7,5,    │   5   │   5   │ Historical │                       │
981           │7,5,9   │   5   │   9   │ Historical │                       │
982           │7,9     │   7   │   9   │ Historical │                       │
983           │7,+     │   7   │   8   │ Historical │                       │
984           │,       │   1   │   $   │ Historical │                       │
985           │,7      │   1   │   7   │ Extension  │                       │
986           │,,      │   $   │   $   │ Extension  │                       │
987           │,;      │   $   │   $   │ Extension  │                       │
988           │7;      │   7   │   7   │ Historical │                       │
989           │7;5;    │   5   │   5   │ Historical │                       │
990           │7;5;9   │   5   │   9   │ Historical │                       │
991           │7;5,9   │   5   │   9   │ Historical │                       │
992           │7;$;4   │   $   │   4   │ Historical │ Valid, but erroneous. │
993           │7;9     │   7   │   9   │ Historical │                       │
994           │7;+     │   7   │   8   │ Historical │                       │
995           │;       │   .   │   $   │ Historical │                       │
996           │;7      │   .   │   7   │ Extension  │                       │
997           │;;      │   $   │   $   │ Extension  │                       │
998           │;,      │   $   │   $   │ Extension  │                       │
999           └────────┴───────┴───────┴────────────┴───────────────────────┘
1000       Historically,  ed  accepted  the  '^' character as an address, in which
1001       case it was identical to the <hyphen> character. POSIX.1‐2008 does  not
1002       require or prohibit this behavior.
1003

FUTURE DIRECTIONS

1005       None.
1006

SEE ALSO

1008       Section 1.4, Utility Description Defaults, ex, sed, sh, vi
1009
1010       The   Base  Definitions  volume  of  POSIX.1‐2008,  Table  5-1,  Escape
1011       Sequences and Associated Actions,  Chapter  8,  Environment  Variables,
1012       Section  9.3,  Basic  Regular Expressions, Chapter 11, General Terminal
1013       Interface, Section 12.2, Utility Syntax Guidelines
1014
1016       Portions of this text are reprinted and reproduced in  electronic  form
1017       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
1018       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
1019       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
1020       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
1021       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
1022       event of any discrepancy between this version and the original IEEE and
1023       The  Open Group Standard, the original IEEE and The Open Group Standard
1024       is the referee document. The original Standard can be  obtained  online
1025       at http://www.unix.org/online.html .
1026
1027       Any  typographical  or  formatting  errors that appear in this page are
1028       most likely to have been introduced during the conversion of the source
1029       files  to  man page format. To report such errors, see https://www.ker
1030       nel.org/doc/man-pages/reporting_bugs.html .
1031
1032
1033
1034IEEE/The Open Group                  2013                               ED(1P)
Impressum