sync_file_range(2) System Calls Manual sync_file_range(2)

ИМЯ

sync_file_range - синхронизирует сегмент файла на диске

Standard C library (libc, -lc)

СИНТАКСИС

#define _GNU_SOURCE         /* See feature_test_macros(7) */
#define _FILE_OFFSET_BITS 64
#include <fcntl.h>
int sync_file_range(int fd, off_t offset, off_t nbytes,
                    unsigned int flags);

ОПИСАНИЕ

Вызов sync_file_range() позволяет точно контролировать синхронизацию открытого файла, задаваемого файловым дескриптором fd, с диском.

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

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

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

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

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

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

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

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

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

Гарантировать, что все изменённые страницы в указанном диапазоне при вызове sync_file_range() помещаются для записи. Это начало операции по целостной записи данных.
Начать запись всех изменённых страниц указанного диапазона, которые ещё не были размещены для записи. Это анонимная операция сброса данных на диск. Она не подходит для операций целостности данных.
Ждать завершения записи всех страниц указанного диапазона. Можно использовать после операции SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE, дождаться завершения этой операции и получить её результат.
Это операция по целостной записи данных, которая позволит быть уверенным, что все изменённые на момент вызова sync_file_range() страницы указанного диапазона записаны на диск.

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

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

ОШИБКИ

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

ВЕРСИИ

Для некоторых архитектур (например, PowerPC, ARM) требуется, чтобы 64-битные аргументы были выровнены в нужных парах регистров. На таких архитектурах для объявления вызова sync_file_range(), показанного в СИНТАКСИСЕ, для заполнения между аргументами fd и offset расходовался бы ещё один регистр впустую (подробности смотрите в syscall(2)). Поэтому в этих архитектурах определён другой системный вызов с подходящим порядком аргументов:


int sync_file_range2(int fd, unsigned int flags,
                     off_t offset, off_t nbytes);

Поведение данного системного вызова такое же как sync_file_range().

СТАНДАРТЫ

Linux.

ИСТОРИЯ

Linux 2.6.17.

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

ПРИМЕЧАНИЯ

_FILE_OFFSET_BITS should be defined to be 64 in code that takes the address of sync_file_range, if the code is intended to be portable to traditional 32-bit x86 and ARM platforms where off_t's width defaults to 32 bits.

СМОТРИТЕ ТАКЖЕ

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

ПЕРЕВОД

Русский перевод этой страницы руководства разработал Alexander Golubev <fatzer2@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Hotellook, Nikita <zxcvbnm3230@mail.ru>, Spiros Georgaras <sng@hellug.gr>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику по его адресу электронной почты или по адресу списка рассылки русских переводчиков.

2 мая 2024 г. Linux man-pages 6.8