ИМЯ

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 равно нулю, то синхронизируются все байты, начиная с offset и до конца файла. Синхронизация выполняется в единицах размера системной страницы: значение offset округляется к меньшей границе страницы; (offset+nbytes-1) округляется к большей границе страницы.

В битовую маску аргумент flags можно включать следующие значения:

SYNC_FILE_RANGE_WAIT_BEFORE: Перед выполнением записи ждать, пока будут перезаписаны все страницы в указанном диапазоне, которые уже были отправлены в драйвер устройства.
SYNC_FILE_RANGE_WRITE: Начать перезапись всех изменённых страниц в указанном диапазоне, которые к настоящему моменту не были перезаписаны. Заметим, что это может привести к блокировке, если вы пытаетесь записать больше размера очереди запросов.
SYNC_FILE_RANGE_WAIT_AFTER: После выполнения записи ждать, пока не перезапишутся все страницы в диапазоне.

Указание 0 в flags допустимо; никаких действий выполнено не будет.

Предупреждение

Данный системный вызов очень опасен и не должен использоваться в переносимых программах. Ни одна из этих операций перезаписи не касается метаданных файла. Поэтому, если приложение строго не выполняет перезаписи уже выделенных дисковых блоков, то нет никаких гарантий, что данные будут будьте доступны после катастрофического отказа. Не существует пользовательского интерфейса, который позволял бы узнать, действительно ли выполнилась перезапись. В файловых системах, использующих семантику копирования при записи (например, btrfs) перезапись существующих выделенных блоков невозможна. Когда запись выполняется в уже выделенное пространство, многие файловые системы также вызывают выделитель блоков, которые данный системный вызов не синхронизирует с диском. Данный системный вызов не выполняет сброс дисковых кэшей для записи и поэтому не предоставляет какой-либо целостности данных в системах с изменчивыми дисковыми кэшами на запись.

Некоторые подробности

При SYNC_FILE_RANGE_WAIT_BEFORE и SYNC_FILE_RANGE_WAIT_AFTER будут обнаруживаться все ошибки ввода-вывода или условия ENOSPC, и они будут возвращены вызвавшему.

Полезные комбинации битов в flags:

SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE: Гарантировать, что все изменённые страницы в указанном диапазоне при вызове sync_file_range() помещаются для записи. Это начало операции по целостной записи данных.
SYNC_FILE_RANGE_WRITE: Начать запись всех изменённых страниц указанного диапазона, которые ещё не были размещены для записи. Это анонимная операция сброса данных на диск. Она не подходит для операций целостности данных.
SYNC_FILE_RANGE_WAIT_BEFORE (или 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: Это операция по целостной записи данных, которая позволит быть уверенным, что все изменённые на момент вызова sync_file_range() страницы указанного диапазона записаны на диск.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

При успешном выполнении sync_file_range() возвращает 0. При ошибке возвращается -1, и errno устанавливается в соответствующее значение.

ОШИБКИ

EBADF: Значение fd не является правильным файловым дескриптором.
EINVAL: В flags указан некорректный бит; или некорректное значение в offset или nbytes.
EIO: Ошибка ввода-вывода.
ENOMEM: Не хватает памяти.
ENOSPC: Недостаточно места на диске.
ESPIPE: Значение fd ссылается не на обычный файл, блочное устройство, или каталог.

ВЕРСИИ

Вызов sync_file_range() появился в Linux в ядре версии 2.6.17.

СООТВЕТСТВИЕ СТАНДАРТАМ

Данный системный вызов есть только в 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().

Системный вызов с таких объявлением впервые появился для архитектуры ARM в Linux 2.6.20 под именем arm_sync_file_range(). В Linux 2.6.22 он был переименован, так как аналогичный системный вызов был добавлен для PowerPC. Для архитектур, поддерживаемых glibc, glibc прозрачно обёртывает sync_file_range2() именем sync_file_range().

ИМЯ