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 url の user と pwd フィールドに書き入れるべきであり、成功すれば 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 ライブラリは、 <jkh@FreeBSD.org>, <eu@qub.com>, <ume@FreeBSD.org>, <henry@techiebod.com>, <jau@iki.fi>, <jf@dockes.org>, <freebsd@grem.de>とその他から多数の提案と貢献がありましたが、 <des@FreeBSD.org>によってほとんど書かれました。それは、 <phk@FreeBSD.org>と <jkh@FreeBSD.org>によって書かれたより古い ftpio ライブラリを置き換えます。このマニュアルページは、
<des@FreeBSD.org>と <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 |