名前

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