Manual Pages for UNIX Darwin command on man nntp

nntp(n) Tcl NNTP Client Library nntp(n)

NAME

nntp - Tcl client for the NNTP protocol

SYNOPSIS

package require TTccll 88..22 package require nnnnttpp ??00..22..11??

::::nnnnttpp::::nnnnttpp ?host? ?port? ?nntpName?

nntpName mmeetthhoodd ?arg arg ...?

nntpName aarrttiiccllee ?msgid?

nntpName aauutthhiinnffoo ?user? ?pass?

nntpName bbooddyy ?msgid?

nntpName ccoonnffiigguurree

nntpName ccoonnffiigguurree option

nntpName ccoonnffiigguurree option value ...

nntpName ccggeett option

nntpName ddaattee

nntpName ggrroouupp ?group?

nntpName hheeaadd ?msgid?

nntpName hheellpp

nntpName llaasstt

nntpName lliisstt

nntpName lliissttggrroouupp ?group?

nntpName mmooddeerreeaaddeerr

nntpName nneewwggrroouuppss since

nntpName nneewwnneewwss

nntpName nneewwnneewwss since

nntpName nneewwnneewwss group ?since?

nntpName nneexxtt

nntpName ppoosstt article

nntpName ssllaavvee

nntpName ssttaatt ?msgid?

nntpName qquuiitt

nntpName xxggttiittllee ?grouppattern?

nntpName xxhhddrr field ?range?

nntpName xxoovveerr ?range?

nntpName xxppaatt field range ?patternlist?

DESCRIPTION

The package nnnnttpp provides a simple Tcl-only client library for the NNTP

protocol. It works by opening the standard NNTP socket on the server, and then providing a Tcl API to access the NNTP protocol commands. All server errors are returned as Tcl errors (thrown) which must be caught with the Tcl ccaattcchh command. CCOOMMMMAANNDDSS

::::nnnnttpp::::nnnnttpp ?host? ?port? ?nntpName?

The command opens a socket connection to the specified NNTP

server and creates a new nntp object with an associated global

Tcl command whose name is nntpName. This command may be used to

access the various NNTP protocol commands for the new connec-

tion. The default port number is "119" and the default host is "news". These defaults can be overridden with the environment variables NNNNTTPPPPOORRTT and NNNNTTPPHHOOSSTT respectively. Some of the commands supported by this package are not part of

the nntp rfc 977 (http://www.rfc-editor.org/rfc/rfc977.txt) and

will not be available (or implemented) on all nntp servers.

The access command nntpName has the following general form:

nntpName mmeetthhoodd ?arg arg ...?

Option and the args determine the exact behavior of the command.

nntpName aarrttiiccllee ?msgid?

Query the server for article msgid from the current group. The

article is returned as a valid tcl list which contains the head-

ers, followed by a blank line, and then followed by the body of

the article. Each element in the list is one line of the arti-

cle.

nntpName aauutthhiinnffoo ?user? ?pass?

Send authentication information (username and password) to the server.

nntpName bbooddyy ?msgid?

Query the server for the body of the article msgid from the cur-

rent group. The body of the article is returned as a valid tcl list. Each element in the list is one line of the body of the article.

nntpName ccoonnffiigguurree

nntpName ccoonnffiigguurree option

nntpName ccoonnffiigguurree option value ...

nntpName ccggeett option

Query and configure options of the nntp connection object. Cur-

rently only one option is supported, -bbiinnaarryy. When set articles

are retrieved as binary data instead of text. The only methods affected by this are aarrttiiccllee and bbooddyy. One application of this option would be the download of articles containing yEnc encoded images. Although encoded the data is still mostly binary and retrieving it as text will corrupt the information. See package yyeennccooddee for both encoder and decoder of such data.

nntpName ddaattee

Query the server for the servers current date. The date is returned in the format YYYYMMDDHHMMSS.

nntpName ggrroouupp ?group?

Optionally set the current group, and retrieve information about the currently selected group. Returns the estimated number of

articles in the group followed by the number of the first arti-

cle in the group, followed by the last article in the group, followed by the name of the group.

nntpName hheeaadd ?msgid?

Query the server for the headers of the article msgid from the current group. The headers of the article are returned as a valid tcl list. Each element in the list is one line of the headers of the article.

nntpName hheellpp

Retrieves a list of the commands that are supported by the news server that is currently attached to.

nntpName llaasstt

Sets the current article pointer to point to the previous mes-

sage (if there is one) and returns the msgid of that message.

nntpName lliisstt

Returns a tcl list of valid newsgroups and associated informa-

tion. Each newsgroup is returned as an element in the tcl list with the following format: group last first p where is the name of the newsgroup, is the number of the last known article currently in that newsgroup, is the number of the first article currently in the newsgroup, and

is either 'y' or 'n' indicating whether posting to this newsgroup is allowed ('y') or prohibited ('n'). The and fields will always be numeric. They may have leading zeros. If the field evaluates to less than the field, there are no articles currently on file in the newsgroup.

nntpName lliissttggrroouupp ?group?

Query the server for a list of all the messages (message num-

bers) in the group specified by the argument group or by the current group if the group argument was not passed.

nntpName mmooddeerreeaaddeerr

Query the server for its nntp 'MODE READER' response string.

nntpName nneewwggrroouuppss since

Query the server for a list of all the new newsgroups created since the time specified by the argument since. The argument since can be any time string that is understood by cclloocckk ssccaann. The tcl list of newsgroups is returned in a similar form to the

list of groups returned by the nnnnttppNNaammee lliisstt command. Each ele-

ment of the list has the form: group last first p where is the name of the newsgroup, is the number of the last known article currently in that newsgroup, is the number of the first article currently in the newsgroup, and

is either 'y' or 'n' indicating whether posting to this newsgroup is allowed ('y') or prohibited ('n').

nntpName nneewwnneewwss

Query the server for a list of new articles posted to the cur-

rent group in the last day.

nntpName nneewwnneewwss since

Query the server for a list of new articles posted to the cur-

rent group since the time specified by the argument since. The argument since can be any time string that is understood by cclloocckk ssccaann.

nntpName nneewwnneewwss group ?since?

Query the server for a list of new articles posted to the group specified by the argument group since the time specified by the argument since (or in the past day if no since argument is passed. The argument since can be any time string that is understood by cclloocckk ssccaann.

nntpName nneexxtt

Sets the current article pointer to point to the next message (if there is one) and returns the msgid of that message.

nntpName ppoosstt article

Posts an article of the form specified in RFC 1036

(http://www.rfc-editor.org/rfc/rfc1036.txt, successor to RFC

850) to the current news group.

nntpName ssllaavvee

Identifies a connection as being made from a slave nntp server.

This might be used to indicate that the connection is serving multiple people and should be given priority. Actual use is entirely implementation dependent and may vary from server to server.

nntpName ssttaatt ?msgid?

The stat command is similar to the article command except that no text is returned. When selecting by message number within a group, the stat command serves to set the current article pointer without sending text. The returned acknowledgment

response will contain the message-id, which may be of some

value. Using the stat command to select by message-id is valid

but of questionable value, since a selection by message-id does

NOT alter the "current article pointer"

nntpName qquuiitt

Gracefully close the connection after sending a NNTP QUIT com-

mand down the socket.

nntpName xxggttiittllee ?grouppattern?

Returns a tcl list where each element is of the form: newsgroup description If a grouppattern is specified then only newsgroups that match the pattern will have their name and description returned.

nntpName xxhhddrr field ?range?

Returns the specified header field value for the current message or for a list of messages from the current group. field is the title of a field in the header such as from, subject, date, etc. If range is not specified or is "" then the current message is

queried. The command returns a list of elements where each ele-

ment has the form of: msgid value Where msgid is the number of the message and value is the value set for the queried field. The range argument can be in any of the following forms: """" The current message is queried.

msgid1-msgid2

All messages between msgid1 and msgid2 (including msgid1 and msgid2) are queried. msgid1 msgid2 All messages between msgid1 and msgid2 (including msgid1 and msgid2) are queried.

nntpName xxoovveerr ?range?

Returns header information for the current message or for a range of messages from the current group. The information is returned in a tcl list where each element is of the form: msgid subject from date idstring bodysize headersize xref If range is not specified or is "" then the current message is queried. The range argument can be in any of the following forms: """" The current message is queried.

msgid1-msgid2

All messages between msgid1 and msgid2 (including msgid1 and msgid2) are queried. msgid1 msgid2 All messages between msgid1 and msgid2 (including msgid1 and msgid2) are queried.

nntpName xxppaatt field range ?patternlist?

Returns the specified header field value for a specified message

or for a list of messages from the current group where the mes-

sages match the pattern(s) given in the patternlist. field is the title of a field in the header such as from, subject, date,

etc. The information is returned in a tcl list where each ele-

ment is of the form: msgid value Where msgid is the number of the message and value is the value set for the queried field. The range argument can be in any of the following forms: msgid The message specified by msgid is queried.

msgid1-msgid2

All messages between msgid1 and msgid2 (including msgid1 and msgid2) are queried. msgid1 msgid2 All messages between msgid1 and msgid2 (including msgid1 and msgid2) are queried. EEXXAAMMPPLLEE A bigger example for posting a single article.

package require nntp

set n [nntp::nntp NNTPSERVER]

$n post "From: USER@DOMAIN.EXT (USERFULL)

Path: COMPUTERNAME!USERNAME

Newsgroups: alt.test

Subject: Tcl test post -ignore

Message-ID: <[pid][clock seconds]

@COMPUTERNAME>

Date: [clock format [clock seconds] -format "%a, %d %

b %y %H:%M:%S GMT" -gmt true]

Test message body" KKEEYYWWOORRDDSS