jpman project specific RCS keyword (jpman %Id) is obsolete, after manual entries are stored in freefall CVS repository. This old Id is useless and more worse it confuses users and bug reporters. So, this old Id is removed. Submitted by:jpman project <man-jp@jp.FreeBSD.org>
193 lines
5.1 KiB
Groff
193 lines
5.1 KiB
Groff
.\" Copyright (c) 1998, David Greenman
|
|
.\" 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 unmodified, 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.
|
|
.\"
|
|
.\" %FreeBSD: src/lib/libc/sys/sendfile.2,v 1.6.2.4 2001/03/06 16:46:06 ru Exp %
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.Dd November 5, 1998
|
|
.Dt SENDFILE 2
|
|
.Os
|
|
.Sh 名称
|
|
.Nm sendfile
|
|
.Nd ファイルをソケットに送信
|
|
.Sh ライブラリ
|
|
.Lb libc
|
|
.Sh 書式
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <sys/socket.h>
|
|
.Fd #include <sys/uio.h>
|
|
.Ft int
|
|
.Fn sendfile "int fd" "int s" "off_t offset" "size_t nbytes" "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags"
|
|
.Sh 解説
|
|
.Fn sendfile
|
|
は、記述子
|
|
.Fa fd
|
|
によって指定された通常のファイルを、記述子
|
|
.Fa s
|
|
によって指定されたストリームソケットから送信します。
|
|
.Pp
|
|
.Fa offset
|
|
引数はファイルのどこから開始すべきかを指定します。
|
|
.Fa nbytes
|
|
引数は、ファイルの何バイトを送信する必要があるかを指定します。
|
|
0 は、ファイルの終わりまで送信するという特殊な意味を持ちます。
|
|
.Pp
|
|
オプションのヘッダまたはトレーラ、またはその両方は、構造体 sf_hdtr を
|
|
指すポインタを指定することによってファイルの前と後で送信できます。
|
|
構造体 sf_hdtr の構造は次のとおりです。
|
|
.Pp
|
|
.Bd -literal -offset indent -compact
|
|
struct sf_hdtr {
|
|
struct iovec *headers; /* ヘッダ iovecs を指すポインタ */
|
|
int hdr_cnt; /* ヘッダ iovecs の数 */
|
|
struct iovec *trailers; /* トレーラ iovecs を指すポインタ */
|
|
int trl_cnt; /* トレーラ iovecs の数 */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Fa headers
|
|
ポインタと
|
|
.Fa trailers
|
|
ポインタは、NULL でない場合に構造体 iovec 構造の配列を
|
|
指します。iovec 構造体の詳細については、
|
|
.Fn writev
|
|
システムコールを参照してください。
|
|
これらの配列内の iovecs の数は、
|
|
.Fa hdr_cnt
|
|
と
|
|
.Fa trl_cnt
|
|
によって指定されます。
|
|
.Pp
|
|
NULL でない場合に、システムは、ソケット上に送信された合計バイト数を、
|
|
.Fa sbytes
|
|
によって指された変数に書込みます。
|
|
.Pp
|
|
.Fa flags
|
|
引数は現時点では未定義であり、0 に指定する必要があります。
|
|
.Pp
|
|
非ブロッキング入出力用に指定されたソケットを使用するときに、
|
|
.Fn sendfile
|
|
は要求されたよりも少ないバイトを送信することがあります。
|
|
この場合、正常に書込まれたバイト数が
|
|
.Fa *sbytes
|
|
(指定されている場合) に返され、エラー
|
|
.Er EAGAIN
|
|
が返されます。
|
|
.Sh 実装上の注釈
|
|
.Fn sendfile
|
|
の
|
|
.Fx
|
|
での実装は「0 コピー」です。すなわち、ファイルデータのコピー
|
|
が回避されるように最適化されています。
|
|
.Pp
|
|
非スレッドライブラリでは、
|
|
.Fn sendfile
|
|
は
|
|
.Va sendfile
|
|
システムコールとして実装されています。
|
|
.Pp
|
|
スレッドライブラリでは、
|
|
.Va sendfile
|
|
システムコールは
|
|
.Fn _thread_sys_sendfile
|
|
にアセンブルされ、
|
|
.Fn sendfile
|
|
は読取り用に
|
|
.Fa fd
|
|
を、書込み用に
|
|
.Fa s
|
|
をロックしてから
|
|
.Fn _thread_sys_sendfile
|
|
を呼び出す関数として実装されています。
|
|
.Fn _thread_sys_sendfile
|
|
の呼び出しがブロックする場合は、コンテキストスイッチが実行されます。
|
|
戻る前に、
|
|
.Fn sendfile
|
|
は
|
|
.Fa fd
|
|
と
|
|
.Fa s
|
|
をアンロックします。
|
|
.Sh 戻り値
|
|
正常に完了すると、
|
|
.Fn sendfile
|
|
は 0 を返します。そうでない場合は -1 が返され、
|
|
エラーを示すためにグローバル変数
|
|
.Va errno
|
|
が設定されます。
|
|
.Sh エラー
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBADF
|
|
.Fa fd
|
|
が有効なファイル記述子ではありません。
|
|
.It Bq Er EBADF
|
|
.Fa s
|
|
が有効なソケット記述子ではありません。
|
|
.It Bq Er ENOTSOCK
|
|
.Fa s
|
|
がソケットではありません。
|
|
.It Bq Er EINVAL
|
|
.Fa fd
|
|
が通常のファイルではありません。
|
|
.It Bq Er EINVAL
|
|
.Fa s
|
|
が SOCK_STREAM 型のソケットではありません。
|
|
.It Bq Er EINVAL
|
|
.Fa offset
|
|
が負であるか、または範囲外です。
|
|
.It Bq Er ENOTCONN
|
|
.Fa s
|
|
は、未接続のソケットを指しています。
|
|
.It Bq Er EPIPE
|
|
通信相手が接続を閉じてしまいました。
|
|
.It Bq Er EIO
|
|
.Fa fd
|
|
から読取り中に入出力エラーが発生しました。
|
|
.It Bq Er EFAULT
|
|
パラメータについて無効なアドレスが指定されました。
|
|
.It Bq Er EAGAIN
|
|
ソケットは非ブロッキング入出力と指定されており、ソケットバッファが
|
|
満杯であるためにすべてのデータが送信されませんでした。
|
|
sbytes が指定された場合、送信が正常に完了したバイト数が
|
|
.Fa *sbytes
|
|
内に返されます。
|
|
.El
|
|
.Sh 関連項目
|
|
.Xr open 2 ,
|
|
.Xr send 2 ,
|
|
.Xr socket 2 ,
|
|
.Xr writev 2
|
|
.Sh 歴史
|
|
.Fn sendfile
|
|
は、
|
|
.Fx 3.0
|
|
ではじめて登場しました。このマニュアルページは
|
|
.Fx 3.1
|
|
ではじめて登場しました。
|
|
.Sh 作者
|
|
.Fn sendfile
|
|
とこのマニュアルページは
|
|
.An David Greenman Aq dg@root.com
|
|
が作成しました。
|