1 \cfg{man-identity}{nntpid}{1}{2004-11-21}{Simon Tatham}{Simon Tatham}
3 \title Man page for \cw{nntpid}
7 \cw{nntpid} - retrieve a single article from a news server
11 \c nntpid [ -v ] [ -d ] article [ article... ]
12 \e bbbbbb bb bb iiiiiii iiiiiii
13 \c nntpid [ -v ] [ -d ]
15 \c nntpid [ -v ] -a newsgroup-name
16 \e bbbbbb bb bb iiiiiiiiiiiiii
20 \cw{nntpid} makes a connection to a news server, retrieves one or
21 more articles, and displays them.
23 You can specify the article you want by either:
25 \b giving its Message-ID. Message-IDs are globally unique, so you
26 don't need to know which newsgroup the article was in. Also, they do
27 not vary between news servers.
29 \b giving a newsgroup name and an article number within that
30 newsgroup. Article numbers are assigned internally by a particular
31 news server, so they will be different on other servers carrying the
34 By default, \cw{nntpid} will try to display the article using a
35 pager (\cw{more}(1), unless you have specified an alternative in the
36 environment variable \cw{PAGER}). This is partly for convenience,
37 and partly a mild security measure: it gives you some protection
38 against the news article potentially containing control sequences
39 that cause unexpected behaviour in your terminal. If \cw{nntpid}
40 detects that its standard output is not a terminal, however, it will
41 bypass the pager and just write out the article directly.
43 There are a couple of alternative mode of operation. In one, enabled
44 by the \cw{-a} option, \cw{nntpid} retrieves \e{all} available
45 articles in the group and writes them to standard output in \cw{mbox}
46 format. In the other, enabled with \cw{-b}, \cw{nntpid} simply prints
47 the lowest and highest article numbers currently available in that
48 group from the news server.
50 The location of the news server is obtained by reading the
51 environment variable \cw{NNTPSERVER}, or failing that the file
56 \cw{nntpid} will attempt to interpret its argument list as specifying
57 a series of news articles, as follows:
59 \b An argument containing an @ sign will be parsed as a Message-ID.
60 The angle brackets that usually delimit Message-IDs are optional;
61 \cw{nntpid} will strip them off if it sees them, and will not complain
62 if it does not. If the angle brackets are present, anything outside
63 them will also be discarded.
65 \b Otherwise, an argument containing whitespace or a colon will be
66 parsed as a group name and an article number.
68 \b Otherwise, two successive arguments will be treated as a group name
69 and an article number.
71 For example, the following invocations should all behave identically.
72 (Single quotes are intended to represent POSIX shell quoting, not part
73 of the command line as it reaches \cw{nntpid}.)
75 \c $ nntpid '<foo.bar@baz.quux>' misc.test 1234
76 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
77 \c $ nntpid 'foo.bar@baz.quux' misc.test:1234
78 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
79 \c $ nntpid 'wibble <foo.bar@baz.quux> blah' 'misc.test 1234'
80 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
82 If \cw{nntpid} is given no arguments at all, it will read from
83 standard input. Every line it reads will be interpreted as described
84 above, except that whitespace will also be trimmed from the start and
85 end of the line first.
87 If you provide the \cw{-a} option (see below), none of the above
88 applies. Instead, \cw{nntpid} will expect exactly one command-line
89 argument, which it will treat as a newsgroup name.
95 \dd Verbose mode. In this mode, \cw{nntpid} will log its entire
96 conversation with the news server on standard error.
100 \dd Direct output. In this mode, \cw{nntpid} will write the article
101 straight to standard output without bothering to try using a pager.
105 \dd Retrieve all articles from the given newsgroup. In this mode,
106 \cw{nntpid} will always write straight to standard output (so the
107 \cw{-d} option is unnecessary).
111 \dd Print the current bounds on that group's article numbers. The
112 output is one line consisting of a minimum and maximum article number.
113 (Not every article in that range will necessarily actually exist: a
114 cancelled article will still use up a space in the numbering range.)
118 Currently, the only form of authentication supported by \cw{nntpid}
119 is \cw{AUTHINFO GENERIC}, using the environment variable
120 \cw{NNTPAUTH}. It will only attempt this if it receives a 480
121 response from the news server; if your news server never sends 480
122 then \cw{nntpid} will never even look at \cw{NNTPAUTH}.
126 \cw{nntpid} is free software, distributed under the MIT licence.
127 Type \cw{nntpid --licence} to see the full licence text.