=head1 NAME

sm - Command-line interface to the INN storage manager

=head1 SYNOPSIS

B<sm> [B<-cdHiqRrSs>] [I<token> ...]

=head1 DESCRIPTION

The INN storage manager is the subsystem that stores and keeps track of
all of the articles and what storage backend they're in.  All stored
articles are assigned a storage API token.  B<sm> is a command-line
interface to that storage manager, primarily used to retrieve articles by
those tokens but also to perform other operations on the storage
subsystem.

I<token> is the token of an article (the same thing that's returned by
B<grephistory> or stored in the F<history> file).  It looks something like:

    @0502000005A4000000010000000000000000@

Any number of tokens can be given on the command-line for any function
other than B<-s>.  If none are, B<sm> normally reads tokens from standard
input, one per line.  The default operation is to retrieve and write to
standard output the corresponding article for each token given.

If B<-s> is given, B<sm> instead stores the article given on standard
input (in native format, unless B<-R> is given, in which case wire
format is expected) using the standard rules of the storage subsystem.
If the article is stored successfully, the token of the article is
printed to standard output.  Please note that this does not make any
attempt to write a history entry or any overview data, and is therefore
only useful under very specific circumstances.

=head1 OPTIONS

=over 4

=item B<-c>

Show a clear, decoded form of the storage API token.  Each part of the token
is explained, in a human-readable string.  Amongst other elements, this
command gives the path to where the corresponding article is supposed
to be stored.

=item B<-d>, B<-r>

Rather than retrieving the specified article, remove the article.  This
will delete the article out of the news spool and it will not subsequently
be retrievable by any part of INN.  It's equivalent to C<ctlinnd cancel>
except it takes a storage API token instead of a message-ID.

When the I<expiretombstone> setting in F<inn.conf> is true, B<sm -r>
also appends the cancelled token to F<cancels.tombstone> in I<pathdb>
so that a later B<expire> run can drop the corresponding history entry
without a per-article storage check.  Append failures are logged
but do not affect the cancellation itself.  See inn.conf(5) under
I<expiretombstone> for the full mechanism.

=item B<-H>

Retrieve only the headers of the article rather than the entire article.
This option cannot be used with B<-d>, B<-r>, B<-i>, or B<-S>.

=item B<-i>

Show the newsgroup name and article number associated with the token
rather than the article itself.  Note that for crossposted articles, only
the first newsgroup and article number to which the article is associated
will be returned.

=item B<-q>

Suppress all error messages except usage errors.

=item B<-R>

Display the raw article.  This means that line endings won't be converted
to native line endings and will be left as CRLF sequences; leading periods
will still be escaped for sending over NNTP, and the article will end in
a CRLF.CRLF sequence.

When used with B<-s>, read articles in wire format.

=item B<-S>

Write the article to standard output in the format used by B<rnews> spool
files.  Multiple articles can be written in this format, and the resulting
output can be fed to B<rnews> (on another system, for example) to inject
those articles into INN.  This option cannot be used with B<-d>, B<-r>,
B<-H>, B<-i>, or B<-R>.

=item B<-s>

Store the article given on standard input using the normal storage
rules for articles as configured in storage.conf(5).  Print the new
token for the message to standard output if it is stored successfully.
If this option is given, no other options except B<-R> and possibly B<-q>
should be given.  When B<-R> is given, any number of articles in wire
format are read on standard input and stored.

=back

=head1 EXIT STATUS

If all operations were successful, B<sm> exits with status 0.  If an
operation on any of the provided tokens fails, B<sm> will exit with status
1, even if the operations on other tokens were successful.  In other
words, if twenty tokens are fed to C<sm -r> on stdin, 19 articles were
successfully removed, but the sixth article couldn't be found, B<sm> will
still exit with status 1.

This means that if you need to be sure whether a particular operation
succeeded, you should run B<sm> on one token at a time.

=head1 HISTORY

Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
Rewritten in POD by Russ Allbery <eagle@eyrie.org>.

=head1 SEE ALSO

ctlinnd(8), grephistory(1), history(5), rnews(1), storage.conf(5).

=cut
