doc/ja_JP.eucJP/man/man3/fetch.3

.\" Copyright (c) 1998 Dag-Erling Coiean Smoograv
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	%Id: fetch.3,v 1.7 1998/12/21 19:41:50 des Exp %
.\"
.\" $FreeBSD$
.\"
.Dd July 1, 1998
.Dt FETCH 3
.Os
.Sh 名称
.Nm fetchGetURL ,
.Nm fetchPutURL ,
.Nm fetchStatURL ,
.Nm fetchListURL ,
.Nm fetchParseURL ,
.Nm fetchGet ,
.Nm fetchPut ,
.Nm fetchStat ,
.Nm fetchList ,
.Nm fetchGetFile ,
.Nm fetchPutFile ,
.Nm fetchStatFile ,
.Nm fetchListFile ,
.Nm fetchGetHTTP ,
.Nm fetchPutHTTP ,
.Nm fetchStatHTTP ,
.Nm fetchListHTTP ,
.Nm fetchGetFTP ,
.Nm fetchPutFTP
.Nm fetchStatFTP
.Nm fetchListFTP ,
.Nd ファイル転送ライブラリ
.Sh 書式
.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"
.Sh 解説
この関数は、URL (Uniform Resource Locators)
を使用してファイルの取り出しとアップロードを行なう、
高レベルなライブラリを実現します。
.Pp
.Fn fetchGetURL
と
.Fn fetchPutURL
は、
.Nm fetch
ライブラリのインタフェースを構成します。
この関数は渡された URL を検査して転送手法を決め、
適切な低レベル関数を呼び出して実際の転送を実行します。
.Fa flags
引数は、転送オプションを指定するキャラクタのストリングです。
それぞれのフラグの意味はスキームによって異なるので、
以下の適切なセクションを参照してください。
.Pp
.Fn fetchStatURL
は、要求された文書のメタデータを入手し、
第 2 引数が指す構造体にデータを入力しようとします。
.Fa url_stat
構造体は、
.Aq Pa fetch.h
で以下のように定義されています。
.Bd -literal
struct url_stat {
    off_t        size;
    time_t       atime;
    time_t       mtime;
};
.Ed
.Pp
.Fn fetchListURL
は、指定された URL が指すディレクトリの内容をリストしようとします。
問題がなければ、malloc で割り振られた
.Fa url_ent
構造体の配列を戻します。
.Fa url_ent
構造体は、
.Aq Pa fetch.h
で以下のように定義されています。
.Bd -literal
struct url_ent {
    char         name[MAXPATHLEN];
    struct url_stat stat;
};
.Ed
.Pp
リストは、名前がないエントリで終わります。
.Pp
.Fn fetchListURL
が戻すポインタは、
.Fn free
で解放してください。
.Pp
.Fn fetchParseURL
はナル文字で終わるストリングの URL を取り、RFC1738 に規定されている
Common Internet Scheme Syntax に従って、その URL を
コンポーネント関数に分割します。
このシンタックスを作る正規表現は以下のとおりです。
.Bd -literal
    <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
.Ed
.Pp
URL の一部のコンポーネントは、
すべての URL スキームで重要ではないことがあることに注意してください。
たとえばファイルスキームでは、<scheme> コンポーネントと
<document> コンポーネントしか必要ありません。
.Pp
.Fn fetchParseURL
が戻すポインタは、
.Fn free
で解放してください。
.Pp
.Fn fetchGet
、
.Fn fetchPut
、
.Fn fetchStat
は、ポインタの形式の事前解析済み URL がストリングではなく
.Fa struct url
で必要になることを除けば、
.Fn fetchGetURL
、
.Fn fetchPutURL
、
.Fn fetchStatURL
に似ています。
.Pp
すべての
.Fn fetchGetXXX
関数と
.Fn fetchPutXXX
関数は、要求された文書からのデータの読込みや要求された文書へのデータの
書込みに使用できるストリームのポインタを戻します。
それぞれのアクセス手法のシステム詳細は異なりますが、
.Fn fetchGetXXX
関数が戻すストリームは読込み専用で、
.Fn fetchPutXXX
が戻すストリームは書込み専用であると一般的に仮定されます。
.Sh ファイルスキーム
.Fn fetchGetFile
と
.Fn fetchPutFile
では、ローカルにマウントされたファイルシステムのファイルである文書に
アクセスできます。URL の <document> コンポーネントのみが使用されます。
.Pp
.Fn fetchGetFile
はフラグを受け入れません。
.Pp
.Fn fetchPutFile
は、
.Fa a
フラグ (ファイルに追加) を受け入れます。
このフラグを指定した場合、
.Fn fetchPutFile
が戻すストリームへ書き込まれたデータは、
ファイルの前の内容を置き換えるのではなくファイルの前の内容に追加されます。
.Sh FTP スキーム
.Fn fetchGetFTP
と
.Fn fetchPutFTP
は、RFC959 に記述されているように FTP プロトコルを実現します。
.Pp
.Fa p
フラグ (受動) を指定すると、能動的ではなく受動的な接続が試されます。
.Pp
ユーザ名かパスワードを指定しないと、
.Nm fetch
ライブラリは、ユーザ名 "ftp"、パスワード "ftp" で匿名ログインを試します。
.Sh HTTP スキーム
.Fn fetchGetHTTP
関数と
.Fn fetchPutHTTP
関数は、HTTP/1.1 プロトコルを実現します。
この関数は、RFC2068 に準拠する可能性があります。
.Pp
.Nm fetch
ライブラリと調和する方法で
HTTP PUT 手法を実現する適切な方法がないようなので、
.Fn fetchPutHTTP
は現在のところ実現されていません。
.Sh 戻り値
.Fn fetchParseURL
は、URL のそれぞれのコンポーネントを含む
.Fa struct url
のポインタを戻します。メモリを割り振れない場合、
または URL のシンタックスが 正しくない場合、
.Fn fetchParseURL
は NULL ポインタを戻します。
.Pp
.Fn fetchStat
関数は、問題がなければ 0 を戻し、問題がある場合は -1 を戻します。
.Pp
その他すべての関数は、要求された文書へのアクセスに使用できる
ストリームのポインタを戻します。
エラーが発生した場合は NULL を戻します。
.Pp
.Nm Libfetch
は、Common Error Library
.Nm ( libcom_err )
を使用してエラーを報告します。
.Fn com_err
に渡されるエラーコードは以下のとおりです。
.Bl -tag -width Er
.It Bq Er FETCH_ABORT
オペレーションが異常終了しました。
.It Bq Er FETCH_AUTH
認証がエラーになりました。
.It Bq Er FETCH_DOWN
サービスが使用できません。
.It Bq Er FETCH_EXISTS
ファイルが存在します。
.It Bq Er FETCH_FULL
ファイルシステムの容量が不足しています。
.It Bq Er FETCH_INFO
情報としての応答です。
.It Bq Er FETCH_MEMORY
メモリが不足しています。
.It Bq Er FETCH_MOVED
ファイルが移動されました。
.It Bq Er FETCH_NETWORK
ネットワークエラー
.It Bq Er FETCH_OK
エラーはありません。
.It Bq Er FETCH_PROTO
プロトコルエラー
.It Bq Er FETCH_RESOLV
リゾルバエラー
.It Bq Er FETCH_SERVER
サーバエラー
.It Bq Er FETCH_TEMP
一時的なエラー
.It Bq Er FETCH_TIMEOUT
オペレーションがタイムアウトになりました。
.It Bq Er FETCH_UNAVAIL
ファイルが使用できません。
.It Bq Er FETCH_UNKNOWN
未知のエラー
.It Bq Er FETCH_URL
URL が正しくありません。
.El
.Pp
エラーメッセージには、
"File is not available (404 Not Found)" のように、
プロトコルのエラーコードとメッセージが組み込まれます。
.Sh 環境変数
FTP と HTTP に関連した関数は、
ファイル転送に使用するプロキシサーバのアドレスとして、
.Ev HTTP_PROXY
環境変数と
.Ev FTP_PROXY
環境変数を使用します。
.Sh 関連項目
.Xr com_err 3 ,
.Xr fetch 1 ,
.Xr ftpio 3
.Rs
.%A T. Berners-Lee
.%A L. Masinter
.%A M. McCahill
.%D December 1994
.%T Uniform Resource Locators (URL)
.%O RFC1738
.Re
.Rs
.%A R. Fielding
.%A J. Gettys
.%A J. Mogul
.%A H. Frystyk
.%A T. Berners-Lee
.%D Januray 1997
.%T Hypertext Transfer Protocol -- HTTP/1.1
.%O RFC2068
.Re
.Rs
.%A J. Postel
.%A J. K. Reynolds
.%D October 1985
.%T File Transfer Protocol
.%O RFC959
.Re
.Sh 注
.Nm fetch
ライブラリは Common Error ライブラリを使用するので、
.Nm libfetch
にリンクするアプリケーションは、
.Nm libcom_err
にもリンクする必要があります。
.Sh 歴史
.Nm fetch
ライブラリは、
.Fx 3.0
に追加されました。
.Sh 作者
.Nm 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
が作成した
.Nm ftpio
が置き換えられました。
.Pp
このマニュアルページの筆者は、
.An Dag-Erling Coidan Smograv Aq des@FreeBSD.org
です。
.Sh バグ
.Fn fetchPutHTTP
、
.Fn fetchStatHTTP
、
.Fn fetchListHTTP
、
.Fn fetchListFTP
、FTP プロキシサポートなど、ライブラリの一部はまだ実現されていません。
.Pp
.Ev HTTP_PROXY
環境変数か
.Ev FTP_PROXY
環境変数を適切に設定する以外、
プロキシを実行時に選択する方法はありません。
この環境変数を設定した場合は、
FTP 関数と HTTP 関数によるプロキシの使用を止めることはできません。
.Pp
HTTP 認証は動作しません。調査した範囲では、
コードにバグがあるとは言い切れません。
.Nm libfetch
は HTTP/1.1 基本認証を RFC2068 のとおりに正しく処理しますが、
HTTP サーバは、認証のヘッダフィールドを受け入れません。また
.Nm libfetch
は、HTTP サーバの認証要求を解釈してそれに応答しようとしません。
.Pp
URL でスペースなどをエンコードする試みはなされていません。
URL の文書部分のスペースは、HTTP URL で "%20" に、
FTP URLで "\\ " に置き換える必要があります。
.Pp
エラー番号は、特定コンテキストのみで一意です。
FTP と HTTP で使用するエラーコード、
およびリゾルバとシステムのエラーで使用するエラーコードは重複します。
たとえばエラーコード 202 は、FTPでは "Command not implemented,
superfluous at this site" を表し、HTTP では "Accepted" を表します。
.Pp
このマニュアルページは不十分で、
テキストのフォーマットも揃っていません。
.Pp
その他にも多くのことがあります。