EN JA
FETCH(3)
FETCH(3) FreeBSD Library Functions Manual FETCH(3)

名称

fetchMakeURL, fetchParseURL, fetchFreeURL, fetchXGetURL, fetchGetURL, fetchPutURL, fetchStatURL, fetchListURL, fetchXGet, fetchGet, fetchPut, fetchStat, fetchList, fetchXGetFile, fetchGetFile, fetchPutFile, fetchStatFile, fetchListFile, fetchXGetHTTP, fetchGetHTTP, fetchPutHTTP, fetchStatHTTP, fetchListHTTP, fetchXGetFTP, fetchGetFTP, fetchPutFTP, fetchStatFTP, fetchListFTPファイル転送関数

ライブラリ

File Transfer Library (libfetch, -lfetch)

書式

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

struct url *
fetchMakeURL( const char *scheme, const char *host, int port, const char *doc, const char *user, const char *pwd);

struct url *
fetchParseURL( const char *URL);

void
fetchFreeURL( struct url *u);

FILE *
fetchXGetURL( const char *URL, struct url_stat *us, const char *flags);

FILE *
fetchGetURL( const char *URL, const char *flags);

FILE *
fetchPutURL( const char *URL, const char *flags);

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

struct url_ent *
fetchListURL( const char *URL, const char *flags);

FILE *
fetchXGet( struct url *u, struct url_stat *us, const char *flags);

FILE *
fetchGet( struct url *u, const char *flags);

FILE *
fetchPut( struct url *u, const char *flags);

int
fetchStat( struct url *u, struct url_stat *us, const char *flags);

struct url_ent *
fetchList( struct url *u, const char *flags);

FILE *
fetchXGetFile( struct url *u, struct url_stat *us, const char *flags);

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

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

int
fetchStatFile( struct url *u, struct url_stat *us, const char *flags);

struct url_ent *
fetchListFile( struct url *u, const char *flags);

FILE *
fetchXGetHTTP( struct url *u, struct url_stat *us, const char *flags);

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

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

int
fetchStatHTTP( struct url *u, struct url_stat *us, const char *flags);

struct url_ent *
fetchListHTTP( struct url *u, const char *flags);

FILE *
fetchXGetFTP( struct url *u, struct url_stat *us, const char *flags);

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

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

int
fetchStatFTP( struct url *u, struct url_stat *us, const char *flags);

struct url_ent *
fetchListFTP( struct url *u, const char *flags);

解説

これらの関数は、Uniform Resource Locators (URL) を使用して、ファイルを検索 (取り出し) とアップロードのための高レベルのライブラリを実装しています。

fetchParseURL() は、ヌル文字で終了した文字列の形の URL を取得し、 RFC1738 で詳述された Common Internet Scheme Syntax (共通インターネットスキームシンタックス) のためのコンポーネント関数にそれを分割します。このシンタックスを生成する正規表現は、次の通りです:

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

URL がスキーム名から始まるようには見えないなら、次のシンタックスが仮定されます。

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

URL のいくつかのコンポーネントがすべての URL スキームに必ずしも適切ではないことに注意してください。例えば、ファイルスキームは、<scheme>と <document>コンポーネントのみを必要とします。

fetchMakeURL() と fetchParseURL() は、 < fetch.h> に次のように定義される、 url 構造体へのポインタを返します。

#define URL_SCHEMELEN 16 
#define URL_USERLEN 256 
#define URL_PWDLEN 256 
 
struct url { 
    char  scheme[URL_SCHEMELEN+1]; 
    char  user[URL_USERLEN+1]; 
    char  pwd[URL_PWDLEN+1]; 
    char  host[MAXHOSTNAMELEN+1]; 
    int   port; 
    char *doc; 
    off_t  offset; 
    size_t  length; 
    time_t  ims_time; 
};

ims_time フィールドは、 If-Modified-Since HTTP 要求のための時間値を格納します。

fetchMakeURL() または fetchParseURL() によって返されたポインタは、 fetchFreeURL() を使用して解放されるべきです。

fetchXGetURL(), fetchGetURL() と fetchPutURL() は、 fetch ライブラリへの推奨されたインタフェースを構成します。それらは、転送方法を決定し、かつ実際の転送を実行するために適切なより低レベル関数を呼び出すためにそれらに渡された URL を検査します。 fetchXGetURL() は、さらに us 引数によって指された url_stat 構造体のリモートドキュメントのメタデータを返します。

flags 引数は、転送オプションを指定する文字列です。個々のフラグの意味は、スキーム独立で、下記の適切なセクションで詳述されます。

fetchStatURL() は、要求されたドキュメントのメタデータを取得し、2 つめの引数によって指される構造体に入れることを試みます。 url_stat 構造体は、 < fetch.h> に次のように定義されます。

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

サーバからサイズを得ることができないかもしれないなら、 size フィールドは、-1 に設定されます。サーバから修正時間を得ることができないかもしれないなら、 mtime フィールドは、エポック時間 (1970年1月1日午前0時) に設定されます。サーバからアクセス時間を得ることができないかもしれないなら、 atime フィールドは、修正時間に設定されます。

fetchListURL() は、提供される URL によって指されるディレクトリの内容をリストすることを試みます。成功したなら、 url_ent 構造体の malloc された配列を返します。 url_ent 構造体は、 < fetch.h> に次のように定義されます。

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

リストは、空の名前のエントリによって終了します。

fetchListURL() によって返されたポインタは、 free() を使用して解放されるべきです。

fetchXGet(), fetchGet(), fetchPut() と fetchStat() は、それらが、文字列ではなく struct url へのポインタの形であらかじめ解析された URL を期待することを除いて、 fetchXGetURL(), fetchGetURL(), fetchPutURL() と fetchStatURL() に似ています。

fetchXGetXXX(), fetchGetXXX() と fetchPutXXX() 関数のすべては、要求された文書からデータを読み込むか、あるいはその文書にデータを書き込むために使用することができるストリームへのポインタをそれぞれ返します。個々のアクセス方式の実装の詳細は、変わりますが fetchXGetXXX() か fetchGetXXX() 関数のうちの 1 つによって返されたストリームが読み込みのみであり、 fetchPutXXX() 関数のうちの 1 つによって返されたストリームが書き込みのみであることを一般に仮定することができることに注意してください。

ファイルスキーム

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

fetchXGetFile() と fetchGetFile() は、何のフラグも受け付けません。

fetchPutFile() は、‘ a’ (ファイルに追加する) フラグを受け付けます。そのフラグが指定されるなら、 fetchPutFile() によって返されたストリームに書き込まれたデータは、内容を置き換える代わりに、ファイルの前の内容に追加されます。

FTP スキーム

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

P’ (パッシブ (受動的) でない) フラグが指定されるなら、 (パッシブでなく) アクティブ (能動的) な接続が試みられます。

p’フラグは、アクティブな接続がデフォルトであった、初期のバージョンとの互換性のためにサポートされています。‘ P’フラグに優先するので、両方が指定されるなら、 fetchMakeURL は、パッシブな接続を使用します。

l’ (ロウ、低い) フラグが指定されたなら、データソケットは、高いポート範囲 ( ip(4) を参照) の代わりに、低い (あるいはデフォルト) ポート範囲に割り付けられます。

d’ (ダイレクト、直接) フラグが指定されるなら、 proxy サーバが定義されても、 fetchXGetFTP(), fetchGetFTP() と fetchPutFTP() は、直接の接続を使用します。

ユーザ名もパスワードも与えられないなら、 fetch ライブラリは、ユーザ名 "anonymous"とパスワード "anonymous@<hostname>"で匿名ログインを試みます。

HTTP スキーム

fetchXGetHTTP(), fetchGetHTTP() と fetchPutHTTP() 関数は、HTTP/1.1 プロトコルを実装しています。少しうまくいくなら、それらは、RFC2616 と RFC2617 に準拠する可能性さえあります。

d’ (ダイレクト、直接) フラグが指定されるなら、 proxy サーバが定義されても、 fetchXGetHTTP(), fetchGetHTTP() と fetchPutHTTP() は、直接の接続を使用します。

i’ (if-modified-since) フラグが指定され、 ims_time フィールドが、 struct url に設定されるなら、 fetchXGetHTTP() と fetchGetHTTP() は、 ims_time より新しいなら、ただ内容を取り出すために条件付きの If-Modified-Since HTTP ヘッダを送信します。

fetch ライブラリの残りと調和する方法で HTTP PUT 方法を実装するよい方法がないように思われるので、 fetchPutHTTP() は、現在実装されていません。

HTTPS スキーム

HTTP スキームに基づいています。デフォルトで、ピア (通信相手) は、 /etc/ssl/cert.pem にある CA バンドルを使用して確認されます。ファイルは、複数の CA 証明書を含んでいます。現在の CA バンドルの共通ソースは、 security/ca_root_nss です。

信頼された CA ( verify(1) 参照) のハッシュを含んでいるディレクトリを指す環境変数 SSL_CA_CERT_PATH と信頼された証明書の連結したバンドルを指す環境変数 SSL_CA_CERT_FILE を設定することによってピアの検証に使用される CA バンドルを変更することができます。

環境変数 SSL_CRL_FILE ( crl(1) を参照) を設定することによって、証明書取り消しリスト (CRL) を使用することができます。

環境変数 SSL_NO_VERIFY_PEER を設定することによって、ピアの検証を無効にすることができます。また、これは、CRL チェックを無効にすることに注意してください。

デフォルトで、サービスの識別は、(また、ホスト名検証として知られている) RFC6125 に詳細に記述された規則に従って検証されます。環境変数 SSL_NO_VERIFY_HOSTNAME を設定することによって、この機能を無効にすることができます。

クライアント証明書に基づいた認証がサポートされています。環境変数 SSL_CLIENT_CERT_FILE は、PEM 形式で使用されるキーを含んでいるファイルとクライアント証明書を指すように設定されるべきです。キーが個別のファイルに格納されている場合に、環境変数 SSL_CLIENT_KEY_FILE は、PEM 形式のキーを指すように設定することができます。キーがパスワードを使用する場合に、ユーザに、標準入力 ( PEM(3) を参照) でプロンプトが出されます。

デフォルトで、 libfetch は、リモートのピアと接続を交渉するとき、SSLv3 と TLSv1 を許可します。 (推奨されない) SSLv2 を許可するために、環境変数 SSL_ALLOW_SSL2 とそれぞれのメソッドを無効にするために環境変数 SSL_NO_SSL3 または SSL_NO_TLS1 を設定することによって、この振る舞いを変更することができます。

認証

適切な環境変数を設定し URL あるいは struct url でユーザ名とパスワードを指定することとは別に、呼び出しプログラムは、次のプロトタイプの認証関数を定義するオプションを持っています。

int myAuthMethod( struct url *u)

コールバック関数は、提供される struct urluserpwd フィールドに書き入れるべきであり、成功すれば 0 を返し、あるいは失敗を示す他の値を返します。

認証コールバックを登録するためには、単に fetchAuthMethod にそのポイントを設定します。サイトが認証を要求し、適切な環境変数が設定されていないときはいつでも、コールバックは、使用されます。

このインタフェースは、実験的で、変更の対象かもしれません。

戻り値

fetchParseURL() は、URL の個々のコンポーネントを含んでいる struct url へのポインタを返します。それがメモリを割り付けることができないか、URL が構文上正しくないなら、 fetchParseURL() は、NULL ポインタを返します。

fetchStat() 関数は、成功すれば 0 を返し、失敗すれば -1 を返します。

他のすべての関数は、要求された文書にアクセスするために使用されるストリームのポインタか、またはエラーが生じたなら、NULL を返します。

次のエラーコードが < fetch.h> に定義されています。

[ FETCH_ABORT]
オペレーションが異常終了しました。
[ FETCH_AUTH]
認証が失敗しました。
[ FETCH_DOWN]
サービスが利用不可能です。
[ FETCH_EXISTS]
ファイルが存在します。
[ FETCH_FULL]
ファイルシステムの容量不足です。
[ FETCH_INFO]
Informational response 情報の応答です。
[ 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)"のように、添付のエラーメッセージは、プロトコルに特有のエラーコードとメッセージを含んでいます。

環境変数

FETCH_BIND_ADDRESS
外向きの接続のために使用されるソケットを結びつけるホスト名または IP アドレスを指定します。
FTP_LOGIN
URL で何も提供されなかったなら、デフォルトの FTP でログインします。
FTP_PASSIVE_MODE
no’に設定されるなら、FTP コードは、強制的にアクティブモードを使用します。他の値に設定されるなら、アプリケーションがアクティブモードを要求したとしても、パッシブモードを強制します。
FTP_PASSWORD
リモートサーバがそれを要求し、なにも URL で提供されなかったならば、デフォルト FTP パスワードとなります。
FTP_PROXY
FTP 要求のために使用するプロキシ (代理の) URL です。ドキュメント部分が無視されます。 FTP と HTTP プロキシがサポートされます。スキームが指定されないなら、FTP が仮定されます。プロキシが FTP プロキシであるなら、‘ user’が実際のユーザ名で、‘ host’が FTP サーバの名前であるなら、 libfetch は、プロキシにユーザ名として‘ user@host’を送信します。

この変数が空の文字列に設定されるなら、 HTTP_PROXY 変数が設定されていても、プロキシは、FTP 要求のために使用されません。

ftp_proxy
互換性のために FTP_PROXY と同じです。
HTTP_ACCEPT
HTTP 要求のための Accept ヘッダの値を指定します。空であるなら、 Accept ヘッダは、送信されません。デフォルトは、“*/*”です。
HTTP_AUTH
コロンで分離された項目のリストのように、HTTP 認証パラメータを指定します。最初と 2 番目の項目は、それぞれ認証スキームとレルム (アドレス体系) です。さらなる項目は、スキーム依存です。現在、“basic”と“digest”認証メソッドがサポートされています。

両方の認証は、2 つのパラメータを要求します。次の順序で、ユーザ名とパスワードです。

サーバが認証を要求し、ユーザ名またはパスワードが URL の中で指定されなかったなら、この変数が単に使用されます。

HTTP_PROXY
HTTP 要求のために使用するプロキシの URL です。ドキュメント部分は、無視されます。 HTTP プロキシだけが HTTP 要求のためにサポートされます。ポート番号が指定されないなら、デフォルトは、3128 です。

FTP_PROXY 変数が設定されなければ、このプロキシも FTP ドキュメントのために使用されることに注意してください。

http_proxy
互換性のために HTTP_PROXY と同じです。
HTTP_PROXY_AUTH
HTTP_AUTH 変数と同じ形式で HTTP プロキシのための認証パラメータを指定します。

この変数は、HTTP プロキシに接続された時かつその時に限り使用され、ユーザと (または) パスワードがプロキシ URL の中で指定されたならば、無視されます。

HTTP_REFERER
HTTP 要求のために使用する参照 URL を指定します。“auto”に設定されたなら、ドキュメント URL は、参照 URL として使用されます。
HTTP_USER_AGENT
HTTP 要求のために使用するユーザエージェント (代理人) 文字列を指定します。ユーザエージェントを区別する HTTP 系またはプロキシサーバで動作するとき、これは、有用となります。
NETRC
FTP サイトのログイン名とパスワードを調べるために ~/.netrc の代わりに使用するファイルを指定します。ファイルフォーマットの記述に関しては、 ftp(1) を参照してください。この機能は、実験的です。
NO_PROXY
プロキシ全体の使用を無効にする、単一のアスタリスクか、またはプロキシが使用されるべきでないホストのコンマか空白で分離されたリストのいずれかです。
no_proxy
互換性のために NO_PROXY と同じです。
SSL_ALLOW_SSL2
(推奨されない) 接続を交渉するとき、SSL バージョン 2 を許可します。
SSL_CA_CERT_FILE
信頼された CA 証明書を含んでいる CA 証明書バンドル。デフォルト値は、次の通りです: /etc/ssl/cert.pem
SSL_CA_CERT_PATH
信頼された CA ハッシュを含んでいるパス。
SSL_CLIENT_CERT_FILE
PEM は、クライアント証明書の認証で使用されるクライアント証明書/キーをエンコードされました。
SSL_CLIENT_KEY_FILE
PEM は、キーとクライアント証明書が別々に格納された場合に、クライアントキーをエンコードしました。
SSL_CRL_FILE
証明書の取り消しリストを含んでいるファイル。
SSL_NO_SSL3
接続を交渉するとき、SSL バージョン 3 を許可しません。
SSL_NO_TLS1
接続を交渉するとき、TLV バージョン 1 を許可しません。
SSL_NO_VERIFY_HOSTNAME
設定されるなら、ホスト名がサーバによって与えられる証明書の主題と一致することを検証しません。
SSL_NO_VERIFY_PEER
設定されるなら、信頼された CA に対するピアの証明書を検証しません。

使用例

proxy.example.com ポート 8080 上のプロキシサーバにアクセスするためには、これに似たやり方で HTTP_PROXY 環境変数を設定します。

HTTP_PROXY=http://proxy.example.com:8080

プロキシサーバが認証を要求するなら、認証データを渡すことに利用可能な 2 つのオプションがあります。最初の方法は、プロキシ URL を使用することです。

HTTP_PROXY=http://<user>:<pwd>@proxy.example.com:8080

2 つめの方法は、 HTTP_PROXY_AUTH 環境変数を使用することです。

HTTP_PROXY=http://proxy.example.com:8080 
HTTP_PROXY_AUTH=basic:*:<user>:<pwd>

ローカルホストで実行される HTTP サーバのためのプロキシの使用を無効にするには、次のように NO_PROXY を定義します:

NO_PROXY=localhost,127.0.0.1

いかなる証明書の検証なしで HTTPS ウェブサイトをアクセスします:

SSL_NO_VERIFY_PEER=1 
SSL_NO_VERIFY_HOSTNAME=1

クライアント証明書に基づいた認証とプライベートな CA を使用して HTTPS ウェブサイトをアクセスします:

SSL_CLIENT_CERT_FILE=/path/to/client.pem 
SSL_CA_CERT_FILE=/path/to/myca.pem

関連項目

fetch(1), ftpio(3), ip(4) J. Postel and J. K. Reynolds, File Transfer Protocol, October 1985, RFC959. P. Deutsch, A. Emtage, and A. Marine., How to Use Anonymous FTP, May 1994, RFC1635. T. Berners-Lee, L. Masinter, and M. McCahill, Uniform Resource Locators (URL), December 1994, RFC1738. R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, and T. Berners-Lee, Hypertext Transfer Protocol -- HTTP/1.1, January 1999, RFC2616. J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, and L. Stewart, HTTP Authentication: Basic and Digest Access Authentication, June 1999, RFC2617.

歴史

fetch ライブラリは、 FreeBSD 3.0 ではじめて登場しました。

作者

fetch ライブラリは、 Jordan K. Hubbard <jkh@FreeBSD.org>, Eugene Skepner <eu@qub.com>, Hajimu Umemoto <ume@FreeBSD.org>, Henry Whincup <henry@techiebod.com>, Jukka A. Ukkonen <jau@iki.fi>, Jean-François Dockes <jf@dockes.org>, Michael Gmelin <freebsd@grem.de>とその他から多数の提案と貢献がありましたが、 Dag-Erling Smørgrav <des@FreeBSD.org>によってほとんど書かれました。それは、 Poul-Henning Kamp <phk@FreeBSD.org>と Jordan K. Hubbard <jkh@FreeBSD.org>によって書かれたより古い ftpio ライブラリを置き換えます。

このマニュアルページは、 Dag-Erling Smørgrav <des@FreeBSD.org>と Michael Gmelin <freebsd@grem.de>によって書かれました。

バグ

ライブラリのいくつかの部品は、まだ実装されていません。この最も顕著な例は、 fetchPutHTTP(), fetchListHTTP(), fetchListFTP() と FTP プロキシのサポートです。

必要に応じて、 HTTP_PROXY または FTP_PROXY の環境変数を設定すること以外に実行時にプロキシを選択する方法は、ありません。

libfetch は、(プロキシを使用する) 305 の返答を理解もしないし従いもしません。

エラー番号は、特定のコンテキスト内でのみユニークです。リゾルバとシステムのエラーのために使用されたものが行うように、FTP と HTTP のために使用されたエラーコードは、オーバラップします。例えば、エラーコード 202 は、FTP コンテキストでは、 "Command not implemented, superfluous at this site" (実装されていないコマンド、このサイトで余分) と HTTP コンテキストでは、 "Accepted" (受け付けられた) を意味します。

fetchStatFTP() は、MDTM コマンドの結果が有効な日付であることをチェックしません。

保護されたパスワードの場合に、キーは、ライアント証明書に基づいた認証に使用され、ユーザは、ありとあらゆるフェッチ (取って来る) 操作でパスワードのためにプロンプトが出されます。

マニュアルページは、不完全で、出来が悪く、ひどく書式化されたテキストを生成します。

エラー報告メカニズムは、不出来です。

コードのいくつかの部分は、完全にリエントラントではありません。

July 30, 2013 FreeBSD