Manpages

名 前

sync_file_range − フ ァ イ ル セ グ メ ン ト を デ ィ ス ク と 同 期 す る

書 式

#define _GNU_SOURCE /* feature_test_macros(7) 参 照 */
#include <fcntl.h>

int sync_file_range(int fd, off64_t offset, off64_t nbytes,
unsigned int flags);

説 明

sync_file_range() を 使 う と 、 フ ァ イ ル デ ィ ス ク リ プ タ ー fd で 参 照 さ れ る オ ー プ ン さ れ た フ ァ イ ル の デ ィ ス ク と の 同 期 に 関 し て 、 き め 細 か な 制 御 が 可 能 と な る 。

offset は 、 同 期 を 行 う フ ァ イ ル の 領 域 の 開 始 バ イ ト で あ る 。 nbytes に は 同 期 を 行 う 領 域 の 長 さ を バ イ ト 単 位 で 指 定 す る 。 nbytes が 0 の 場 合 は 、 offset か ら フ ァ イ ル 末 尾 ま で の 全 バ イ ト を 同 期 す る 。 同 期 は シ ス テ ム の ペ ー ジ サ イ ズ の 単 位 で 行 わ れ る 。 offset は ペ ー ジ 境 界 に あ わ せ て 切 り 下 げ ら れ 、 (offset+nbytes−1) は ペ ー ジ 境 界 に あ わ せ て 切 り 上 げ ら れ る 。 ビ ッ ト マ ス ク 引 き 数 flags に は 以 下 の 値 を 指 定 す る こ と が で き る :
SYNC_FILE_RANGE_WAIT_BEFORE 何 ら か の 書 き 込 み を 行 う 前 に 、 指 定 さ れ た 領 域 の ペ ー ジ で 書 き 出 し を 行 う よ う に デ バ イ ス ド ラ イ バ に す で に 要 求 が 発 行 さ れ て い る ペ ー ジ の 書 き 出 し が 全 て 完 了 す る の を 待 つ 。
SYNC_FILE_RANGE_WRITE 指 定 さ れ た 領 域 の ペ ー ジ で 、 書 き 出 し 要 求 が 発 行 さ れ て い な い 全 て の dirty (キ ャ ッ シ ュ だ け が 変 更 さ れ て い る ) ペ ー ジ の 書 き 出 し を 開 始 す る 。 リ ク エ ス ト キ ュ ー の 大 き さ よ り 多 く 書 き 込 も う と し た 場 合 に は 、 こ の 処 理 は 停 止 (block) す る 可 能 性 が あ る 点 に 注 意 す る こ と 。
SYNC_FILE_RANGE_WAIT_AFTER 何 ら か の 書 き 込 み 後 に 、 指 定 さ れ た 領 域 の 全 て の ペ ー ジ の 書 き 出 し が 行 わ れ る の を 待 つ 。

flags に 0 を 指 定 し た 場 合 、 何 も し な い こ と を 表 す 。 警 告 こ の シ ス テ ム コ ー ル は 非 常 に 危 険 で あ り 、 移 植 性 が 必 要 な プ ロ グ ラ ム で 使 用 す べ き で は な い 。 こ れ ら の 操 作 で は ど れ も フ ァ イ ル の メ タ デ ー タ の 書 き 出 し を 行 わ な い 。 し た が っ て 、 ア プ リ ケ ー シ ョ ン に よ り 作 成 済 み の デ ィ ス ク ブ ロ ッ ク の 上 書 き の 実 行 が 確 実 に 行 わ れ な い 限 り 、 ク ラ ッ シ ュ の 後 で も デ ー タ が 利 用 で き る 保 証 は な い 。 書 き 込 み が 上 書 き だ け で あ る か を 知 る た め の ユ ー ザ ー イ ン タ ー フ ェ ー ス は 存 在 し な い 。 (btrfs な ど の ) copy−on−write 動 作 を 使 っ た フ ァ イ ル シ ス テ ム で は 、 既 存 の 割 り 当 て 済 み の ブ ロ ッ ク に 対 す る 上 書 き 自 体 が で き な い 。 前 も っ て 割 り 当 て ら れ た 領 域 に 書 き 込 み を 行 う 場 合 、 多 く の フ ァ イ ル シ ス テ ム で は block allocator へ の 書 き 込 み も 必 要 と な る が 、 こ の シ ス テ ム コ ー ル は block allocator の デ ィ ス ク へ の 同 期 を 行 わ な い 。 こ の シ ス テ ム コ ー ル は デ ィ ス ク 書 き 込 み キ ャ ッ シ ュ の フ ラ ッ シ ュ を 行 わ な い の で 、 揮 発 性 の デ ィ ス ク 書 き 込 み キ ャ ッ シ ュ を 使 っ た シ ス テ ム で は こ の シ ス テ ム コ ー ル で は デ ー タ の 一 貫 性 を 確 保 で き な い こ と に な る 。 詳 細
SYNC_FILE_RANGE_WAIT_BEFORE と SYNC_FILE_RANGE_WAIT_AFTER は I/O エ ラ ー や ENOSPC 状 態 を 検 出 し 、 呼 び 出 し 元 に こ れ ら の 情 報 を 返 す 。

flags の 役 に 立 つ ビ ッ ト の 組 み 合 わ せ を 以 下 に 示 す :
SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE 指 定 さ れ た 範 囲 内 の ペ ー ジ で 、 sync_file_range() が 呼 び 出 さ れ た 際 に dirty で あ っ た 全 て の ペ ー ジ が 、 確 実 に 書 き 出 し 対 象 と な る よ う に す る 。 こ れ は 、 start−write−for−data−integrity 操 作 (デ ー タ 完 全 性 確 保 の た め の 書 き 込 み 開 始 の 操 作 ) で あ る 。
SYNC_FILE_RANGE_WRITE 指 定 さ れ た 範 囲 内 の ペ ー ジ で 、 現 在 書 き 出 し 中 で な い 全 て の dirty ペ ー ジ の 書 き 出 し を 開 始 す る 。 こ れ は 非 同 期 の デ ィ ス ク へ の フ ラ ッ シ ュ (flush−to−disk) 操 作 で あ る 。 デ ー タ 完 全 性 確 保 が 必 要 な 操 作 と し て は 適 切 で は な い 。
SYNC_FILE_RANGE_WAIT_BEFORE (or SYNC_FILE_RANGE_WAIT_AFTER) 指 定 さ れ た 範 囲 内 の 全 て の ペ ー ジ の 書 き 出 し の 完 了 を 待 つ 。 こ の フ ラ グ は 、 前 に 行 わ れ た 操 作 SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE の 後 に 使 用 で き 、 こ の 操 作 の 完 了 を 待 ち 、 結 果 を 取 得 す る こ と が で き る 。
SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE |
SYNC_FILE_RANGE_WAIT_AFTER こ れ は write−for−data−integrity 操 作 (デ ー タ 完 全 性 確 保 の た め の 書 き 込 み ) で あ り 、 指 定 さ れ た 範 囲 内 の 、 sync_file_range() が 呼 ば れ た 時 点 で dirty な 全 て の ペ ー ジ が デ ィ ス ク に 格 納 さ れ る こ と が 保 証 さ れ る 。

返 り 値

成 功 の 場 合 、 sync_file_range() は 0 を 返 す 。 失 敗 の 場 合 、 −1 を 返 し 、 errno に エ ラ ー を 示 す 値 を 設 定 す る 。

エ ラ ー

メ モ リ ー 不 足 で あ る 。

fd が 、 通 常 の フ ァ イ ル 、 ブ ロ ッ ク デ バ イ ス 、 デ ィ レ ク ト リ 、 シ ン ボ リ ッ ク リ ン ク 以 外 の も の を 指 し て い る 。

バ ー ジ ョ ン

sync_file_range() は カ ー ネ ル 2.6.17 で Linux に 登 場 し た 。

準 拠

こ の シ ス テ ム コ ー ル は Linux 独 自 で あ り 、 移 植 性 が 必 要 な プ ロ グ ラ ム で は 使 用 を 避 け る べ き で あ る 。

注 意

sync_file_range2() い く つ か の ア ー キ テ ク チ ャ ー (例 え ば 、 PowerPC や ARM) で は 、 64 ビ ッ ト の 引 き 数 は 適 切 な レ ジ ス タ ー の 組 に 割 り 当 て る 必 要 が あ る 。 こ の よ う な ア ー キ テ ク チ ャ ー で は 、 「 書 式 」 に 書 か れ て い る sync_file_range() の 呼 び 出 し シ グ ネ チ ャ ー で 、 引 き 数 fd と offset の 間 の パ デ ィ ン グ (詰 め も の ) で レ ジ ス タ ー が 一 つ 消 費 さ れ て し ま う (詳 細 は syscall(2) 参 照 )。 そ の た め 、 こ れ ら の ア ー キ テ ク チ ャ ー で は 引 き 数 が 適 切 な 順 序 に な っ た 別 の シ ス テ ム コ ー ル が 定 義 さ れ て い る 。

int sync_file_range2(int fd, unsigned int flags,
off64_t offset, off64_t nbytes); 上 記 の 点 以 外 は 、 こ の シ ス テ ム コ ー ル の 動 作 は sync_file_range() と 全 く 同 じ で あ る 。 こ の シ ス テ ム コ ー ル に 対 す る ラ イ ブ ラ リ に よ る サ ポ ー ト は glibc で は 提 供 さ れ て い な い 。 こ の バ ー ジ ョ ン の シ ス テ ム コ ー ル は 、 Linux 2.6.20 で ARM ア ー キ テ ク チ ャ ー で 初 め て 登 場 し 、 arm_sync_file_range() と い う 名 前 で あ っ た 。 Linux 2.6.22 で 、 同 様 の シ ス テ ム コ ー ル が PowerPC 用 に 追 加 さ れ た 際 に 、 シ ス テ ム コ ー ル の 名 前 が 変 更 さ れ た 。 glibc に よ る サ ポ ー ト が 提 供 さ れ て い る ア ー キ テ ク チ ャ ー で は 、 glibc の ラ ッ パ ー 関 数 は sync_file_range() と い う 名 前 で sync_file_range2() を 適 切 に 使 用 す る よ う に な っ て い る 。

関 連 項 目

fdatasync(2), fsync(2), msync(2), sync(2)

こ の 文 書 に つ い て

こ の man ペ ー ジ は Linux man−pages プ ロ ジ ェ ク ト の リ リ ー ス 3.79 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は http://www.kernel.org/doc/man−pages/ に 書 か れ て い る 。