LIBINN(3)

名前
libinn - InterNetNews ライブラリルーチン

形式
#include "libinn.h"
typedef struct _TIMEINFO {
    time_t	time;
    long	usec;
    long	tzone;
} TIMEINFO;
char *
GenerateMessageID()
void
HeaderCleanFrom(from)
    char	*from;
char *
HeaderFind(Article, Header, size)
    char	*Article;
    char	*Header;
    int	size;
FILE *
CAopen(FromServer, ToServer)
    FILE	*FromServer;
    FILE	*ToServer;
FILE *
CAlistopen(FromServer, ToServer, request)
    FILE	*FromServer;
    FILE	*ToServer;
    char	*request;
void
CAclose()
struct _DDHANDLE *
DDstart(FromServer, ToServer)
    FILE	*FromServer;
    FILE	*ToServer;
void
DDcheck(h, group)
    DDHANDLE	*h;
    char	*group;
char *
DDend(h)
    DDHANDLE	*h;
void
CloseOnExec(fd, flag)
    int	fd;
    int	flag;
int
SetNonBlocking(fd, flag)
    int	fd;
    int	flag;
int
LockFile(fd, flag)
    int	fd;
    int	flag;
char *
GetConfigValue(value)
    char	*value;
char *
GetFileConfigValue(value)
    char	*value;
char *
GetFQDN()
char *
GetModeratorAddress(FromServer, ToServer, group)
    FILE	*FromServer;
    FILE	*ToServer;
    char	*group;
int
GetResourceUsage(usertime, systime)
    double	*usertime;
    double	*systime;
int
GetTimeInfo(now)
    TIMEINFO	*now;
int
NNTPlocalopen(FromServerp, ToServerp, errbuff)
    FILE	**FromServerp;
    FILE	**ToServerp;
    char	*errbuff;
int
NNTPremoteopen(FromServerp, ToServerp, errbuff)
    FILE	**FromServerp;
    FILE	**ToServerp;
    char	*errbuff;
int
NNTPconnect(host, FromServerp, ToServerp, errbuff)
    char	*host;
    FILE	**FromServerp;
    FILE	**ToServerp;
    char	*errbuff;
int
NNTPcheckarticle(text)
    char	*text;
int
NNTPsendarticle(text, ToServer, Terminate)
    char	*text;
    FILE	*ToServer;
    int	Terminate;
int
NNTPsendpassword(server, FromServer, ToServer)
    char	*server;
    FILE	*FromServer;
    FILE	*ToServer;
void
Radix32(value, p)
    unsigned long	value;
    char	*p;
char *
ReadInFile(name, Sbp)
    char	*name;
    struct stat	*Sbp;
char *
ReadInDescriptor(fd, Sbp)
    int	fd;
    struct stat	*Sbp;
char *
INNVersion()

機能説明
libinn は記事や関連するデータを操作ためのルーチンのライブラリです。 libinn.h が利用できない場合は、このヘッダファイルを使用する必要は無いですが、上記のデータタイプ TIMEINFO のみを適宜宣言する必要があります。

GenerateMessageID 現在時刻、プロセス ID およびローカルホストの FQDN を使用して、 唯一であろうと思われる Message-ID ヘッダを作成します。 戻り値はスタティックな領域を示し、以後の呼び出しで再利用します。

HeaderCleanFrom ``From'' あるいは ``Reply-To'' ヘッダの値から無関係の情報を除き、 有効なアドレス部分のみ残します。 特に、引数の from には次のような変更が行われます。
    address	-->  address
    address (stuff)	-->  address
    stuff <address>	-->  address
変換は単純で、ヘッダフォーマットを規定している RFC 1036 をもとにしています。

HeaderFind Article を検索し、 Header で指定したヘッダを見つけます。 Size はヘッダ名の長さでなければいけません。 戻り値はヘッダの値へのポインタで、先頭のホワイトスペースはスキップされています。 ヘッダが見つからなければ、NULL となります。 Article は記事のテキストから構成される標準 C 言語での文字列となっていなければいけません。 ヘッダ部の最後は空行で識別されます — \n が二つ連続で続きます。

CAopen と CAclose はニュースクライアントからの active ファイルへのアクセスを提供します。 ``CA'' は Client Active を意味します。 CAopen は active(5) ファイルを read のためにオープンします。 戻り値はオープンした FILE 構造体へのポインタか、エラーであれば NULL となります。 ローカルあるいは NFS マウントした先にコピーしたファイルが存在していれば、 CAopen はそのファイルを使用します。 引数の FromServer と ToServer はそれぞれ接続された NNTP サーバへの入出力 FILE 構造体へのポインタでなければいけません。 次に説明する NNTPremoteopen あるいは NNTPlocalopen を参照してください。 いずれの引数も NULL の場合、ファイルがローカルで使用できなければ、 CAopen は単に NULL を返します。 引数が NULL でなければ、 CAopen はこれを使用して、NNTP サーバに ``list'' コマンドを使用して問い合わせ、 ローカルにテンポラリなコピーを作成します。

CAlistopen はサーバに ``list'' コマンドを送り、その結果得られるテンポラリファイルへのポインタを返します。 引数の request が NULL でなければ、コマンドで使用される引数として送られます。 CAopen とは異なり、このルーチンはローカルで使用可能となっている active ファイルのコピーは使用しません。

CAclose は active ファイルをクローズし、 CAopen あるいは CAlistopen で作成したテンポラリファイルを削除します。

CloseOnExec はファイルディスクリプタを ``close-on-exec'' とし、子プロセスとファイルディスクリプタを共有しないようにすることができます。 flag が 0 以外の場合、ファイルディスクリプタを ``close-on-exec'' にし、 0 の場合、``close-on-exec'' をクリアします。

DDstart 、 DDcheck および DDend は Distribution ヘッダを設定するために使用します。 ``DD'' は Default Distribution を意味します。 すべての Newsgroups ヘッダをチェックした後、適切な Distribution ヘッダを決めるために distrib.pats(5) ファイルを調べます。 DDstart は解析を開始します。 戻り値は、後続の関数で使用することになるハンドラへのポインタとなります。 引数の FromServer と ToServer はそれぞれ接続された NNTP サーバへの入出力 FILE 構造体へのポインタでなければいけません。 いずれかの引数が NULL の場合、ファイルがローカルで使用可能でなければ、 戻り値は、最終的にはデフォルトの空となります。

DDcheck は DDstart で得られたハンドラ h とチェックすべきニュースグループである group を用いて呼ばなければいけません。 このルーチンが必要となる状況が頻繁にあるかもしれません。

DDend はハンドラ内で保持していた状態を解放し、戻り値は Distribution ヘッダで使用されることになるテキストのための領域を指します。

SetNonBlocking は指定したファイルディスクリプタの( flag が 0 以外なら)ノンブロッキング I/O を有効にしたり、( flag が 0 ならば)無効にしたりします。 戻り値は、エラーで -1 で、成功すれば 0 となります。

LockFile はファイルディスクリプタ fd をロックしようとします。 flag が 0 以外の場合、ロックできるまで待ち、0 の場合、 戻り値はファイルがロックできなければ -1 となります。 戻り値は、エラーで -1 で、成功すれば 0 となります。

GetConfigValue は指定した設定パラメータの値を取得します。 パラメータとその意味についての詳細は、 inn.conf(5) を参照してください。 戻り値はスタティックな領域を示し、以後の呼び出しで再利用します。

GetFileConfigValue は指定した設定パラメータの値をデフォルトの値をチェックせずに inn.conf ファイルから取得します。 戻り値はスタティックな領域を示し、以後の呼び出しで再利用し、値が存在しなければ NULL となります。

GetFQDN はローカルホストの FQDN を取得します。 戻り値はスタティックな領域を示し、以後の呼び出しで再利用し、エラーの場合は NULL となります。

GetModeratorAddress は group で指定したニュースグループのモデレータの E-mail アドレスを取得し、 エラーの場合の戻り値は NULL となります。 E-mail アドレスがどのように取得されるかの詳細は、 moderators(5) を参照してください。 GetModeratorAddress は指定したニュースグループ名が実際に moderated であるかどうかはチェックしません。 戻り値はスタティックな領域を示し、以後の呼び出しで再利用します。 FromServer と ToServer はそれぞれ接続された NNTP サーバへの入出力 FILE 構造体へのポインタでなければいけません。 いずれかの引数が NULL の場合、ローカルなファイルから取得しようとします。

GetResourceUsage は引数の usertime と systime にカレントのプロセスと起動した子プロセスで使用したトータルなユーザとシステム時間を代入します。 これは、 getrusage(2) システムコールによって行います。 戻り値は、エラーで -1 で、成功すれば 0 となります。

GetTimeInfo は引数 now 現在時刻とタイムゾーンを代入します。 引数の ``time'' と ``usec'' には gettimeofday(2) を呼ぶことにより代入されます。 ``tzone'' には GMT からの現在時刻へのオフセットが代入されます。 これは、 localtime(3) を呼び、``tm_gmtoff'' の値からその値を引き、60 で割ることにより行われます。 効率を上げるため、``tzone'' は最後に GetTimeInfo を呼んでから 1 時間以上経過している場合のみ再計算されます。 このルーチンの戻り値は、エラーで -1 で、成功すれば 0 となります。

NNTPlocalopen はローカルホスト上で起動している InterNetNews サーバのプライベートなポートへのコネクションを張ります。 戻り値は、エラーで -1 で、成功すれば 0 となります。 FromServerp と ToServerp は NNTP サーバと通信するために使用することができる FILE 構造体へのポインタが代入されます。 errbuff は NULL あるいは 512 バイト以上のバッファへのポインタとなります。 NULL でなく、サーバがコネクションを拒否した場合、サーバからのリプライが代入されています。 このルーチンは一般的な使用目的のために用意されているわけではありません。

NNTPremoteopen は GetConfigValue を呼んでローカルサーバ名を見つけ、標準のNNTP ポートへコネクションを張る以外は NNTPlocalopen と同じです。 クライアントのプログラムではこのルーチンを使用することができます。 戻り値は、エラーで -1 で、成功すれば 0 となります。

NNTPconnect は引数 host でコネクションを張るホストを指定する以外は NNTPremoteopen と同じです。

NNTPcheckarticle は text が NNTP での一行の長さの制限の範囲内であるかどうかチェックします。 戻り値は、エラーで -1 で、text が有効であれば 0 となります。

NNTPsendarticle は ToServer に対して、NNTP における行末処理を使用して、 text を write します。 text は一行以上の行で構成し、改行で終了していなければいけません。 Terminate が 0 以外の場合、NNTP における行末処理を text に対して行って write します。 戻り値は、エラーで -1 で、成功すれば 0 となります。

NNTPsendpassword は passwd.nntp(5) ファイルから適切なエントリを見つけ、NNTP サーバに認証情報を送ります。 server はホスト名です。 server が NULL の場合、 GetConfigValue を使用して、サーバを見つけます。 FromServer と ToServer は接続した NNTP サーバへの FILE 構造体へのポインタでなければいけません。 指定したホストがパスワードファイルになければ何も行いません。

Radix32 は、 value の値を p で示されるバッファへ radix-32 の文字列として変換します。 数字は 5 ビット毎に区切られ、区切られたものは 0..32 の数字を一文字で表すために、 0..9a..v の数字とアルファベット文字に変換されます。 value の下位 32 ビットのみが使用されるため、 p は 8 バイト(7 文字と最後の \0)のバッファを指している必要があります。

ReadInFile は name というファイル名を割り当てたメモリに読み込み、最後に終了文字の \0 を付け加えます。 戻り値は、割り当てた領域へのポインタで、エラーの場合は NULL となります。 Sbp が NULL でなければ、 stat(2) の結果を保持する領域へのアドレスとみなします。

ReadInDescriptor は、 fd がすでにオープンしているファイルを指している以外は、 ReadInFile と同じことを行います。

INNVersion は、接続時のメッセージ出力に適切な INN のバージョンを示すための文字列へのポインタを返します。

使用例
    char	*p;
    char	*Article;
    char	buff[256];
    FILE	*F;
    FILE	*ToServer;
    FILE	*FromServer;
    if ((p = HeaderFind(Article, "From", 4)) == NULL)
        Fatal("Can't find From line");
    (void)strcpy(buff, p);
    HeaderCleanFrom(buff);
    if ((F = CAopen(FromServer, ToServer)) == NULL)
        Fatal("Can't open active file");
    /* 子プロセスにはファイルディスクリプタを渡さない */
    CloseOnExec(fileno(F), 1);
    /* ローカルにコピーする */
    p = ReadInDescriptor(fileno(F), (struct stat *)NULL);
    /* ファイルをクローズする */
    CAclose();
    if (NNTPremoteopen(&FromServer, &ToServer) < 0)
        Fatal("Can't connect to server");
    if ((p = GetModeratorAddress("comp.sources.unix")) == NULL)
        Fatal("Can't find moderator's address");

履歴
InterNetNews 用に Rich $alz <rsalz@uunet.uu.net> により記述されました。

関連事項
active(5)、 dbz(3)、 parsedate(3)、 inn.conf(5)、 inndcomm(3)、 moderators(5)、 passwd.nntp(5)