=for comment $Id: edinplace.pod,v 1.12 2006/02/12 22:31:12 dm Exp $

=head1 NAME

edinplace - edit a file in place

=head1 SYNOPSIS

edinplace [--error=I<code>] [[--file=I<file>] I<command> [I<arg> ...]]

=head1 DESCRIPTION

edinplace runs I<command> with its input from I<file> (or standard
input by default), and then replaces the contents of I<file> with the
output of I<command>.  To the extent possible, edinplace attempts to
exit with the same status as I<command>.

If edinplace is run on standard input (no B<--file> option), it must
inherit a file descriptor 0 that is open for both reading and writing.
When processing standard input, if edinplace does not encounter a
fatal error, it rewinds its standard input to offset 0 before exiting.
Thus, a script can first run B<edinplace> I<command>, then run another
filter command such as B<grep>, and the resulting output will be the
output of grep on I<command>'s output.

If no I<command> is specified, edinplace just rewinds its standard
input to file offset 0.  In this case, it is an error to supply the
B<--file> option.  Of course, rewinding only works when standard input
is a real file (as opposed to a pipe or device).

There are two options:

=over

=item B<--error=>I<code> (B<-x> I<code>)

Ordinarily, edinplace attempts to exit with the same status as
I<command>.  However, if edinplace encounters some fatal error (such
as being unable to execute I<command>), it will exit with status
I<code>.  The default value is 1.  The range of valid exit codes is
1-255, inclusive.


=item B<--file=>I<file> (B<-f> I<file>)

Specifies that I<file> should be edited.  Otherwise, edinplace will
edit its standard input (which must be opened for both reading and
writing).

=item B<--skipfrom>

Skip the first line of the file if it starts "From ".  If edinplace is
run without a command, positions the file offset at the start of the
second line of the file.  If edinplace is run with a command, then the
first line of the file is neither fed to the command, nor overwritten.
This option is useful for running edinplace over mail files, which
sometimes start with a "From " line specifying the envelope sender of
the message.  Since "From " is not part of the message header, just a
Unix convention, some programs are confused by the presence of that
line.  Note that if you specify a command, then edinplace resets the
file offset to 0 upon exiting, even if the B<--skipfrom> option was
present.

=back

=head1 EXAMPLES

The following command prepends the string C<ORIGINAL: > to the
beginning of each line in text file F<message>:

=over

B<edinplace -f message sed -e 's/^/ORIGINAL: /'>

=back

The following command runs the B<spamassassin> mail filter program on
a mail message stored in file F<message>, replacing the contents of
F<message> with B<spamassassin>'s annotated output, and exiting with
code 100 if B<spamassassin> thinks the message is spam.  If edinplace
encounters any fatal errors, it will exit with code 111.

=over

B<edinplace -x 111 -f message spamassassin -e 100>

=back

(B<spamassassin> reads a mail message on standard input and outputs an
annotated copy of the message including information about whether or
not the message is likely to be spam and why.  The B<-e> option to
B<spamassassin> specifies what exit status B<spamassassin> should use
if the message appears to be spam; edinplace will use the same exit
code as the program it has run.)

To run spamassassin on incoming mail before accepting the mail from
the remote client, place the following line in an appropriate Mail
Avenger F<rcpt> file as the last command executed:

    bodytest edinplace -x 111 spamassassin -e 100

=head1 SEE ALSO

L<avenger(1)|avenger(1)>

The Mail Avenger home page: L<http://www.mailavenger.org/>.

=head1 BUGS

edinplace does not make a copy of the file being edited, but rather
overwrites the file as it is being processed.  At any point where
I<command> has produced more output than it has consumed input from
the file, edinplace buffers the difference in memory.  Thus, a
I<command> that outputs large amounts of data before reading the input
file can run edinplace out of memory.  (A program that outputs data as
it reads even a very large file should be fine, however.)

If I<command> crashes or malfunctions for any reason, you will likely
lose the input file, since edinplace will view this as a program that
simply outputs the empty file.

=head1 AUTHOR

David MaziE<egrave>res