fetch(3)

fetchGetURL, fetchPutURL, fetchStatURL, fetchListURL, fetchParseURL, fetchGet, fetchPut, fetchStat, fetchList, fetchGetFile, fetchPutFile, fetchStatFile, fetchListFile, fetchGetHTTP, fetchPutHTTP, fetchStatHTTP, fetchListHTTP, fetchGetFTP, fetchPutFTP fetchStatFTP fetchListFTP, − ファ イル転送ライブラリ

#include <sys/param.h>
#include <stdio.h>
#include <fetch.h>

FILE *

fetchGetURL(char *URL, char *flags);

FILE *

fetchPutURL(char *URL, char *flags);

int

fetchStatURL(char *URL, struct url_stat *us, char *flags);

struct url_ent *

fetchListURL(char *URL, char *flags);

struct url *

fetchParseURL(char *URL, char *flags);

FILE *

fetchGet(struct url *URL, char *flags);

FILE *

fetchPut(struct url *URL, char *flags);

int

fetchStat(struct url *URL, struct url_stat *us, char *flags);

struct url_ent *

fetchList(struct url *, char *flags);

FILE *

fetchGetFile(struct url *u, char *flags);

FILE *

fetchPutFile(struct url *u, char *flags);

int

fetchStatFile(struct url *URL, struct url_stat *us, char *flags);

struct url_ent *

fetchListFile(struct url *, char *flags);

FILE *

fetchGetHTTP(struct url *u, char *flags);

FILE *

fetchPutHTTP(struct url *u, char *flags);

int

fetchStatHTTP(struct url *URL, struct url_stat *us, char *flags);

struct url_ent *

fetchListHTTP(struct url *, char *flags);

FILE *

fetchGetFTP(struct url *u, char *flags);

FILE *

fetchPutFTP(struct url *u, char *flags);

int

fetchStatFTP(struct url *URL, struct url_stat *us, char *flags);

struct url_ent *

fetchListFTP(struct url *, char *flags);

解説

この関数は、URL (Uniform Resource Locators) を使用してファイルの取り出し とアップロードを行なう、高レベルなライブラリを実現します。

fetchGetURL() と fetchPutURL() は、 fetch ライブラリのインタフェースを構 成します。この関数は渡された URL を検査して転送手法を決め、適切な低レベル 関数を呼び出して実際の転送を実行します。 flags 引数は、転送オプションを指 定するキャラクタのストリングです。それぞれのフラグの意味はスキームによっ て異なるので、以下の適切なセクションを参照してください。

fetchStatURL() は、要求された文書のメタデータを入手し、第 2 引数が指す構 造体にデータを入力しようとします。 url_stat 構造体は、 ⟨fetch.h⟩ で以下の ように定義されています。

struct url_stat {
    off_t        size;
    time_t       atime;
    time_t       mtime;
};

fetchListURL() は、指定された URL が指すディレクトリの内容をリストしよう とします。問題がなければ、malloc で割り振られた url_ent 構造体の配列を戻 します。 url_ent 構造体は、 ⟨fetch.h⟩ で以下のように定義されています。

struct url_ent {
    char         name[MAXPATHLEN];
    struct url_stat stat;
};

リストは、名前がないエントリで終わります。

fetchListURL() が戻すポインタは、 free() で解放してください。

fetchParseURL() はナル文字で終わるストリングの URL を取り、RFC1738 に規定 されている Common Internet Scheme Syntax に従って、その URL をコンポーネ ント関数に分割します。このシンタックスを作る正規表現は以下のとおりです。

    <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?

URL の一部のコンポーネントは、すべての URL スキームで重要ではないことがあ ることに注意してください。たとえばファイルスキームでは、<scheme> コンポー ネントと <document> コンポーネントしか必要ありません。

fetchParseURL() が戻すポインタは、 free() で解放してください。

fetchGet() 、 fetchPut() 、 fetchStat() は、ポインタの形式の事前解析済み URL がストリングではなく struct url で必要になることを除けば、 fetchGetURL() 、 fetchPutURL() 、 fetchStatURL() に似ています。

すべての fetchGetXXX() 関数と fetchPutXXX() 関数は、要求された文書からの データの読込みや要求された文書へのデータの書込みに使用できるストリームの ポインタを戻します。それぞれのアクセス手法のシステム詳細は異なりますが、 fetchGetXXX() 関数が戻すストリームは読込み専用で、 fetchPutXXX() が戻すス トリームは書込み専用であると一般的に仮定されます。

fetchGetFile() と fetchPutFile() では、ローカルにマウントされたファイルシ ステムのファイルである文書にアクセスできます。URL の <document> コンポー ネントのみが使用されます。

fetchGetFile() はフラグを受け入れません。

fetchPutFile() は、 a フラグ (ファイルに追加) を受け入れます。このフラグ を指定した場合、 fetchPutFile() が戻すストリームへ書き込まれたデータは、 ファイルの前の内容を置き換えるのではなくファイルの前の内容に追加されま す。

fetchGetFTP() と fetchPutFTP() は、RFC959 に記述されているように FTP プロ トコルを実現します。

p フラグ (受動) を指定すると、能動的ではなく受動的な接続が試されます。

ユーザ名かパスワードを指定しないと、 fetch ライブラリは、ユーザ名 "ftp"、 パスワード "ftp" で匿名ログインを試します。

fetchGetHTTP() 関数と fetchPutHTTP() 関数は、HTTP/1.1 プロトコルを実現し ます。この関数は、RFC2068 に準拠する可能性があります。

fetch ライブラリと調和する方法で HTTP PUT 手法を実現する適切な方法がない ようなので、 fetchPutHTTP() は現在のところ実現されていません。

fetchParseURL() は、URL のそれぞれのコンポーネントを含む struct url のポ インタを戻します。メモリを割り振れない場合、または URL のシンタックスが 正しくない場合、 fetchParseURL() は NULL ポインタを戻します。

fetchStat() 関数は、問題がなければ 0 を戻し、問題がある場合は -1 を戻しま す。

その他すべての関数は、要求された文書へのアクセスに使用できるストリームの ポインタを戻します。エラーが発生した場合は NULL を戻します。

Libfetch は、Common Error Library (libcom_err) を使用してエラーを報告しま す。 com_err() に渡されるエラーコードは以下のとおりです。

オペレーションが異常終了しました。

[FETCH_AUTH]
認証がエラーになりました。

[FETCH_DOWN]
サービスが使用できません。

[FETCH_EXISTS]
ファイルが存在します。

[FETCH_FULL]
ファイルシステムの容量が不足しています。

[FETCH_INFO]
情報としての応答です。

[FETCH_MEMORY]
メモリが不足しています。

[FETCH_MOVED]
ファイルが移動されました。

[FETCH_NETWORK]
ネットワークエラー

[FETCH_OK]
エラーはありません。

[FETCH_PROTO]
プロトコルエラー

[FETCH_RESOLV]
リゾルバエラー

[FETCH_SERVER]
サーバエラー

[FETCH_TEMP]
一時的なエラー

[FETCH_TIMEOUT]
オペレーションがタイムアウトになりました。

[FETCH_UNAVAIL]
ファイルが使用できません。

[FETCH_UNKNOWN]
未知のエラー

[FETCH_URL]
URL が正しくありません。

エラーメッセージには、 "File is not available (404 Not Found)" のように、 プロトコルのエラーコードとメッセージが組み込まれます。

環境変数

FTP と HTTP に関連した関数は、ファイル転送に使用するプロキシサーバのアド レスとして、 HTTP_PROXY 環境変数と FTP_PROXY 環境変数を使用します。

com_err(3), fetch(1), ftpio(3)

fetch ライブラリは Common Error ライブラリを使用するので、 libfetch にリ ンクするアプリケーションは、 libcom_err にもリンクする必要があります。

fetch ライブラリは、 FreeBSD 3.0 に追加されました。

fetch ライブラリは、 Jordan K. Hubbard ⟨jkh@FreeBSD.org⟩,
Eugene Skepner ⟨eu@qub.com⟩ 、その他の FreeBSD 開発者の提案を受け入れ、
Dag-Erling Coidan Smograv ⟨des@FreeBSD.org⟩ が作成しました。これにより、
Poul-Henning Kamp ⟨pkh@FreeBSD.org⟩ と
Jordan K. Hubbard ⟨jkh@FreeBSD.org⟩ が作成した ftpio が置き換えられまし た。

このマニュアルページの筆者は、
Dag-Erling Coidan Smograv ⟨des@FreeBSD.org⟩ です。

fetchPutHTTP() 、 fetchStatHTTP() 、 fetchListHTTP() 、 fetchListFTP() 、FTP プロキシサポートなど、ライブラリの一部はまだ実現されていません。

HTTP_PROXY 環境変数か FTP_PROXY 環境変数を適切に設定する以外、プロキシを 実行時に選択する方法はありません。この環境変数を設定した場合は、 FTP 関数 と HTTP 関数によるプロキシの使用を止めることはできません。

HTTP 認証は動作しません。調査した範囲では、コードにバグがあるとは言い切れ ません。 libfetch は HTTP/1.1 基本認証を RFC2068 のとおりに正しく処理しま すが、 HTTP サーバは、認証のヘッダフィールドを受け入れません。また libfetch は、HTTP サーバの認証要求を解釈してそれに応答しようとしません。

URL でスペースなどをエンコードする試みはなされていません。 URL の文書部分 のスペースは、HTTP URL で "%20" に、 FTP URLで "\ " に置き換える必要があ ります。

エラー番号は、特定コンテキストのみで一意です。 FTP と HTTP で使用するエ ラーコード、およびリゾルバとシステムのエラーで使用するエラーコードは重複 します。たとえばエラーコード 202 は、FTPでは "Command not implemented, superfluous at this site" を表し、HTTP では "Accepted" を表します。

このマニュアルページは不十分で、テキストのフォーマットも揃っていません。

その他にも多くのことがあります。

FreeBSD 10.0 July 1, 1998 FreeBSD 10.0