Man page - splice(2)

Packages contains this manual

Available languages:

en fr pl ja ru

Manual

SPLICE

名 前
書 式
説 明
返 り 値
エ ラ ー
バ ー ジ ョ ン
準 拠
注 意
例
関 連 項 目
こ の 文 書 に つ い て

名 前

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