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/ に書かれている。