名前
sync_file_range - sync a file segment with disk
書式
#define _GNU_SOURCE
#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 (キャッシュだけが変更されている) ページの 書き出しを開始する。 | |
| SYNC_FILE_RANGE_WAIT_AFTER | |
| 何らかの書き込み後に、指定された領域の全てのページの 書き出しが行われるのを待つ。 | |
詳細
これらの操作ではどれもファイルのメタデータの書き出しを行わない。 したがって、アプリケーションが確実に作成済みのディスクブロックの 上書きを実行しない限り、クラッシュの後でもデータが利用可能である 保証はない。
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 | |
| これは、昔からある fdatasync(2) 操作そのものである。 これは write-for-data-integrity 操作 (データ完全性確保のための書き込み) であり、指定された範囲内の、 sync_file_range() が呼ばれた時点で dirty な全てのページが ディスクに格納されることが保証される。 | |
返り値
成功の場合、 sync_file_range() は 0 を返す。失敗の場合、-1 を返し、 error にエラーを示す値を設定する。
エラー
| EBADF | fd が有効なファイルディスクリプタではない。 |
| EIO | I/O エラー。 |
| EINVAL | flags に不正なビットが指定されている。または offset か nbytes が不正である。 |
| ENOMEM | メモリ不足である。 |
| ENOSPC | ディスク領域不足である。 |
| ESPIPE | fd が、通常のファイル、ブロックデバイス、ディレクトリ、シンボリックリンク 以外のものを指している。 |
バージョン
sync_file_range() はカーネル 2.6.17 で Linux に登場した。
準拠
このシステムコールは Linux 独自であり、 移植性が必要なプログラムでは使用を避けるべきである。
関連項目
fdatasync(2), fsync(2), msync(2), sync(2), feature_test_macros(7)
