Объект интерфейса ОС

typedef struct sqlite3_vfs sqlite3_vfs;
typedef void (*sqlite3_syscall_ptr)(void);
struct sqlite3_vfs {
  int iVersion;            /* Structure version number (currently 3) */
  int szOsFile;            /* Size of subclassed sqlite3_file */
  int mxPathname;          /* Maximum file pathname length */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Pointer to application-specific data */
  int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*,
               int flags, int *pOutFlags);
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
  /*
  ** The methods above are in version 1 of the sqlite_vfs object
  ** definition.  Those that follow are added in version 2 or later
  */
  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  /*
  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  ** Those below are for version 3 and greater.
  */
  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
  /*
  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  ** New fields may be appended in future versions.  The iVersion
  ** value will increment whenever this happens.
  */
};

Экземпляр объекта sqlite3_vfs определяет интерфейс между ядром SQLite и базовой операционной системой. «vfs» в названии объекта обозначает «виртуальную файловую систему». Дополнительную информацию см. в документации VFS.

Интерфейс VFS иногда расширяется добавлением новых методов в конец. Каждый раз, когда происходит такое расширение, поле iVersion увеличивается. Значение iVersion начиналось с 1 в SQLite версии 3.5.0 04.09.2007, затем увеличилось до 2 с SQLite версией 3.7.0 21.07.2010, и затем до 3 с SQLite версией 3.7.6 12.04.2011. К объекту sqlite3_vfs могут быть добавлены дополнительные поля, а значение iVersion может снова увеличиться в будущих версиях SQLite. Обратите внимание, что из-за упущения структура объекта sqlite3_vfs изменилась при переходе от SQLite версии 3.5.9 к версии 3.6.0 16.07.2008, и поле iVersion не увеличилось.

Поле szOsFile — это размер подклассированной структуры sqlite3_file, используемой этой VFS. mxPathname — максимальная длина имени пути в этой VFS.

Зарегистрированные объекты sqlite3_vfs хранятся в связанном списке, образованном указателем pNext. Интерфейсы sqlite3_vfs_register() и sqlite3_vfs_unregister() управляют этим списком в потокобезопасном режиме. Интерфейс sqlite3_vfs_find() ищет в списке. Ни код приложения, ни реализация VFS не должны использовать указатель pNext.

Поле pNext — единственное поле в структуре sqlite3_vfs, которое SQLite когда-либо будет изменять. SQLite будет обращаться к этому полю или изменять его только при удержании определенного статического мьютекса. Приложение никогда не должно изменять что-либо в объекте sqlite3_vfs после его регистрации.

Поле zName содержит имя модуля VFS. Имя должно быть уникальным для всех модулей VFS.

SQLite гарантирует, что параметр zFilename метода xOpen — это либо нулевой указатель, либо строка, полученная из xFullPathname() с добавлением необязательного суффикса. Если к параметру zFilename добавляется суффикс, он будет состоять из одного символа «-», за которым следует не более 11 буквенно-цифровых символов и/или символов «-». SQLite дополнительно гарантирует, что строка будет допустимой и неизменной до вызова xClose(). Из-за предыдущего предложения sqlite3_file может безопасно хранить указатель на имя файла, если ему нужно запомнить имя файла по какой-либо причине. Если параметр zFilename для xOpen — нулевой указатель, xOpen должен придумать собственное временное имя для файла. Всякий раз, когда параметр xFilename равен NULL, параметр flags также будет включать SQLITE_OPEN_DELETEONCLOSE.

Аргумент flags для xOpen() включает все биты, установленные в аргументе flags для sqlite3_open_v2(). Или, если используется sqlite3_open() или sqlite3_open16(), тогда flags включает по крайней мере SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE. Если xOpen() открывает файл только для чтения, он устанавливает *pOutFlags, чтобы включить SQLITE_OPEN_READONLY. Другие биты в *pOutFlags могут быть установлены.

SQLite также добавит один из следующих флагов к вызову xOpen(), в зависимости от открываемого объекта:

Реализация ввода-вывода файлов может использовать флаги типа объекта, чтобы изменить способ работы с файлами. Например, приложение, которое не заботится о восстановлении после сбоя или откате, может сделать открытие файла журнала бессмысленным действием. Записи в этот журнал также будут бессмысленными, а любая попытка чтения журнала вернёт SQLITE_IOERR. Или реализация может распознать, что файл базы данных будет выполнять чтение и запись сектора с выравниванием страниц в случайном порядке, и настроить свою систему ввода-вывода соответственно.

SQLite также может добавить один из следующих флагов к методу xOpen:

Флаг SQLITE_OPEN_DELETEONCLOSE означает, что файл должен быть удален при закрытии. Флаг SQLITE_OPEN_DELETEONCLOSE будет установлен для TEMP баз данных и их журналов, временных баз данных и поджурналов.

Флаг SQLITE_OPEN_EXCLUSIVE всегда используется в сочетании с флагом SQLITE_OPEN_CREATE, которые оба напрямую аналогичны флагам O_EXCL и O_CREAT API открывания POSIX. Флаг SQLITE_OPEN_EXCLUSIVE, в сочетании с SQLITE_OPEN_CREATE, используется для указания, что файл должен быть всегда создан, и что это ошибка, если он уже существует. Он не используется для указания, что файл должен быть открыт для эксклюзивного доступа.

SQLite выделяет не менее szOsFile байтов памяти для хранения структуры sqlite3_file, переданной в качестве третьего аргумента в xOpen. Метод xOpen не обязан выделять структуру; он должен только заполнить её. Обратите внимание, что метод xOpen должен установить sqlite3_file.pMethods либо на действительный объект sqlite3_io_methods, либо на NULL. xOpen должен сделать это даже в случае неудачи открытия. SQLite ожидает, что элемент sqlite3_file.pMethods будет действительным после возврата xOpen независимо от успеха или неудачи вызова xOpen.

Аргумент flags для xAccess() может быть SQLITE_ACCESS_EXISTS для проверки существования файла, или SQLITE_ACCESS_READWRITE для проверки возможности чтения и записи в файл, или SQLITE_ACCESS_READ для проверки возможности чтения файла. Флаг SQLITE_ACCESS_READ фактически никогда не используется и не реализован во встроенных VFS SQLite. Файл называется во втором аргументе и может быть каталогом. Метод xAccess возвращает SQLITE_OK при успехе или какой-либо ненулевой код ошибки, если есть ошибка ввода-вывода или если имя файла, заданное во втором аргументе, недопустимо. Если возвращается SQLITE_OK, то ненулевое или нулевое значение записывается в *pResOut, чтобы указать, доступен ли файл или нет.

SQLite всегда будет выделять не менее mxPathname+1 байта для выходного буфера xFullPathname. Точный размер выходного буфера также передаётся в качестве параметра в оба метода. Если выходной буфер недостаточно велик, следует вернуть SQLITE_CANTOPEN. Поскольку это обрабатывается как ошибка в SQLite, реализации vfs должны стремиться предотвратить это, установив mxPathname в достаточно большое значение.

Интерфейсы xRandomness(), xSleep(), xCurrentTime() и xCurrentTimeInt64() строго не являются частью файловой системы, но включены в структуру VFS для полноты. Функция xRandomness() пытается вернуть nBytes байтов качественного случайного числа в zOut. Значение возврата — фактическое количество полученных байтов случайности. Метод xSleep() заставляет вызывающую нить спать не менее заданного количества микросекунд. Метод xCurrentTime() возвращает число Джулиана для текущей даты и времени как значение с плавающей точкой. Метод xCurrentTimeInt64() возвращает, как целое число, число Джулиана, умноженное на 86400000 (количество миллисекунд в 24-часовом дне). SQLite будет использовать метод xCurrentTimeInt64() для получения текущей даты и времени, если этот метод доступен (если iVersion равен 2 или больше, и указатель функции не равен NULL), и вернется к xCurrentTime(), если xCurrentTimeInt64() недоступен.

Интерфейсы xSetSystemCall(), xGetSystemCall() и xNestSystemCall() не используются ядром SQLite. Эти необязательные интерфейсы предоставляются некоторыми VFS для облегчения тестирования кода VFS. Заменяя системные вызовы функциями под своим управлением, программа тестирования может моделировать сбои и условия ошибок, которые в противном случае были бы трудно или невозможно вызвать. Набор системных вызовов, которые могут быть переопределены, варьируется от одной VFS к другой и от одной версии той же VFS к другой. Приложения, использующие эти интерфейсы, должны быть готовы к тому, что любой или все эти интерфейсы будут NULL или что их поведение изменится с одной версии на другую. Приложения не должны пытаться получить доступ к какому-либо из этих методов, если iVersion VFS меньше 3.

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

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