SENDFILE
Section: Linux Programmer's Manual (2)
Updated: 2017-09-15
Index
JM Home Page
roff page
名前
sendfile - ファイルディスクリプター間でデータを転送する
書式
#include <sys/sendfile.h>
ssize_t sendfile(int out_fd, int in_fd, off_t *offset,
size_t count);
説明
sendfile() は、あるファイルディスクリプターから別の ファイルディスクリプターへのデータのコピーを行う。
このコピーはカーネル内で行われるので、 sendfile() は、 read(2) と write(2)
を組み合わせるよりも効率がよい。 read(2) や write(2) ではユーザー空間との間でデータの転送が必要となるからである。
in_fd は読み込みのためにオープンされたファイルディスクリプター、 out_fd
は書き込みのためにオープンされたディスクリプターでなければならない。
offset が NULL でない場合、 offset は sendfile() が in_fd
のどこからデータを読み始めるかを示すファイルオフセットを保持する変数への ポインターである。 sendfile()
は復帰する時、この変数に最後に読み込んだバイトの 次のバイトのオフセットを書き込む。 offset が NULL でない場合、
sendfile() は in_fd のファイルオフセットを変更しない。 NULL の場合は、ファイルオフセットを in_fd
から読み込んだバイト数を反映した位置に調整する。
offset が NULL の場合、データは in_fd のファイルオフセットから読み出され、
ファイルオフセットはこの呼び出しで更新される。
count は、ファイルディスクリプター間でコピーするバイト数である。
in_fd 引数は mmap(2) 風の操作ができるファイルを指していなければならな
い (ソケットを指定することはできない)。
2.6.33 より前の Linux カーネルでは out_fd はソケットを参照していなければな
らない。Linux 2.6.33 以降では、任意のファイルを参照することができる。
通常のファイルの場合には sendfile() はファイルオフセットを適切に変更する。
返り値
If the transfer was successful, the number of bytes written to out_fd is
returned. Note that a successful call to sendfile() may write fewer
bytes than requested; the caller should be prepared to retry the call if
there were unsent bytes. See also NOTES.
エラーの場合は -1 が返され、 errno が適切に設定される。
エラー
- EAGAIN
-
O_NONBLOCK を用いて非ブロック I/O が選択されたが、書き込みがブロックされた。
- EBADF
-
入力ファイルが読み込みのためにオープンされていないか、 出力ファイルが書き込みのためにオープンされていない。
- EFAULT
-
アドレスがおかしい。
- EINVAL
-
ディスクリプターが有効でないか、ロックされている。もしくは mmap(2) 風の操作が in_fd では利用できない。もしくは
count が負である。
- EINVAL
-
out_fd has the O_APPEND flag set. This is not currently supported by
sendfile().
- EIO
-
in_fd から読み込んでいるうちに予期しないエラーが起こった。
- ENOMEM
-
in_fd から読み込むための十分なメモリーがない。
- EOVERFLOW
-
count is too large, the operation would result in exceeding the maximum
size of either the input file or the output file.
- ESPIPE
-
offset is not NULL but the input file is not seekable.
バージョン
sendfile は Linux 2.2 で初めて登場した。 インクルードファイル <sys/sendfile.h> は
glibc 2.1 から存在している。
準拠
POSIX.1-2001 や他の標準では規定されていない。
他の UNIX システムでは、異なった方式やプロトタイプで sendfile()
を実装している。移植性を考慮したプログラムでは使用すべきではない。
注意
sendfile() will transfer at most 0x7ffff000 (2,147,479,552) bytes,
returning the number of bytes actually transferred. (This is true on both
32-bit and 64-bit systems.)
sendfile() を使って TCP ソケットにファイルを送ろうとしていて、 ファイルの内容の前にヘッダーデータを付け加える必要がある場合は、
パケット数を最小にして性能を上げるために tcp(7) に記述されている TCP_CORK オプションを使うといいだろう。
In Linux 2.4 and earlier, out_fd could also refer to a regular file; this
possibility went away in the Linux 2.6.x kernel series, but was restored in
Linux 2.6.33.
元々の Linux sendfile() システムコールは大きなファイルオフセットを
扱えるように設計されていなかった。その結果、Linux 2.4 で、
ビット幅の大きな offset 引数を持った sendfile64() が追加された。
glibc の sendfile() のラッパー関数はカーネルによるこの違いを吸収している。
sendfile() が EINVAL や ENOSYS で失敗するような場合は、 アプリケーションは
read(2)/write(2) に戻すことを考えてもよいかもしれない。
If out_fd refers to a socket or pipe with zero-copy support, callers must
ensure the transferred portions of the file referred to by in_fd remain
unmodified until the reader on the other end of out_fd has consumed the
transferred data.
The Linux-specific splice(2) call supports transferring data between
arbitrary file descriptors provided one (or both) of them is a pipe.
関連項目
copy_file_range(2), mmap(2), open(2), socket(2), splice(2)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
https://www.kernel.org/doc/man-pages/ に書かれている。
Index
- 名前
-
- 書式
-
- 説明
-
- 返り値
-
- エラー
-
- バージョン
-
- 準拠
-
- 注意
-
- 関連項目
-
- この文書について
-
This document was created by
man2html,
using the manual pages.
Time: 16:46:42 GMT, November 24, 2023