.\" Copyright (c) 1996 Jordan Hubbard (jkh@FreeBSD.org)
.\" 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 JORDAN HUBBARD ``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: ftpio.3,v 1.17 1998/03/19 07:34:09 charnier Exp %
.\"
.\" $FreeBSD$
.Dd June 17, 1996
.Dt ftpio 3
.Os
.Sh 名称
.Nm ftpLogin ,
.Nm ftpChdir ,
.Nm ftpErrno ,
.Nm ftpGetModtime ,
.Nm ftpGetSize ,
.Nm ftpGet ,
.Nm ftpPut ,
.Nm ftpBinary ,
.Nm ftpPassive ,
.Nm ftpVerbose ,
.Nm ftpGetURL ,
.Nm ftpPutURL
.Nd FTPIO ユーザライブラリ
.Sh 書式
.Fd #include <ftpio.h>
.Ft FILE *
.Fn ftpLogin "char *host" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
.Ft int
.Fn ftpChdir "FILE *stream, char *dirname"
.Ft int
.Fn ftpErrno "FILE *stream"
.Ft const char *
.Fn ftpErrString "int errno"
.Ft time_t
.Fn ftpGetModtime "FILE *stream, char *file"
.Ft off_t
.Fn ftpGetSize "FILE *stream, char *file"
.Ft FILE *
.Fn ftpGet "FILE *stream, char *file, off_t *seekto"
.Ft FILE *
.Fn ftpPut "FILE *stream, char *file"
.Ft int
.Fn ftpAscii "FILE *stream"
.Ft int
.Fn ftpBinary "FILE *stream"
.Ft int
.Fn ftpPassive "FILE *stream, int status"
.Ft void
.Fn ftpVerbose "FILE *stream, int status"
.Ft FILE *
.Fn ftpGetURL "char *url, char *user, char *passwd, int *retcode"
.Ft FILE *
.Fn ftpPutURL "char *url, char *user, char *passwd, int *retcode"

.Sh 解説
この関数は、FTP コネクションを管理するための
高レベルなライブラリを実装します。
.Pp
.Fn ftpLogin
は、指定された
.Fa user ,
.Fa passwd ,
.Fa ftp_port
(0 を渡した場合、標準 FTP ポートの 21 がデフォルトで
.Fa ftp_port
になる),
.Fa verbose
フィールドを
使用してログインしようとします。ログインに成功すれば、標準的な
ストリーム記述子が戻されます。この記述子は、後の FTP オペレーションに
渡してください。エラーが発生した場合は NULL が戻され、
.Fa retcode
には、外部サーバが戻すエラーコードが入ります。
.Pp
.Fn ftpChdir
は、サーバの CD コマンドを出し、
.Fa dir
で指定された
ディレクトリに変更しようとします。問題がなければゼロが戻されます。
問題がある場合は、サーバのエラーコードが戻されます。
.Pp
.Fn ftpErrno
は、最後のオペレーションのサーバエラーコードを戻します。
FTP のエラーコードに精通している場合は、エラーの原因の確認に有益です。
.Fn ftpErrString
は、人間が判読できるサーバエラーコードを戻します。
.Pp
.Fn ftpGet
は、
.Fa file
引数が指定するファイルを取り出し (FTP サーバのカレントディレクトリ
からの相対パスと想定される。
.Fn ftpChdir
参照)、そのファイルのための新しい FILE* ポインタを戻します。
エラーが発生した場合は NULL を戻します。
.Fa seekto
が NULL ではない場合、これが指す整数の内容は、ファイルの再開ポイント
として使用されます。つまり、戻されたストリームは、ファイルの
.Fa *seekto
バイトを指しているということです。これは、エラーで失敗した転送を
効率的に再開する際に便利です。シーク操作がエラーになった場合、
.Fa *seekto
の値はゼロになります。
.Pp
.Fn ftpGetModtime
は、
.Fa file
引数が指定するファイルの最終修正時刻を
戻します。ファイルをオープンできない場合は 0 が戻されます。
.Pp
.Fn ftpGetSize
は、
.Fa file
引数が指定するファイルのサイズをバイト単位で
戻します。ファイルをオープンできない場合は -1 が戻されます。
.Pp
.Fn ftpPut
は、
.Fa file
引数が指定する新しいファイルを作成し
(FTP サーバのカレントディレクトリからの相対パスと想定される。
.Fn ftpChdir
参照)、ファイルの新しい
.Fa stream
ポインタを戻します。エラーが発生した場合は NULL を戻します。
.Pp
.Fn ftpAscii
は、
.Fa stream
が指定する現行サーバのコネクションに
ASCII モードを設定します。
.Pp
.Fn ftpBinary
は、
.Fa stream
が指定する現行サーバのコネクションに
バイナリモードを設定します。
.Pp
.Fn ftpPassive
は、
.Fa stream
が指定する現在のサーバのコネクションのパッシブモード
(ファイアウォール用)を論理値
.Fa status
に設定します。
.Pp
.Fn ftpVerbose
は、
.Fa stream
が指定する現在のサーバのコネクションの冗長モードを論理値
.Fa status
に設定します。
.Pp
.Fn ftpGetURL
は、
.Fa URL
が指定するファイルを取り出します。これは、
サーバの
.Fa stream
が戻されないこと除けば、
.Fn ftpLogin ,
.Fn ftpChdir ,
.Fn ftpGet
を組み合わせた操作と同じとみなすことができます。
サーバとのコネクションは、ファイルが完全に読み込まれた時点で
クローズされます。複数のファイルを取り出す場合は、低レベルのルーチン
を使用してください。この方がはるかに効率的です。
.Pp
.Fn ftpPutURL
は、
.Fa URL
が指定するファイルを作成します。これは、
サーバの
.Fa stream
が戻されないことを除けば、
.Fn ftpLogin ,
.Fn ftpChdir ,
.Fn ftpPut
を組み合わせた操作と同じとみなすことができます。
サーバとのコネクションは、ファイルが完全に書き込まれた時点で
クローズされます。複数のファイルを作成する場合は、低レベルのルーチン
を使用してください。この方がはるかに効率的です。
.Sh 環境変数
.Bl -tag -width FTP_PASSIVE_MODE -offset 123
.It Ev FTP_TIMEOUT
.Tn FTP
接続を異常終了させる前に、通信相手からの応答を待つ最大時間
(秒単位) です。
.It Ev FTP_PASSIVE_MODE
パッシブモード
.Tn FTP
を強制的に使用します。
.El
.Sh バグ
こいつを徹底的に使い込むと、内部状態マシンを混乱させてしまう可能性が
ありますが、私がテストした限りでは、非常に丈夫に作られていることが
確かめてあります。
.Pp
.Sh 歴史
Poul-Henning Kamp のシステムインストレーションユーティリティ用
ftp ドライバとして始まり、Jordan Hubbard が、stdio の拡張という
より一般的な形式に変更しました。
Jean-Marc Zucconi のアイデアと拡張機能もいくつか盛り込まれています。
.Sh 作者
.An Jordan Hubbard ,
.An Poul-Henning Kamp ,
.An Jean-Marc Zucconi
.\"X kuma 1999-11-6