Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
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 にエラーを示す
値を設定する。
エラー
EBADF fd が有効なファイルディスクリプターではない。
EINVAL flags に不正なビットが指定されている。または offset か nbytes が不正である。
EIO I/O エラー。
ENOMEM メモリー不足である。
ENOSPC ディスク領域不足である。
ESPIPE 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 プロジェクトのリリース 5.10 の一部である。プロジェクトの
説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。