8-bit characters are not ignored

[unix-history] / usr / src / contrib / ed / ed.1

.\" Copyright (c) 1992 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Rodney Ruddock of the University of Guelph.
.\"
.\" %sccs.include.redist.roff%
.\"
.\"	@(#)ed.1	5.3 (Berkeley) %G%
.\"
.TH ED 1 ""
.SH NAME
ed \- line oriented text editor
.SH SYNOPSIS
.B ed
[
.B \-p
.I prompt-string
] [
.B \-s
] [
.B \-v
] [
.I filename
]
.SH DESCRIPTION
.I Ed
is a standard text editor.
.PP
\fIEd\fR is a powerful line oriented editor. Although ex(1)/vi(1) have gained
popularity, \fIed\fR still maintains advantages over them. Most notable points
are the
.I W
command (see below) (which is not part of ex(1)/vi(1)\|), the
smaller executable size (you can often be editing before the others finish
loading), and the better response when editing from slow terminals or across
low baud data lines. \fIEd\fR continues to be used by many system utilities.
.SH OPTIONS
.PP
When a filename is present \fIed\fR starts by simulating an
.I e
command (see below)
If no filename is present \fIed\fR
starts with an empty buffer.
The option
.B \-p
allows for the setting of a prompt string in
.IR ed .
The option
.B \-s
suppresses the printing
of explanatory output
(from the commands
.IR e ,
.IR E ,
.IR r ,
.IR w ,
.I W
and
.IR wq ;
see below) and should be used with a script.
The
.B \-v
option will display a message of which mode (BSD or POSIX)
.I ed
as been set locally. This is useful for determining the described
behavior below.
.PP
.I Ed
performs all changes to a copy of the file which is contained in a \fBbuffer\fR.
For the changes to have an effect one of the write commands (
.IR w ,
.IR W ,
.IR wq ,
or
.IR Wq )
must be issued.
.PP
The contents of the
.B buffer
can changed by issuing commands that are lead
by zero, one, or two addresses. All commands are alphabetically listed below
with their parameter structures if applicable; trailing structures not
described with commands are regarded as erroneous. Commands that
accept zero addresses regard the presence of any address as an error.
.PP
.I Ed
works in two modes: command, and input. The two modes are exclusive of
each other. While in command mode
.I ed
accepts commands that display, modify, or give information about the
.BR buffer .
While in input mode
.I ed
accepts lines of text to be added to the
.BR buffer .
.PP
Addressing in \fIed\fR specifies one or more lines contained in the
.BR buffer .
For commands that expect at least one address, and none are given, default
addresses will be used.
Using addresses in
.I ed
involves understanding that during the execution of most
.I ed
commands that a
.I "current line"
(
.BR current )
exists.
.B Current
(as a rule of thumb) is the location in the
.B buffer
that the last command issued affected; some
commands do not affect
.BR current .
Each command description (below) describes
its affects on
.B current
as the affect will vary depending under which compile option (BSD or POSIX)
.I ed
was compiled under.
Addresses can be divided into three cases: one 
address (\fBsingle address\fR), two addresses (an \fBaddress pair\fR),
and special address forms.

For the first two cases
an address is formed with the use of:
.TP
1.
A positive decimal integer (e.g. 123) indicating a line number in the buffer.
Line number 1 is the first line in the buffer.
.TP
2.
The `.' character indicating the current line (\fBcurrent\fR).
.TP
3.
The `$' character which indicates the last line in the buffer.
.TP
4.
A regular expression (RE) enclosed with `/'s as delimiters (i.e. /RE/).
This causes a forward search to the first occurrence of the specified RE. The
address will then become this line.
The character sequence \e/ escapes the forwardslash from being a
delimiter.
The search will wrap from the bottom of
the buffer to the top of the buffer if need be.
.I Ed
RE's are, outside of this document, now refered to as
.IR "basic regular expressions" .
Basic regular expressions (BRE's), traditionally described in \fIed(1)\fR are
now fully described in regex(1). BRE's are, for the most part, the same as
the old RE's - the name has changed and the expressions extended to meet
POSIX 1003.2 specifications. (See the search command for more details.)
.TP
5.
A RE enclosed with `?'s as delimiters (i.e. ?RE?).
This will cause a backward search to the first occurrence of the
specified BRE. The address will then become this line.
The character sequence \e? escapes the questionmark from being a
delimiter.
The search will wrap
from the top of the buffer to the
bottom of the buffer if need be. (See the search command for more details.)
.TP
6.
A line previously marked by the `k' command (see below). \fB`x\fR addresses
the line marked by the single lower-case letter `\fBx\fR' (from the
portable character set in the range a-z).
.TP
7.
An address of the form 1-6 followed by a `+' followed by an integer number, 
.BR n ,
specifies the line to be addressed is 
.B n
lines after the address of the form
1-6.
If the address starts with a `+' then by default the addressed line is taken
with respect to 
.B current
(equivalent to `.'\|; form 2).
If no integer number is given then 1 is added to the address.
Hence, if
more than one `+' is given in a sequence, with no integer number following,
1 is added to the address for each `+'. Therefore, +++ is eqivalent to +3,
but +++1 is equivalent to +1.
.TP
8.
An address of the form 1-6 followed by a `\-' followed by an integer number,
.BR n ,
specifies the line to be addressed is 
.B n
lines before the address of the form
1-6.
If the address starts with a `\-' then by default the
addressed line is taken
with respect to 
.B current
(`.'\|; form 1).
If no integer number is given then 1 is subtracted from the address.
Hence, if
more than one `\-' is given in a sequence, with no integer number following,
1 is subtracted from the address for each `\-'. Therefore, \-\-\-
is eqivalent to \-3,
but \-\-\-1 is equivalent to \-1.
For backward compatibility `^' is the equivalent to `\-'.
.TP
9.
A `,' (comma) may be used to separate two addresses of the form 1-8 to
create an \fBaddress pair\fR.
The first address must occur no later in
the buffer than the second address to be legal.
.TP
10.
A `;' (semicolon) may be used to separate two addresses of the form 1-8 to
create an \fBaddress pair\fR.
With this form the second address is evaluated with respect to
and after the first address has been evaluated. This is useful when
addresses of the forms 2-8 are used.
The first address must occur no later in
the buffer than the second address to be legal.
.TP
NOTE:
Addresses of the forms 7 and 8 cannot be followed by addresses
of forms 2-6; it is an error.
.PP
The following are special address forms that cannot be combined
with any of the address forms listed above.
A `,' by itself represents the address pair `1,$'.
Likewise `%' by itself represents the address pair `1,$'.
A `;' by itself represents the address pair `.,$'.
.PP
The \fIed\fR commands listed below default to the addresses prefixing the
commands. Commands without default addresses accept zero addresses.
The parentheses with the default addresses are not part of
the address; they are used to show that the addresses are
default.
.PP
Generally only one command appears on a line at a time.
However, many of the commands may be suffixed by `l', `n',
or `p', in which case
the current line is printed
in the manner discussed below.
These suffixes may be combined in any order.
.TP 5
.RB (\|.\|)\|a
.br
.ns
.TP 5
<text>
.br
.ns
.TP 5
.B .
.br
Append text after the addressed line. A `.' in the first column
followed immediately by a <newline> places
.I ed
back in command mode - the `.' is not included in the text. Line 0
is legal for this command; text will be placed at the top of the buffer.
.B Current
is the last line appended (or the addressed line if no text given).
.TP 5
.RB (\|.\|,\|.\|)\|c
.br
.ns
.TP 5
<text>
.br
.ns
.TP 5
.B .
.br
Change text on the addressed line(s). The addressed lines are deleted
before
.I
ed
is placed in input mode. A `.' in the first column
followed immediately by a <newline> places
.I ed
back in command mode - the `.' is not included in the text.
.B Current
is the new last line appended (or if no text is given the line after
the addressed line deleted).
.TP 5
.RB (\|.\|,\|.\|)\|d
Delete the addressed line(s) from the buffer. Deleted lines may be
recovered with the undo command (\fIu\fR; see below).
.B
Current
is the line after the last addressed line deleted.
.TP 5
e [filename]
Edit the new file `filename'. The
.B buffer
is cleared and the new file is placed in the
.BR buffer .
If the
.B buffer
has been modified since the last write command
.I ed
will issue a warning (`?'); a second issuing of
the command will be obeyed regardless.
The number of characters read is printed (unless -s is specified
at startup). If `filename' is missing, the remembered
name is used.
If `filename' is lead by ! then it shall be interpreted as a shell
command from which the output will be used as a non-remembered name.
Undo will not restore the
.B buffer
to its state before the edit command.
.B Current
is the last line in the
.B buffer
(`$').
.TP 5
E [filename]
.I E
works the same as
.I e
except if the buffer has been modified no warning is issued.
.TP 5
f [filename]
Print the
.BR "remembered filename" .
If `filename' is specified the
.B "remembered filename"
will be set to `filename'.
If `filename' is lead by ! then it shall be interpreted as a shell
command from which the output will be used as a non-remembered name.
.B Current
is unchanged.
.TP 5
(1,$)\|g/regular expression/command list
The global command first marks all lines matching
the regular expression.
For each matching line, the
command list is executed. At the start of each command list execution,
\fBcurrent\fR is set to equal that line; \fBcurrent\fR may change
as each command in the command list is executed for that line.
The first command of the command list begins on the same line as
the global command.
Generally, in the command list one command occupies a line. Thus to
have multiple commands in the command list it is necessary to escape the
<newline> at the end of each line so that the global command does not
interpret it as an indication that the command list entry has ended.
The <newline> is escaped by proceeding it with a backslash (\e).
Similarly with the commands that set \fIed\fR into input mode the <newlines>
of the entered text need to be escaped. If the `.' used to end input mode
is the last line of the command list the <newline> following the `.' need
not be escaped, or the `.' may be omitted entirely.
Commands in the command list can affect any line in the buffer.
For the behaviour of each \fIed\fR command within a command list refer to the
information on the individual command.
The commands
.IR g ,
.IR G ,
.IR v ,
.IR V ,
and \fI!\fR
are permitted in the command list, but should be used with caution.
The command list defaults to 
.I p
if left empty (i.e. g/RE/p).
For the regular expression the delimiters can be any characters except
for <space> and <newline>; delimiters within a regular expression can
be escaped with a backslash preceeding it.
.TP 5
(1,$)\|G/regular expression/
.br
The interactive global command works similar to \fIg\fR. The first step
is to mark every line which matches the given regular expression.
For every line matched it will print this line, set \fBcurrent\fR
to this line, and accept one command (not including \fIa\fR, \fIc\fR, \fIi\fR, \fIg\fR, \fIG\fR, \fIv\fR, and \fIV\fR)
for execution.
The command can affect any line in the buffer. `%' by itself executes
the last non-null command.
A return by itself will act as a null command. \fBCurrent\fR
will be set to the last line affected by the last successful command
input. If no match or an input command error occurs \fBcurrent\fR
will be set to the last line searched by \fIG\fR. \fIG\fR can be prematurely
ended by `ctrl-C' (SIGINT).

.TP 5
h
.br
The help command displays a message explaining the most recent command
error (indicated by `?'). \fBCurrent\fR is unchanged.
.TP 5
H
.br
This toggles on or off the automatic display of messages explaining
the most recent command error in place of `?'. \fBCurrent\fR is
unchanged.
.TP 5
.RB (\|.\|)\|i
.TP 5
<text>
.br
.TP 5
.B .
.br
The insert command places
.I ed
in input mode with the text being placed before the
addressed line. Line 0 is invalid for this command.
A `.' in the first column
followed immediately by a return places
.I ed
back in command mode - the `.' is not included in the text.
.B Current
is the last line inserted. If no text is inserted then
.B current
is the addressed when
.I ed
is compiled for POSIX; compiled for BSD,
.B current
is the addressed line -1.
.TP 5
.RB (\|.\|,\|.+1)\|j
The join command joins the addressed lines together to make one
line. If no addresses are specified
.B current
and
.BR current +1
lines are joined.
If one address only is given then
no join is performed.
.B Current
becomes that line if
.I ed
has been compiled under the BSD option; if compiled under the POSIX
option
.B current
is unchanged.
.TP 5
( \fB. \fR)\|k\fBx\fR
The mark command marks the addressed line with label
.BR x ,
where
.B x
is a lowercase letter from the portable character set (a-z).
The address form \fB`x\fR will refer to
this line (address form 6 above).
.B Current
is unchanged.
.TP 5
.RB (\|.\|,\|.\|)\|l
The list command
prints the addressed lines in an unambiguous way:
non-graphic characters are
printed in three-digit octal preceded by a \e
unless they are one of the following in which case they will be printed
as indicated in the brackets:
backslash (`\e\\'),
horizontal tab (\et), form feed (\ef).
return (\er), vertical tab (\ev), and backspace (\eb).
Long lines will be broken base on the type of terminal currently in
use.
.B Current
is set to the last line printed.
The
.I l
command may be placed on the same line after any
command except (\fIe\fR, \fIE\fR, \fIf\fR, \fIq\fR, \fIQ\fR, \fIr\fR, \fIw\fR, \fIW\fR, or \fI!\fR).
.TP 5
.RB (\|.\|,\|.\|)\|m\fBa\fR
The move command moves the addressed lines in the buffer
to after the address
.BR a .
Line 0 is valid for this command.
.B Current
is the location in the
.B buffer
of the last line moved.
.TP 5
.RB (\|.\|,\|.\|)\|n
The number command prints the addressed lines preceding the text with the line number.
The
.I n
command
may
be placed on the same line after any command
except (\fIe\fR, \fIE\fR, \fIf\fR, \fIq\fR, \fIQ\fR, \fIr\fR, \fIw\fR, \fIW\fR, or \fI!\fR).
.B Current
is the last line printed.
.TP 5
.RB (\|.\|,\|.\|)\|p
The print command prints the addressed lines.
The
.I p
command
may
be placed on the same line after any command
except (\fIe\fR, \fIE\fR, \fIf\fR, \fIq\fR, \fIQ\fR, \fIr\fR, \fIw\fR, \fIW\fR, or \fI!\fR).
.B Current
is the last line printed.
.TP
.RB (\|.\|,\|.\|)\|P
This command is a synonym for
.I p
if
.I ed
has been compiled under the BSD option. If
.I ed
has been compiled under the POSIX option then the prompt is toggled on or off.
.B Current
is unchanged when compiled under the POSIX option.
The default prompt is "*" if not specified with the \-p option at startup.
The prompt is initially off unless the \-p option is specified.
.TP 5
q
The quit command causes
.I ed
to exit. If the
.B buffer
has been modified since the last write command
.I ed
will
issue a warning once (`?'); a second issuing of the command will be obeyed
regardless.
.TP 5
Q
.I Q
works the same as
.I q
except if the buffer has been modified no warning is issued.
.TP 5
($)\|r [filename]
The read command reads in the file `filename' after the
addressed line. If no `filename' is specified then the
.B "remembered filename"
is used. Address 0 is valid for this command.
If read is successful then the number of characters
read is printed (unless the -s option is specified).
If `filename' is lead by ! then it shall be interpreted as a shell
command from which the output will be used as a non-remembered name.
.B Current
is the last line read.
.TP 5
(\| \fB.\fR\|, \fB.\fR\|)\|s/regular expression/\fBreplacement\fR/\fBflags\fR
.br
The substitute command searches for the regular expression in the
addressed lines.
On each line in which a match is found,
matched strings are replaced by the \fBreplacement\fR as specified
by the \fBflags\fR (see below).
If no \fBflags\fR appear, by default only the first occurrence
of the matched string in each line is replaced.
It is an error if no matches to the RE occur.
.IP
The delimiters may be any character except <space> or <newline>.
The delimiter lead by a \e will escape it to be a literal
in the RE or
.BR replacement .
.IP
An ampersand, `&', appearing in the replacement
will equal the string matching the RE.
The `&'s special meaning is supressable by leading
it with a `\e'.
When `%' is the only replacement character in
.B replacement
the most recent
replacement is used.
The `%'s special meaning is supressable by leading
it with a `\e'.
.IP
The characters `\fB\en\fR' (where \fBn\fR is a digit 1-9) is
replaced by the text matching the RE subexpression
.B n
(known as backreferencing).
.I S
may be used to break lines by including a <newline> in
.B replacement
preceeded by a backslash (`\e') to escape it.
.B Replacement
can continue on the next line and can include another escaped <newline>.
.IP
The following extention should not be included in portable scripts.
When spliting lines using \fIs\fR with the global commands (\fIg\fR,
\fIG\fR, \fIv\fR, or \fIV\fR) the new-line in the replacement string
must be escaped by preceding it with `\e\e\e' (three adjacent `\e'\|s \-
the first \e escapes the second \e so that it is passed to \fIs\fR
to escape the <newline>).
.IP
The \fBflags\fR may be any combination of:
.RS
.IP \fIcount\fR
in each addressed line replace the \fIcount\fR\-th matching occurrence.
.IP g
in each addressed line replace all matching occurrences. When \fIcount\fR and
g are specified together inclusively replace in each addressed line
all matches from the \fIcount\fR\-th match to the end of line.
.IP l
write the line after replacement in the manner specified by the \fIl\fR
command.
.IP n
write the line after replacement in the manner specified by the \fIn\fR
command.
.IP p
write the line after replacement in the manner specified by the \fIp\fR
command.
.RE
.IP
The following special form
should not be included in portable scripts.
This form is maintained for backward compatibility and
is extended to dovetail into the above forms of
.BR s .
.I S
followed by
.I no
delimiters
repeats the most recent substitute command
on the addressed lines.
.I S
may be suffixed with the letters
.BR r " (use the most recent RE rather than the last RE used with \fIs\fR),"
.B p
(complement the setting of the
any print command (l, n, p)
suffix from the previous substitution),
.B g
(complement the setting of the
.I g
suffix) or
.B N
(negate the previous \fIcount\fR flag).
These modifying letters may be combined in any order
(N.B. multiple use of the modifying letters may cause them
to be interpreted as delimiters).
.IP
.B Current
is set to the last line search (BSD) or where the last replacement
occurred (POSIX).
.TP 5
.RB (\|.\|,\|.\|)\|t\|\fBa\fR
The transcribe command copies the addressed lines in
the
.B buffer
to after the address
.BR a .
Address 0 is valid for this command.
.B Current
is the last line transcribed.
.TP 5
.RB (\|.\|,\|.\|)\|u
The undo command nullifies the most recent
.B buffer
modifying command.
Buffer modifying commands undo works on are
.IR a ,
.IR c ,
.IR d ,
.IR g ,
.IR G ,
.IR i ,
.IR j ,
.IR m ,
.IR r ,
.IR s ,
.IR t ,
.IR u ,
.IR v ,
and
.I V.
Marks set by the \fIk\fR command will also be restored.
All commands (including nested \fIg\fR, \fIG\fR, \fIv\fR, and
\fIV\fR commands within the \fIg\fR or \fIv\fR)
that undo works on are treated as a single buffer modification.
\fBCurrent\fR is set to the line it addressed before the last
buffer modification.
.TP 5
(1, $)\|v/regular expression/command list
The global non-matching command performs as the
.I g
command does except that the command list is executed for every line
that does not match the RE.
.TP 5
(1, $)\|V/regular expression/
The interactive global non-matching command is the same as the
.I G
except that one command will be accepted as input
with \fBcurrent\fR initially set to every line
that does not match the RE.
.TP 5
(1, $)\|w [filename]
.br
The write command writes the addressed lines to the file `filename'.
If no `filename' is specified then the
.B "remembered filename"
is used. If no addresses are specified the whole
.B buffer
is written.
If the command is successful, the number of characters written is
printed (unless the -s option is specified).
If `filename' is lead by ! then it shall be interpreted as a shell
command from which the output will be used as a non-remembered name.
\fBCurrent\fR is unchanged.
.TP
(1, $)\|W [filename]
.I W
works as the
.I w
command does except the addressed contents of the
.B buffer
are appended to `filename' (or the
.B "remember filename"
if `filename' is not specified).
\fBCurrent\fR is unchanged.
.TP 5
(1, $)\|wq [filename]
.I wq
works as the
.I w
command does with the addition that
.I ed
exits immediately after the write is complete.
\fBCurrent\fR is unchanged.
.TP 5
(1,$)\|Wq [filename]
.I Wq
works as the
.I W
command does with the addition that
.I ed
exits immediately after the write is complete.
\fBCurrent\fR is unchanged.
.TP 5
.RB (\|.\|+1)\|z\ \ \ \ or,
.br
.TP 5
.RB (\|.\|+1)\|z\fBn\fR
Scroll through the
.BR buffer .
Starting from the addressed line (or
.BR current +1)
print the next 22 (by default or
.BR n )
lines. The
.B n
is a sticky value; it becomes the default number of lines printed
for successive scrolls.
.B Current
is the last line printed.
.TP 5
($)\|=
Print the number of lines in the
.BR buffer .
If an address is provided (in the forms 1-8 above) then the line number
for that line will be printed.
\fBCurrent\fR is unchanged.
.TP 5
!<shell command>
The command after the
.I !
is executed by \fIsh(1)\fR and the results are printed. A `!' is
printed in the first column when execution has completed (unless the -s
option has been specified).
A `!' after \fI!\fR repeats the last shell command. An unescaped `%'
represents the remembered pathname.
\fBCurrent\fR is unchanged.
.TP 5
/regular expression/\|\|\|\|\|or,
.br
.TP 5
?regular expression?
.br
The search command searches forward, `/', (or backward, `?') through the
.B buffer
attempting to find
a line that matches the RE. The search will wrap to the top  (or bottom)
of the
.B buffer
if necessary. Search returns the line number that the match occurs on -
combined with the null command (see below) this causes the line to be printed.
.B Current
is the matching line.
.TP 5
.RB (\|.+1,\|.+1)\|<newline>
.br
The null command is equivalent to asking for the line
.BR current +1
to be printed according to the
.I p
command. This is a useful command to quickly print the next couple of
lines. If more than a couple of lines are needed the
.I z
command (see above) is much better to use. 
\fBCurrent\fR is the last line printed.

.SH OTHER
.PP
If an interrupt signal (SIGINT)\| is sent,
.I ed
prints `?'
and returns to command mode.
.PP
BSD command pairs (pp, ll, etc.) are permitted. Additionally any single
print command may follow any of the non-I/O commands (I/O commands:
e, E, f, r, w, W, wq, and !). This will cause the current line to be
printed in the specified manner after the command has completed.
.PP
Previous limitations on the number of characters per line and per command
list have been lifted; there is now no maximum.
File name and path length is restricted to the maximum length that
the current file system supports.
The
.I undo
command now restores marks to affected lines.
The temporary buffer method will vary dependent on the method selected at
compile. Two methods work with a temporary file (stdio and db), while the
third uses memory.
The limit on the number of lines depends on the amount of memory.
.SH FILES
/tmp/_bsd44_ed*
.br
.XP
ed.hup: the buffer is written to this file in the current
directory if possible and in the HOME directory is not
(if the signal SIGHUP (hangup) is received).
.SH "SEE ALSO"
B. W. Kernighan,
.I
A Tutorial Introduction to the ED Text Editor
.br
B. W. Kernighan,
.I
Advanced editing on UNIX
.br
regex(7), sed(1), learn(1), ex(1), POSIX 1003.2 (4.20)
.SH "AUTHOR"
Rodney Ruddock
.SH DIAGNOSTICS
`?name' for a file that is either inaccessible, does not exist, or is
a directory. `?'
for all other errors unless the help messages have been toggled on (with
the H command) in which case a descriptive message will be printed.
.PP
All NULL characters are ignored during input from the user or files.
EOF is treated as a newline so that characters after the last <newline>
are included into the \fBbuffer\fR.
.PP
.I Ed
returns 0 on successful completion. A value >0 is returned
when an \fIed\fR command failed.
.SH NOTES
.PP
Regular expressions are now described on regex(7).
.I Ed
follows basic regular expressions (BRE's) as described on regex(7).
BRE's, for the most part, are the same as previous
.I ed
RE's. The changes to the RE's are extension for internationalization
under POSIX 1003.2. Old scripts with RE's should work without
modification.
.PP
The special form of substitute has been maintained for backward
compatability and should not be used in scripts if they are to
portable.
.PP
Help messages may appear ambiguous to beginners - particularly when BRE's
form part of the command.
.PP
For backward compatability, when more addresses are provided
than required by a command the one or two addresses closest to the
command are used (depending on how may addresses the command accepts).
Portable scripts should not rely on this feature.
.PP
For backward compatibility the option `-' is
equivalent to the `-s' option at the startup of
.IR ed .