| 1 | \cfg{man-identity}{nntpid}{1}{2004-11-21}{Simon Tatham}{Simon Tatham} |
| 2 | |
| 3 | \title Man page for \cw{nntpid} |
| 4 | |
| 5 | \U NAME |
| 6 | |
| 7 | \cw{nntpid} - retrieve a single article from a news server |
| 8 | |
| 9 | \U SYNOPSIS |
| 10 | |
| 11 | \c nntpid [ -v ] [ -d ] article [ article... ] |
| 12 | \e bbbbbb bb bb iiiiiii iiiiiii |
| 13 | \c nntpid [ -v ] [ -d ] |
| 14 | \e bbbbbb bb bb |
| 15 | \c nntpid [ -v ] -a newsgroup-name |
| 16 | \e bbbbbb bb bb iiiiiiiiiiiiii |
| 17 | |
| 18 | \U DESCRIPTION |
| 19 | |
| 20 | \cw{nntpid} makes a connection to a news server, retrieves one or |
| 21 | more articles, and displays them. |
| 22 | |
| 23 | You can specify the article you want by either: |
| 24 | |
| 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. |
| 28 | |
| 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 |
| 32 | same group. |
| 33 | |
| 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. |
| 42 | |
| 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. |
| 49 | |
| 50 | The location of the news server is obtained by reading the |
| 51 | environment variable \cw{NNTPSERVER}, or failing that the file |
| 52 | \cw{/etc/nntpserver}. |
| 53 | |
| 54 | \U ARGUMENTS |
| 55 | |
| 56 | \cw{nntpid} will attempt to interpret its argument list as specifying |
| 57 | a series of news articles, as follows: |
| 58 | |
| 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. |
| 64 | |
| 65 | \b Otherwise, an argument containing whitespace or a colon will be |
| 66 | parsed as a group name and an article number. |
| 67 | |
| 68 | \b Otherwise, two successive arguments will be treated as a group name |
| 69 | and an article number. |
| 70 | |
| 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}.) |
| 74 | |
| 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 |
| 81 | |
| 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. |
| 86 | |
| 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. |
| 90 | |
| 91 | \U OPTIONS |
| 92 | |
| 93 | \dt \cw{-v} |
| 94 | |
| 95 | \dd Verbose mode. In this mode, \cw{nntpid} will log its entire |
| 96 | conversation with the news server on standard error. |
| 97 | |
| 98 | \dt \cw{-d} |
| 99 | |
| 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. |
| 102 | |
| 103 | \dt \cw{-a} |
| 104 | |
| 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). |
| 108 | |
| 109 | \dt \cw{-b} |
| 110 | |
| 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.) |
| 115 | |
| 116 | \U AUTHENTICATION |
| 117 | |
| 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}. |
| 123 | |
| 124 | \U LICENCE |
| 125 | |
| 126 | \cw{nntpid} is free software, distributed under the MIT licence. |
| 127 | Type \cw{nntpid --licence} to see the full licence text. |
| 128 | |
| 129 | \versionid $Id$ |