名称

sendfile — ファイルをソケットに送信

ライブラリ

Standard C Library (libc, -lc)

書式

#include < sys/types.h>
#include < sys/socket.h>
#include < sys/uio.h>

int
sendfile( int fd, int s, off_t offset, size_t nbytes, struct sf_hdtr *hdtr, off_t *sbytes, int flags);

解説

sendfile() システムコールは、記述子 fd によって指定された通常のファイルを、記述子 s によって指定されたストリームソケットから送信します。

offset 引数は、ファイルのどこから開始すべきかを指定します。 offset がファイルの終りを超えていた場合は、システムは、次に説明されるように成功を返して、0 バイトを送信したと報告します。 nbytes 引数は、ファイルの何バイトを送信する必要があるかを指定します。 0 は、ファイルの終わりまで送信するという特殊な意味を持ちます。

オプションのヘッダまたはトレーラ、またはその両方は、構造体 sf_hdtr を指すポインタを指定することによってファイルの前と後で送信できます。 struct sf_hdtr の構造は、次の通りです:

struct sf_hdtr { 
 struct iovec *headers;  /* ヘッダ iovecs を指すポインタ */ 
 int hdr_cnt;            /* ヘッダ iovecs の数 */ 
 struct iovec *trailers; /* トレーラ iovecs を指すポインタ */ 
 int  trl_cnt;           /* トレーラ iovecs の数 */ 
};

headers ポインタと trailers ポインタは、 NULL でない場合に struct iovec 構造体の配列を指します。 iovec 構造体の詳細については、 writev() システムコールを参照してください。これらの配列内の iovecs の数は、 hdr_cnt と trl_cnt によって指定されます。

NULL でない場合に、システムは、ソケット上に送信された合計バイト数を、 sbytes によって指された変数に書き込みます。

flags 引数は、これらの値のビットマップです:

• SF_NODISKIO。このフラグは、ディスク入出力でブロックされるであろうすべての sendfile() 呼び出しに対して、代わりに EBUSY を返させます。ブロックされる転送要求を 1 つの分離された入出力ワーカスレッドにすることで、忙しいサーバには役に立つことがあります。
• SF_MNOWAIT。利用可能となるいくつかのカーネルリソース、特に mbuf と sf_buf、のためにウェートしません。このフラグは、他のリソースが、ブロッキングの方法でまだ割り当てられているので、 sendfile() システムコールを本当に、非ブロッキングにしません。
• SF_SYNC。 sendfile は、ネットワークスタックが、その後の変更を安全にする、ファイルの VM ページをもはや参照しなくなるまで、スリープします。これは、データが実際に送信されたことを保証しないことに注意してください。

非ブロッキング入出力用に指定されたソケットを使用するときに、 sendfile() は、要求されたよりも少ないバイトを送信することがあります。この場合、正常に書き込まれたバイト数が *sbytes (指定されている場合) に返され、エラー EAGAIN が返されます。

実装に関する注

sendfile() の FreeBSD での実装は、「0 コピー」です。すなわち、ファイルデータのコピーが回避されるように最適化されています。

チューニング

いくつかのアーキテクチャに関して、このシステムコールは、内部でクライアントへの送信ファイルデータを取り扱うために、特別な sendfile() バッファ ( struct sf_buf) を使用します。送信ソケットがブロックされていて、利用可能な sendfile() バッファが十分でない場合には、 sendfile() は、ブロックされ、“ sfbufa”の状態を報告します。送信ソケットがブロックされておらず、利用可能な sendfile() バッファが十分でない場合には、この呼び出しはブロックされ、呼び出しを終了する前に必要なバッファが利用可能になるのを待ちます。

sf_buf の割り当てられた数は、 sendfile() を介してクライアントにデータを送信するために使用される nmbclusters の数に、比例しているべきです。ブロッキングを避けるために適宜にチューンしましょう! sendfile() を広範囲に使用する忙しい装置が、 kern.ipc.nmbclusters に展開されるこれらの値を増加させたくなるかもしれません (詳細は、 tuning(7) を参照してください)。

利用可能な sendfile() バッファの数は、 loader.conf(5) の中の kern.ipc.nsfbufs 変数または NSFBUFS カーネルコンフィギュレーション調整のどちらかによって、ブート時に決定されます。 sendfile() バッファの数は、 kern.maxusers に合わせて調整されます。 kern.ipc.nsfbufsused および kern.ipc.nsfbufspeak の読み込み専用の sysctl(8) 変数は、現在とピークの sendfile() バッファの使用量をそれぞれ表します。これらの値は、 netstat -m を通しても見ることができます。

kern.ipc.nsfbufs の値が 0 と報告されるなら、利用者のアーキテクチャは、一般的な仮想メモリ構造によって効率的に、それらのタスクを実行することができるので、 sendfile() バッファを使用する必要はありません。

戻り値

The sendfile() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

エラー

[ EAGAIN]

ソケットは、非ブロッキング入出力と指定されており、ソケットバッファが満杯であるためにすべてのデータが送信されませんでした。 sbytes が指定された場合、送信が正常に完了したバイト数が *sbytes 内に返されます。

[ EBADF]

fd 引数が有効なファイル記述子ではありません。

[ EBADF]

s 引数が有効なソケット記述子ではありません。

[ EBUSY]

完全な転送を完了するには、ディスク入出力が必要となるため、中断されました。部分的なデータは、送られたかもしれません (このエラーは、 SF_NODISKIO が指定されたときのみ起こります)。

[ EFAULT]

引数について無効なアドレスが指定されました。

[ EINTR]

sendfile() が完了する前にシグナルが割り込みました。 *sbytes が指定された場合には、成功裏に送出されたバイト数がここに格納されます。

[ EINVAL]

fd 引数が通常のファイルではありません。

[ EINVAL]

s 引数が SOCK_STREAM 型のソケットではありません。

[ EINVAL]

offset 引数が負です。

[ EIO]

fd から読み込み中に入出力エラーが発生しました。

[ ENOBUFS]

システムは、内部バッファを割り付けることができませんでした。

[ ENOTCONN]

s 引数が、未接続のソケットを指しています。

[ ENOTSOCK]

s 引数がソケットではありません。

[ EOPNOTSUPP]

記述子 fd のファイルシステムが、 sendfile() をサポートしていません。

[ EPIPE]

通信相手が接続を閉じてしまいました。

関連項目

netstat(1), open(2), send(2), socket(2), writev(2), tuning(7) K. Elmeleegy, A. Chanda, A. L. Cox, and W. Zwaenepoel, A Portable Kernel Abstraction for Low-Overhead Ephemeral Mapping Management, The Proceedings of the 2005 USENIX Annual Technical Conference, pp 223-236, 2005.

歴史

sendfile() システムコールは、 FreeBSD 3.0 ではじめて登場しました。このマニュアルページは、 FreeBSD 3.1 ではじめて登場しました。

作者

sendfile() システムコールとこのマニュアルページは、 David G. Lawrence <dg@dglawrence.com>によって書かれました。