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

NAME

12       ed — edit text
13

SYNOPSIS

15       ed [-p string] [-s] [file]
16

DESCRIPTION

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

OPTIONS

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

OPERANDS

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

STDIN

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

INPUT FILES

50       The input files shall be text files.
51

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

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

STDOUT

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

STDERR

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

OUTPUT FILES

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

EXTENDED DESCRIPTION

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

EXIT STATUS

821       The following exit values shall be returned:
822
823        0    Successful completion without any file or command errors.
824
825       >0    An error occurred.
826

CONSEQUENCES OF ERRORS

828       When an error in the input script is encountered, or when an  error  is
829       detected that is a consequence of the data (not) present in the file or
830       due to an external condition such as a read or write error:
831
832        *  If the standard input is a terminal device file, all input shall be
833           flushed, and a new command read.
834
835        *  If  the standard input is a regular file, ed shall terminate with a
836           non-zero exit status.
837
838       The following sections are informative.
839

APPLICATION USAGE

841       Because of the extremely terse nature of the  default  error  messages,
842       the  prudent  script writer begins the ed input commands with an H com‐
843       mand, so that if any errors do occur at least some clue as to the cause
844       is made available.
845
846       In  earlier  versions  of  this  standard,  an obsolescent - option was
847       described. This is no longer specified. Applications should use the  -s
848       option.  Using  -  as  a file operand now produces unspecified results.
849       This allows implementations to continue to support the former  required
850       behavior.
851

EXAMPLES

853       None.
854

RATIONALE

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

FUTURE DIRECTIONS

1043       None.
1044

SEE ALSO

1046       Section 1.4, Utility Description Defaults, ex, sed, sh, vi
1047
1048       The   Base  Definitions  volume  of  POSIX.1‐2017,  Table  5-1,  Escape
1049       Sequences and Associated Actions,  Chapter  8,  Environment  Variables,
1050       Section  9.3,  Basic  Regular Expressions, Chapter 11, General Terminal
1051       Interface, Section 12.2, Utility Syntax Guidelines
1052
1054       Portions of this text are reprinted and reproduced in  electronic  form
1055       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
1056       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
1057       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
1058       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
1059       event of any discrepancy between this version and the original IEEE and
1060       The Open Group Standard, the original IEEE and The Open Group  Standard
1061       is  the  referee document. The original Standard can be obtained online
1062       at http://www.opengroup.org/unix/online.html .
1063
1064       Any typographical or formatting errors that appear  in  this  page  are
1065       most likely to have been introduced during the conversion of the source
1066       files to man page format. To report such errors,  see  https://www.ker
1067       nel.org/doc/man-pages/reporting_bugs.html .
1068
1069
1070
1071IEEE/The Open Group                  2017                               ED(1P)
Impressum