chiark / gitweb /
option for no inotify; manpage fix
[innduct.git] / doc / man / sm.1
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "SM 1"
132 .TH SM 1 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
133 .SH "NAME"
134 sm \- Command\-line interface to the INN storage manager
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 \&\fBsm\fR [\fB\-dHiqRrS\fR] [\fItoken\fR ...]
138 .SH "DESCRIPTION"
139 .IX Header "DESCRIPTION"
140 The \s-1INN\s0 storage manager is the subsystesm that stores and keeps track of
141 all of the articles and what storage backend they're in.  All stored
142 articles are assigned a storage \s-1API\s0 token.  \fBsm\fR is a command-line
143 interface to that storage manager, primarily used to retrieve articles by
144 those tokens but also to perform other operations on the storage
145 subsystem.
146 .PP
147 \&\fItoken\fR is the token of an article (the same thing that's returned by
148 \&\fBgrephistory\fR or stored in the history file).  It looks something like:
149 .PP
150 .Vb 1
151 \&    @0502000005A4000000010000000000000000@
152 .Ve
153 .PP
154 Any number of tokens can be given on the command line.  If none are, \fBsm\fR
155 reads tokens from standard input, one per line.  The default operation is
156 to retrieve and write to standard output the corresponding article for
157 each token given.
158 .SH "OPTIONS"
159 .IX Header "OPTIONS"
160 .IP "\fB\-d\fR, \fB\-r\fR" 4
161 .IX Item "-d, -r"
162 Rather than retrieving the specified article, remove the article.  This
163 will delete the article out of the news spool and it will not subsequently
164 be retrievable by any part of \s-1INN\s0.  It's equivalent to \f(CW\*(C`ctlinnd cancel\*(C'\fR
165 except it takes a storage \s-1API\s0 token instead of a message \s-1ID\s0.
166 .IP "\fB\-H\fR" 4
167 .IX Item "-H"
168 Retrieve only the header of the article rather than the entire article.
169 This option cannot be used with \fB\-d\fR, \fB\-r\fR, \fB\-i\fR, or \fB\-S\fR.
170 .IP "\fB\-i\fR" 4
171 .IX Item "-i"
172 Show the newsgroup name and article number associated with the token
173 rather than the article itself.  Note that for crossposted articles, only
174 the first newsgroup and article number to which the article is associated
175 will be returned.
176 .IP "\fB\-q\fR" 4
177 .IX Item "-q"
178 Suppress all error messages except usage errors.
179 .IP "\fB\-R\fR" 4
180 .IX Item "-R"
181 Display the raw article.  This means that line endings won't be converted
182 to native line endings and will be left as \s-1CRLF\s0 sequences, leading periods
183 will still be escaped for sending over \s-1NNTP\s0, and the article will end in
184 a \s-1CRLF\s0.CRLF sequence.
185 .IP "\fB\-S\fR" 4
186 .IX Item "-S"
187 Write the article to standard output in the format used by rnews spool
188 files.  Multiple articles can be written in this format, and the resulting
189 output can be fed to rnews (on another system, for example) to inject
190 those articles into \s-1INN\s0.  This option cannot be used with \fB\-d\fR, \fB\-r\fR,
191 \&\fB\-H\fR, \fB\-i\fR, or \fB\-R\fR.
192 .SH "EXIT STATUS"
193 .IX Header "EXIT STATUS"
194 If all operations were successful, \fBsm\fR exits with status 0.  If an
195 operation on any of the provided tokens fails, \fBsm\fR will exit with status
196 1, even if the operations on other tokens were successful.  In other
197 words, if twenty tokens are fed to \f(CW\*(C`sm \-r\*(C'\fR on stdin, 19 articles were
198 successfully removed, but the sixth article couldn't be found, \fBsm\fR will
199 still exit with status 1.
200 .PP
201 This means that if you need to be sure whether a particular operation
202 succeeded, you should run sm on one token at a time.
203 .SH "HISTORY"
204 .IX Header "HISTORY"
205 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
206 Rewritten in \s-1POD\s0 by Russ Allbery <rra@stanford.edu>.
207 .PP
208 $Id: sm.1 7880 2008-06-16 20:37:13Z iulius $
209 .SH "SEE ALSO"
210 .IX Header "SEE ALSO"
211 \&\fIctlinnd\fR\|(8), \fIgrephistory\fR\|(1), \fIhistory\fR\|(5), \fIrnews\fR\|(1), \fIstorage.conf\fR\|(5).