doc/pod/sm.pod

   1 =head1 NAME
   2
   3 sm - Command-line interface to the INN storage manager
   4
   5 =head1 SYNOPSIS
   6
   7 B<sm> [B<-dHiqRrS>] [I<token> ...]
   8
   9 =head1 DESCRIPTION
  10
  11 The INN storage manager is the subsystesm that stores and keeps track of
  12 all of the articles and what storage backend they're in.  All stored
  13 articles are assigned a storage API token.  B<sm> is a command-line
  14 interface to that storage manager, primarily used to retrieve articles by
  15 those tokens but also to perform other operations on the storage
  16 subsystem.
  17
  18 I<token> is the token of an article (the same thing that's returned by
  19 B<grephistory> or stored in the history file).  It looks something like:
  20
  21     @0502000005A4000000010000000000000000@
  22
  23 Any number of tokens can be given on the command line.  If none are, B<sm>
  24 reads tokens from standard input, one per line.  The default operation is
  25 to retrieve and write to standard output the corresponding article for
  26 each token given.
  27
  28 =head1 OPTIONS
  29
  30 =over 4
  31
  32 =item B<-d>, B<-r>
  33
  34 Rather than retrieving the specified article, remove the article.  This
  35 will delete the article out of the news spool and it will not subsequently
  36 be retrievable by any part of INN.  It's equivalent to C<ctlinnd cancel>
  37 except it takes a storage API token instead of a message ID.
  38
  39 =item B<-H>
  40
  41 Retrieve only the header of the article rather than the entire article.
  42 This option cannot be used with B<-d>, B<-r>, B<-i>, or B<-S>.
  43
  44 =item B<-i>
  45
  46 Show the newsgroup name and article number associated with the token
  47 rather than the article itself.  Note that for crossposted articles, only
  48 the first newsgroup and article number to which the article is associated
  49 will be returned.
  50
  51 =item B<-q>
  52
  53 Suppress all error messages except usage errors.
  54
  55 =item B<-R>
  56
  57 Display the raw article.  This means that line endings won't be converted
  58 to native line endings and will be left as CRLF sequences, leading periods
  59 will still be escaped for sending over NNTP, and the article will end in
  60 a CRLF.CRLF sequence.
  61
  62 =item B<-S>
  63
  64 Write the article to standard output in the format used by rnews spool
  65 files.  Multiple articles can be written in this format, and the resulting
  66 output can be fed to rnews (on another system, for example) to inject
  67 those articles into INN.  This option cannot be used with B<-d>, B<-r>,
  68 B<-H>, B<-i>, or B<-R>.
  69
  70 =back
  71
  72 =head1 EXIT STATUS
  73
  74 If all operations were successful, B<sm> exits with status 0.  If an
  75 operation on any of the provided tokens fails, B<sm> will exit with status
  76 1, even if the operations on other tokens were successful.  In other
  77 words, if twenty tokens are fed to C<sm -r> on stdin, 19 articles were
  78 successfully removed, but the sixth article couldn't be found, B<sm> will
  79 still exit with status 1.
  80
  81 This means that if you need to be sure whether a particular operation
  82 succeeded, you should run sm on one token at a time.
  83
  84 =head1 HISTORY
  85
  86 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
  87 Rewritten in POD by Russ Allbery <rra@stanford.edu>.
  88
  89 $Id: sm.pod 6683 2004-03-06 18:31:58Z rra $
  90
  91 =head1 SEE ALSO
  92
  93 ctlinnd(8), grephistory(1), history(5), rnews(1), storage.conf(5).
  94
  95 =cut