manページ  — FETCH

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

書式 解説 ファイルスキーム FTP スキーム HTTP スキーム 戻り値 環境変数 関連項目 注 歴史 作者 バグ

#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 fetchGetURL() を使用してエラーを報告します。 com_err() に渡されるエラーコードは以下のとおりです。

[FETCH_ABORT]
	オペレーションが異常終了しました。
[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 環境変数を使用します。

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" を表します。

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

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