1nntp(n)                     Tcl NNTP Client Library                    nntp(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       nntp - Tcl client for the NNTP protocol
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require nntp  ?0.2.1?
14
15       ::nntp::nntp ?host? ?port? ?nntpName?
16
17       nntpName method ?arg arg ...?
18
19       nntpName article ?msgid?
20
21       nntpName authinfo ?user? ?pass?
22
23       nntpName body ?msgid?
24
25       nntpName configure
26
27       nntpName configure option
28
29       nntpName configure option value ...
30
31       nntpName cget option
32
33       nntpName date
34
35       nntpName group ?group?
36
37       nntpName head ?msgid?
38
39       nntpName help
40
41       nntpName last
42
43       nntpName list
44
45       nntpName listgroup ?group?
46
47       nntpName mode_reader
48
49       nntpName newgroups since
50
51       nntpName newnews
52
53       nntpName newnews since
54
55       nntpName newnews group ?since?
56
57       nntpName next
58
59       nntpName post article
60
61       nntpName slave
62
63       nntpName stat ?msgid?
64
65       nntpName quit
66
67       nntpName xgtitle ?group_pattern?
68
69       nntpName xhdr field ?range?
70
71       nntpName xover ?range?
72
73       nntpName xpat field range ?pattern_list?
74
75______________________________________________________________________________
76

DESCRIPTION

78       The package nntp provides a simple Tcl-only client library for the NNTP
79       protocol.  It works by opening the standard NNTP socket on the  server,
80       and then providing a Tcl API to access the NNTP protocol commands.  All
81       server errors are returned as Tcl errors (thrown) which must be  caught
82       with the Tcl catch command.
83

COMMANDS

85       ::nntp::nntp ?host? ?port? ?nntpName?
86              The  command  opens  a  socket  connection to the specified NNTP
87              server and creates a new nntp object with an  associated  global
88              Tcl  command whose name is nntpName. This command may be used to
89              access the various NNTP protocol commands for  the  new  connec‐
90              tion.  The  default port number is "119" and the default host is
91              "news". These defaults can be overridden  with  the  environment
92              variables NNTPPORT and NNTPHOST respectively.
93
94              Some  of  the commands supported by this package are not part of
95              the nntp rfc 977 (http://www.rfc-editor.org/rfc/rfc977.txt)  and
96              will not be available (or implemented) on all nntp servers.
97
98              The access command nntpName has the following general form:
99
100              nntpName method ?arg arg ...?
101                     Option  and  the args determine the exact behavior of the
102                     command.
103
104       nntpName article ?msgid?
105              Query the server for article msgid from the current group.   The
106              article is returned as a valid tcl list which contains the head‐
107              ers, followed by a blank line, and then followed by the body  of
108              the  article.  Each element in the list is one line of the arti‐
109              cle.
110
111       nntpName authinfo ?user? ?pass?
112              Send authentication information (username and password)  to  the
113              server.
114
115       nntpName body ?msgid?
116              Query the server for the body of the article msgid from the cur‐
117              rent group.  The body of the article is returned as a valid  tcl
118              list.  Each  element  in the list is one line of the body of the
119              article.
120
121       nntpName configure
122
123       nntpName configure option
124
125       nntpName configure option value ...
126
127       nntpName cget option
128              Query and configure options of the nntp connection object.  Cur‐
129              rently  only one option is supported, -binary. When set articles
130              are retrieved as binary data instead of text. The  only  methods
131              affected by this are article and body.
132
133              One application of this option would be the download of articles
134              containing yEnc encoded images. Although  encoded  the  data  is
135              still  mostly  binary and retrieving it as text will corrupt the
136              information.
137
138              See package yencode for both encoder and decoder of such data.
139
140       nntpName date
141              Query the server for the servers current date.  The date is  re‐
142              turned in the format YYYYMMDDHHMMSS.
143
144       nntpName group ?group?
145              Optionally set the current group, and retrieve information about
146              the currently selected group.  Returns the estimated  number  of
147              articles  in the group followed by the number of the first arti‐
148              cle in the group, followed by the last  article  in  the  group,
149              followed by the name of the group.
150
151       nntpName head ?msgid?
152              Query  the  server for the headers of the article msgid from the
153              current group.  The headers of the article  are  returned  as  a
154              valid  tcl  list.  Each  element  in the list is one line of the
155              headers of the article.
156
157       nntpName help
158              Retrieves a list of the commands that are supported by the  news
159              server that is currently attached to.
160
161       nntpName last
162              Sets  the  current article pointer to point to the previous mes‐
163              sage (if there is one) and returns the msgid of that message.
164
165       nntpName list
166              Returns a tcl list of valid newsgroups and  associated  informa‐
167              tion.   Each newsgroup is returned as an element in the tcl list
168              with the following format:
169
170
171                    group last first p
172
173
174              where <group> is the name of the newsgroup, <last> is the number
175              of  the  last known article currently in that newsgroup, <first>
176              is the number of the first article currently in  the  newsgroup,
177              and  <p> is either 'y' or 'n' indicating whether posting to this
178              newsgroup is allowed ('y') or prohibited ('n').
179
180              The <first> and <last> fields will always be numeric.  They  may
181              have  leading zeros.  If the <last> field evaluates to less than
182              the <first> field, there are no articles currently  on  file  in
183              the newsgroup.
184
185       nntpName listgroup ?group?
186              Query  the  server  for a list of all the messages (message num‐
187              bers) in the group specified by the argument  group  or  by  the
188              current group if the group argument was not passed.
189
190       nntpName mode_reader
191              Query the server for its nntp 'MODE READER' response string.
192
193       nntpName newgroups since
194              Query  the  server  for a list of all the new newsgroups created
195              since the time specified by the argument  since.   The  argument
196              since  can  be any time string that is understood by clock scan.
197              The tcl list of newsgroups is returned in a similar form to  the
198              list of groups returned by the nntpName list command.  Each ele‐
199              ment of the list has the form:
200
201
202                    group last first p
203
204
205              where <group> is the name of the newsgroup, <last> is the number
206              of  the  last known article currently in that newsgroup, <first>
207              is the number of the first article currently in  the  newsgroup,
208              and  <p> is either 'y' or 'n' indicating whether posting to this
209              newsgroup is allowed ('y') or prohibited ('n').
210
211       nntpName newnews
212              Query the server for a list of new articles posted to  the  cur‐
213              rent group in the last day.
214
215       nntpName newnews since
216              Query  the  server for a list of new articles posted to the cur‐
217              rent group since the time specified by the argument since.   The
218              argument  since  can  be  any  time string that is understood by
219              clock scan.
220
221       nntpName newnews group ?since?
222              Query the server for a list of new articles posted to the  group
223              specified  by the argument group since the time specified by the
224              argument since (or in the past  day  if  no  since  argument  is
225              passed.   The  argument since can be any time string that is un‐
226              derstood by clock scan.
227
228       nntpName next
229              Sets the current article pointer to point to  the  next  message
230              (if there is one) and returns the msgid of that message.
231
232       nntpName post article
233              Posts   an   article   of   the   form  specified  in  RFC  1036
234              (http://www.rfc-editor.org/rfc/rfc1036.txt,  successor  to   RFC
235              850) to the current news group.
236
237       nntpName slave
238              Identifies  a connection as being made from a slave nntp server.
239              This might be used to indicate that the  connection  is  serving
240              multiple people and should be given priority.  Actual use is en‐
241              tirely implementation dependent and  may  vary  from  server  to
242              server.
243
244       nntpName stat ?msgid?
245              The  stat  command is similar to the article command except that
246              no text is returned.  When selecting by message number within  a
247              group,  the  stat  command  serves  to  set  the current article
248              pointer without sending text. The  returned  acknowledgment  re‐
249              sponse  will contain the message-id, which may be of some value.
250              Using the stat command to select by message-id is valid  but  of
251              questionable value, since a selection by message-id does NOT al‐
252              ter the "current article pointer"
253
254       nntpName quit
255              Gracefully close the connection after sending a NNTP  QUIT  com‐
256              mand down the socket.
257
258       nntpName xgtitle ?group_pattern?
259              Returns a tcl list where each element is of the form:
260
261
262              newsgroup description
263
264
265              If  a group_pattern is specified then only newsgroups that match
266              the pattern will have their name and description returned.
267
268       nntpName xhdr field ?range?
269              Returns the specified header field value for the current message
270              or  for a list of messages from the current group.  field is the
271              title of a field in the header such as from, subject, date, etc.
272              If  range  is not specified or is "" then the current message is
273              queried.  The command returns a list of elements where each ele‐
274              ment has the form of:
275
276
277                  msgid value
278
279
280              Where  msgid is the number of the message and value is the value
281              set for the queried field.  The range argument can be in any  of
282              the following forms:
283
284              ""     The current message is queried.
285
286              msgid1-msgid2
287                     All  messages between msgid1 and msgid2 (including msgid1
288                     and msgid2) are queried.
289
290              msgid1 msgid2
291                     All messages between msgid1 and msgid2 (including  msgid1
292                     and msgid2) are queried.
293
294       nntpName xover ?range?
295              Returns  header  information  for  the  current message or for a
296              range of messages from the current group.   The  information  is
297              returned in a tcl list where each element is of the form:
298
299
300                  msgid subject from date idstring bodysize headersize xref
301
302
303              If  range  is not specified or is "" then the current message is
304              queried.  The range argument can be  in  any  of  the  following
305              forms:
306
307              ""     The current message is queried.
308
309              msgid1-msgid2
310                     All  messages between msgid1 and msgid2 (including msgid1
311                     and msgid2) are queried.
312
313              msgid1 msgid2
314                     All messages between msgid1 and msgid2 (including  msgid1
315                     and msgid2) are queried.
316
317       nntpName xpat field range ?pattern_list?
318              Returns the specified header field value for a specified message
319              or for a list of messages from the current group where the  mes‐
320              sages  match the pattern(s) given in the pattern_list.  field is
321              the title of a field in the header such as from, subject,  date,
322              etc.   The information is returned in a tcl list where each ele‐
323              ment is of the form:
324
325
326                  msgid value
327
328
329              Where msgid is the number of the message and value is the  value
330              set  for the queried field.  The range argument can be in any of
331              the following forms:
332
333              msgid  The message specified by msgid is queried.
334
335              msgid1-msgid2
336                     All messages between msgid1 and msgid2 (including  msgid1
337                     and msgid2) are queried.
338
339              msgid1 msgid2
340                     All  messages between msgid1 and msgid2 (including msgid1
341                     and msgid2) are queried.
342

EXAMPLE

344       A bigger example for posting a single article.
345
346                  package require nntp
347                  set n [nntp::nntp NNTP_SERVER]
348                  $n post "From: USER@DOMAIN.EXT (USER_FULL)
349                  Path: COMPUTERNAME!USERNAME
350                  Newsgroups: alt.test
351                  Subject: Tcl test post -ignore
352                  Message-ID: <[pid][clock seconds]
353                  @COMPUTERNAME>
354                  Date: [clock format [clock seconds] -format "%a, %d %
355                  b %y %H:%M:%S GMT" -gmt true]
356
357                  Test message body"
358
359

BUGS, IDEAS, FEEDBACK

361       This document, and the package it describes, will  undoubtedly  contain
362       bugs  and  other  problems.  Please report such in the category nntp of
363       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
364       also  report any ideas for enhancements you may have for either package
365       and/or documentation.
366
367       When proposing code changes, please provide unified diffs, i.e the out‐
368       put of diff -u.
369
370       Note  further  that  attachments  are  strongly  preferred over inlined
371       patches. Attachments can be made by going  to  the  Edit  form  of  the
372       ticket  immediately  after  its  creation, and then using the left-most
373       button in the secondary navigation bar.
374

KEYWORDS

376       news, nntp, nntpclient, rfc 1036, rfc 977
377

CATEGORY

379       Networking
380
381
382
383tcllib                               1.5.1                             nntp(n)
Impressum