Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
splice - パイプとの間でデータを継ぎ合わせる
書式
#define _GNU_SOURCE /* feature_test_macros(7) 参照 */
#include <fcntl.h>
ssize_t splice(int fd_in, loff_t *off_in, int fd_out,
loff_t *off_out, size_t len, unsigned int flags);
説明
splice() は、カーネルアドレス空間とユーザーアドレス空間との間のコピーを伴わずに、 2 つのファイルディスク
リプター間でデータの移動を行う。 ファイルディスクリプター fd_in からファイルディスクリプター fd_out へ最
大 len バイトを転送する。 2 つのファイルディスクリプターのうち一つは パイプを参照していなければならない。
fd_in と off_in には以下のルールが適用される。
* fd_in がパイプを参照している場合、 off_in は NULL でなければならない。
* fd_in がパイプを参照しておらず、かつ off_in が NULL の場合、 バイトは fd_in のファイルオフセットから読
み出され、 ファイルオフセットは適切に調整される。
* fd_in がパイプを参照しておらず、 off_in が NULL でない場合、 off_in は fd_in からのデータ読み出しを開
始する先頭オフセットを格納したバッファー へのポインターでなければならない。この場合、 fd_in のファイル
オフセットは変更されない。
fd_out と off_out に関しても同様である。
flags 引数には、以下の値の 0 個以上をビット毎の論理和の形で指定する。
SPLICE_F_MOVE
ページのコピーでなく移動を試みる。 これはカーネルに対するヒントでしかない。 つまり、カーネルがパイ
プからページを移動できない場合や、 パイプバッファーがページ全部を参照していない場合は、 ページのコ
ピーが行われることもある。 このフラグの最初の実装にはバグがあった。そのため、 Linux 2.6.21 以降で
はこのフラグの操作はできないようになっている (ただし、 splice() コールでこのフラグを指定することは
今も認められている)。 将来、正しい実装が行われることだろう。
SPLICE_F_NONBLOCK
入出力時に停止 (block) しない。 このフラグを指定すると、 splice によるパイプ操作を非停止モード
(nonblocking) で 行おうとするが、その場合でも splice() は停止することもある。なぜなら、データのや
り取りを行う ファイルディスクリプターは (O_NONBLOCK フラグをセットされていない場合) 停止する可能性
があるからである。
SPLICE_F_MORE
この後の splice でさらに転送されるデータがあることを示す。 このフラグは fd_out がソケットを参照し
ている場合に有用なヒントとなる (send(2) の MSG_MORE や tcp(7) の TCP_CORK の説明も参照)。
SPLICE_F_GIFT
splice() では使用しない。 vmsplice(2) 参照。
返り値
Upon successful completion, splice() returns the number of bytes spliced to or from the pipe.
A return value of 0 means end of input. If fd_in refers to a pipe, then this means that there was no
data to transfer, and it would not make sense to block because there are no writers connected to the
write end of the pipe.
エラーの場合、 splice() は -1 を返し、 errno にエラーを示す値を設定する。
エラー
EAGAIN SPLICE_F_NONBLOCK was specified in flags or one of the file descriptors had been marked as
nonblocking (O_NONBLOCK), and the operation would block.
EBADF ファイルディスクリプターの一方または両方が有効ではない、 もしくは適切な read-write モードではな
い。
EINVAL The target filesystem doesn't support splicing.
EINVAL The target file is opened in append mode.
EINVAL どのファイルディスクリプターもパイプを参照していない。
EINVAL An offset was given for nonseekable device (e.g., a pipe).
EINVAL fd_in と fd_out が同じパイプを参照している。
ENOMEM メモリー不足。
ESPIPE off_in か off_out のいずれかが NULL ではないが、対応するファイルディスクリプターが パイプを参照し
ている。
バージョン
splice() システムコールは Linux 2.6.17 で初めて登場した。 ライブラリによるサポートは glibc バージョン 2.5
で追加された。
準拠
このシステムコールは Linux 固有である。
注意
3 つのシステムコール (splice(), vmsplice(2), tee(2)) を使うと、ユーザー空間プログラムは任意のカーネルバッ
ファーに対する 完全な制御ができる。カーネルバッファーは、パイプに使用されているのと 同種のバッファーを
使ってカーネル内に実装されている。 大まかにいうと、これらのシステムコールは以下の仕事を行う:
• splice() は、バッファーから任意のファイルディスクリプターや、その逆方向、 もしくはあるバッファーから別
のバッファーへの、データ移動を行う。
• tee(2) は、あるバッファーから別のバッファーへのデータ「コピー」を行う。
• vmsplice(2) は、ユーザー空間からバッファーへのデータ「コピー」を行う。
ここではコピーの話をしているが、実際のコピーは一般的に回避される。 カーネルは、パイプバッファーをカーネル
メモリーのページへのポインター集合として 実装し、ページへの参照回数を管理することで、これを実現している。
カーネルは、対象となるページを参照する (出力バッファー用の) ポインターを 新規に作成することでバッファー内
のページの「コピー」を作成し、 そのページの参照回数を増やす。つまり、ポインターだけがコピーされ、 バッ
ファーのページはコピーされない。
In Linux 2.6.30 and earlier, exactly one of fd_in and fd_out was required to be a pipe. Since Linux
2.6.31, both arguments may refer to pipes.
例
tee(2) 参照。
関連項目
copy_file_range(2), sendfile(2), tee(2), vmsplice(2), pipe(7)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告
に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。
Linux 2020-06-09 SPLICE(2)