FETCH

Section: C Library Functions (3)
索引 jman

BSD mandoc

名称

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

索引

書式

Fd #include <sys/param.h> Fd #include <stdio.h> Fd #include <fetch.h> Ft FILE * Fn fetchGetURL char *URL char *flags Ft FILE * Fn fetchPutURL char *URL char *flags Ft int Fn fetchStatURL char *URL struct url_stat *us char *flags Ft struct url_ent * Fn fetchListURL char *URL char *flags Ft struct url * Fn fetchParseURL char *URL char *flags Ft FILE * Fn fetchGet struct url *URL char *flags Ft FILE * Fn fetchPut struct url *URL char *flags Ft int Fn fetchStat struct url *URL struct url_stat *us char *flags Ft struct url_ent * Fn fetchList struct url * char *flags Ft FILE * Fn fetchGetFile struct url *u char *flags Ft FILE * Fn fetchPutFile struct url *u char *flags Ft int Fn fetchStatFile struct url *URL struct url_stat *us char *flags Ft struct url_ent * Fn fetchListFile struct url * char *flags Ft FILE * Fn fetchGetHTTP struct url *u char *flags Ft FILE * Fn fetchPutHTTP struct url *u char *flags Ft int Fn fetchStatHTTP struct url *URL struct url_stat *us char *flags Ft struct url_ent * Fn fetchListHTTP struct url * char *flags Ft FILE * Fn fetchGetFTP struct url *u char *flags Ft FILE * Fn fetchPutFTP struct url *u char *flags Ft int Fn fetchStatFTP struct url *URL struct url_stat *us char *flags Ft struct url_ent * Fn fetchListFTP struct url * char *flags

索引

解説

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

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

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

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

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

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

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

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

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

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

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

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

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

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

索引

ファイルスキーム

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

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

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

索引

FTP スキーム

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

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

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

索引

HTTP スキーム

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

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

索引

戻り値

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

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

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

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

Bq Er FETCH_ABORT: オペレーションが異常終了しました。
Bq Er FETCH_AUTH: 認証がエラーになりました。
Bq Er FETCH_DOWN: サービスが使用できません。
Bq Er FETCH_EXISTS: ファイルが存在します。
Bq Er FETCH_FULL: ファイルシステムの容量が不足しています。
Bq Er FETCH_INFO: 情報としての応答です。
Bq Er FETCH_MEMORY: メモリが不足しています。
Bq Er FETCH_MOVED: ファイルが移動されました。
Bq Er FETCH_NETWORK: ネットワークエラー
Bq Er FETCH_OK: エラーはありません。
Bq Er FETCH_PROTO: プロトコルエラー
Bq Er FETCH_RESOLV: リゾルバエラー
Bq Er FETCH_SERVER: サーバエラー
Bq Er FETCH_TEMP: 一時的なエラー
Bq Er FETCH_TIMEOUT: オペレーションがタイムアウトになりました。
Bq Er FETCH_UNAVAIL: ファイルが使用できません。
Bq Er FETCH_UNKNOWN: 未知のエラー
Bq Er FETCH_URL: URL が正しくありません。

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

索引

環境変数

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

索引

注

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

索引

歴史

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

索引

作者

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

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

索引

バグ

Fn fetchPutHTTP 、 Fn fetchStatHTTP 、 Fn fetchListHTTP 、 Fn 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" を表します。

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

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

索引

jman

Time: 07:06:49 GMT, January 12, 2009