Объект виртуальных методов файла интерфейса ОС

typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Methods above are valid for version 1 */
  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
  void (*xShmBarrier)(sqlite3_file*);
  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
  /* Methods above are valid for version 2 */
  int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
  int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
  /* Methods above are valid for version 3 */
  /* Additional methods may be added in future releases */
};

Каждый файл, открытый методом sqlite3_vfs.xOpen, заполняет объект sqlite3_file (или, чаще, подкласс объекта sqlite3_file) указателем на экземпляр этого объекта. Этот объект определяет методы, используемые для выполнения различных операций с открытым файлом, представленным объектом sqlite3_file.

Если метод sqlite3_vfs.xOpen задаёт элемент sqlite3_file.pMethods на ненулевой указатель, то метод sqlite3_io_methods.xClose может быть вызван даже если метод sqlite3_vfs.xOpen сообщил о неудаче. Единственный способ предотвратить вызов xClose после неудачного sqlite3_vfs.xOpen — установить элемент sqlite3_file.pMethods в NULL.

Аргумент flags метода xSync может быть одним из SQLITE_SYNC_NORMAL или SQLITE_SYNC_FULL. Первый вариант — обычный fsync(). Второй вариант — полная синхронизация в стиле Mac OS X. Флаг SQLITE_SYNC_DATAONLY может быть включён с помощью операции OR, чтобы указать, что необходимо синхронизировать только данные файла, а не его inode.

Целочисленные значения для xLock() и xUnlock() являются одним из:

xLock() повышает блокировку файла базы данных. Другими словами, xLock() перемещает блокировку файла базы данных в направлении от NONE к EXCLUSIVE. Аргумент xLock() всегда является одним из SHARED, RESERVED, PENDING или EXCLUSIVE, никогда не SQLITE_LOCK_NONE. Если блокировка файла базы данных уже находится на уровне или выше запрошенной блокировки, то вызов xLock() — это операция без действия. xUnlock() понижает блокировку файла базы данных до SHARED или NONE. Если блокировка уже находится на уровне или ниже запрошенного состояния блокировки, то вызов xUnlock() — это операция без действия. Метод xCheckReservedLock() проверяет, удерживает ли какая-либо база данных подключения, либо в этом процессе, либо в другом процессе, блокировку RESERVED, PENDING или EXCLUSIVE для файла. Он возвращает true через параметр указателя вывода, если такая блокировка существует, и false в противном случае.

Метод xFileControl() — это общий интерфейс, который позволяет реализациям VFS напрямую управлять открытым файлом с использованием интерфейса sqlite3_file_control(). Второй аргумент "op" — целочисленный код операции. Третий аргумент — общий указатель, предназначенный для указания на структуру, которая может содержать аргументы или место для записи возвращаемых значений. Возможные применения xFileControl() — это функции для включения блокировок с тайм-аутами, изменения стратегии блокировки (например, для использования блокировок dot-файлов), запроса состояния блокировки или разрыва устаревших блокировок. Ядро SQLite зарезервировало все коды операций меньше 100 для собственного использования. Доступен список кодов операций меньше 100. Приложения, которые определяют пользовательский метод xFileControl, должны использовать коды операций больше 100, чтобы избежать конфликтов. Реализации VFS должны возвращать SQLITE_NOTFOUND для кодов операций управления файлами, которые они не распознают.

Метод xSectorSize() возвращает размер сектора устройства, на котором лежит файл. Размер сектора — это минимальный размер записи, который можно выполнить без нарушения других байтов в файле. Метод xDeviceCharacteristics() возвращает битовую маску, описывающую поведение основного устройства:

Свойство SQLITE_IOCAP_ATOMIC означает, что все записи любого размера являются атомарными. Значения SQLITE_IOCAP_ATOMICnnn означают, что записи блоков размером nnn байт и выровненных по адресу, который является целым кратным nnn, являются атомарными. Значение SQLITE_IOCAP_SAFE_APPEND означает, что при добавлении данных в файл данные добавляются сначала, а затем расширяется размер файла, а не наоборот. Свойство SQLITE_IOCAP_SEQUENTIAL означает, что информация записывается на диск в том же порядке, что и вызовы xWrite().

Если xRead() возвращает SQLITE_IOERR_SHORT_READ, он также должен заполнить незаполненные части буфера нулями. VFS, который не заполняет нулями короткие чтения, может казаться работающим. Однако отсутствие заполнения коротких чтений в конечном итоге приведёт к повреждению базы данных.

См. также списки Объектов, Констант и Функций.

SQLite is in the Public Domain.
https://sqlite.org/c3ref/io_methods.html