Стандартные коды операций управления файлами

#define SQLITE_FCNTL_LOCKSTATE               1
#define SQLITE_FCNTL_GET_LOCKPROXYFILE       2
#define SQLITE_FCNTL_SET_LOCKPROXYFILE       3
#define SQLITE_FCNTL_LAST_ERRNO              4
#define SQLITE_FCNTL_SIZE_HINT               5
#define SQLITE_FCNTL_CHUNK_SIZE              6
#define SQLITE_FCNTL_FILE_POINTER            7
#define SQLITE_FCNTL_SYNC_OMITTED            8
#define SQLITE_FCNTL_WIN32_AV_RETRY          9
#define SQLITE_FCNTL_PERSIST_WAL            10
#define SQLITE_FCNTL_OVERWRITE              11
#define SQLITE_FCNTL_VFSNAME                12
#define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13
#define SQLITE_FCNTL_PRAGMA                 14
#define SQLITE_FCNTL_BUSYHANDLER            15
#define SQLITE_FCNTL_TEMPFILENAME           16
#define SQLITE_FCNTL_MMAP_SIZE              18
#define SQLITE_FCNTL_TRACE                  19
#define SQLITE_FCNTL_HAS_MOVED              20
#define SQLITE_FCNTL_SYNC                   21
#define SQLITE_FCNTL_COMMIT_PHASETWO        22
#define SQLITE_FCNTL_WIN32_SET_HANDLE       23
#define SQLITE_FCNTL_WAL_BLOCK              24
#define SQLITE_FCNTL_ZIPVFS                 25
#define SQLITE_FCNTL_RBU                    26
#define SQLITE_FCNTL_VFS_POINTER            27
#define SQLITE_FCNTL_JOURNAL_POINTER        28
#define SQLITE_FCNTL_WIN32_GET_HANDLE       29
#define SQLITE_FCNTL_PDB                    30
#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE     31
#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE    32
#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE  33
#define SQLITE_FCNTL_LOCK_TIMEOUT           34
#define SQLITE_FCNTL_DATA_VERSION           35
#define SQLITE_FCNTL_SIZE_LIMIT             36
#define SQLITE_FCNTL_CKPT_DONE              37
#define SQLITE_FCNTL_RESERVE_BYTES          38
#define SQLITE_FCNTL_CKPT_START             39
#define SQLITE_FCNTL_EXTERNAL_READER        40
#define SQLITE_FCNTL_CKSM_FILE              41
#define SQLITE_FCNTL_RESET_CACHE            42
#define SQLITE_FCNTL_NULL_IO                43
#define SQLITE_FCNTL_BLOCK_ON_CONNECT       44
#define SQLITE_FCNTL_FILESTAT               45

Эти целочисленные константы являются кодами операций для метода xFileControl объекта sqlite3_io_methods и интерфейса sqlite3_file_control().

Код операции SQLITE_FCNTL_LOCKSTATE используется для отладки. Этот код операции заставляет метод xFileControl записать текущее состояние блокировки (одно из значений SQLITE_LOCK_NONE, SQLITE_LOCK_SHARED, SQLITE_LOCK_RESERVED, SQLITE_LOCK_PENDING или SQLITE_LOCK_EXCLUSIVE) в целое число, на которое указывает аргумент pArg. Эта возможность доступна только в том случае, если SQLite скомпилирована с параметром SQLITE_DEBUG.
Код операции SQLITE_FCNTL_SIZE_HINT используется SQLite, чтобы сообщить слою VFS, какого размера может достичь файл базы данных в ходе текущей транзакции. Эта подсказка не обязательно точна, но часто близка к действительности. Нижележащая VFS может решить заранее выделить место для файла базы данных на основании этой подсказки, чтобы ускорить запись в файл базы данных.
Код операции SQLITE_FCNTL_SIZE_LIMIT используется VFS в памяти, реализующей sqlite3_deserialize(), для установки верхнего предела размера базы данных в памяти. Аргумент — указатель на sqlite3_int64. Если целое число, на которое он указывает, отрицательное, в него записывается текущий предел. В противном случае предел устанавливается равным большему из значения указанного целого числа и текущего размера базы данных. В указанное целое число записывается новый предел.
Код операции SQLITE_FCNTL_CHUNK_SIZE используется для запроса к VFS расширять и усекать файл базы данных блоками размера, заданного пользователем. Четвертый аргумент sqlite3_file_control() должен указывать на целое число (типа int), содержащее новый размер блока для указанной базы данных. Выделение места для файла базы данных большими блоками (например, по 1 МБ за раз) может уменьшить фрагментацию файловой системы и повысить производительность некоторых систем.
Код операции SQLITE_FCNTL_FILE_POINTER используется для получения указателя на объект sqlite3_file, связанный с определенным соединением с базой данных. См. также SQLITE_FCNTL_JOURNAL_POINTER.
Код операции SQLITE_FCNTL_JOURNAL_POINTER используется для получения указателя на объект sqlite3_file, связанный с файлом журнала (либо с журналом отката, либо с журналом предварительной записи) для определенного соединения с базой данных. См. также SQLITE_FCNTL_FILE_POINTER.
Операция управления файлом SQLITE_FCNTL_SYNC_OMITTED больше не используется.
Код операции SQLITE_FCNTL_SYNC генерируется SQLite внутри и отправляется в VFS непосредственно перед вызовом метода xSync для дескриптора файла базы данных. Если метод xSync не вызывается из-за того, что пользователь настроил SQLite с помощью PRAGMA synchronous=OFF, этот код операции вызывается вместо метода xSync. В большинстве случаев аргумент-указатель, передаваемый вместе с этой операцией управления файлом, равен NULL. Однако если синхронизация файла базы данных выполняется в рамках фиксации нескольких баз данных, аргумент указывает на строку с нулевым завершающим символом, содержащую имя файла супержурнала транзакции. VFS, которым этот сигнал не нужен, должны молча игнорировать данный код операции. Приложениям не следует вызывать sqlite3_file_control() с этим кодом операции, поскольку это может нарушить работу специализированных VFS, которым он необходим.
Код операции SQLITE_FCNTL_COMMIT_PHASETWO генерируется SQLite внутри и отправляется в VFS после фиксации транзакции, но до снятия блокировки с базы данных. VFS, которым этот сигнал не нужен, должны молча игнорировать данный код операции. Приложениям не следует вызывать sqlite3_file_control() с этим кодом операции, поскольку это может нарушить работу специализированных VFS, которым он необходим.
Код операции SQLITE_FCNTL_WIN32_AV_RETRY используется для настройки количества и интервалов автоматических повторных попыток при некоторых операциях дискового ввода-вывода в Windows VFS, чтобы обеспечить надежность при наличии антивирусных программ. По умолчанию Windows VFS повторяет операции чтения, записи и удаления файлов до 10 раз, выдерживая перед первой повторной попыткой задержку 25 миллисекунд и увеличивая ее еще на 25 миллисекунд с каждой следующей попыткой. Этот код операции позволяет изменить оба значения (10 повторных попыток и задержку 25 миллисекунд). Значения изменяются для всех соединений с базами данных в рамках одного процесса. Аргумент — указатель на массив из двух целых чисел: первое число задает новое количество повторных попыток, а второе — задержку. Если любое из чисел отрицательное, соответствующая настройка не изменяется, а вместо этого в элемент массива записывается ее прежнее значение, что позволяет запросить текущие параметры повторных попыток. Параметр zDbName игнорируется.
Код операции SQLITE_FCNTL_PERSIST_WAL используется для установки или запроса режима постоянного журнала предварительной записи. По умолчанию вспомогательный журнал предварительной записи (файл WAL) и файлы разделяемой памяти, используемые для управления транзакциями, автоматически удаляются при закрытии последнего соединения с базой данных. В постоянном режиме WAL эти файлы сохраняются после закрытия. Сохранение файлов полезно, когда другие процессы, не имеющие права записи в каталог с файлом базы данных, хотят читать этот файл, поскольку для чтения базы данных должны существовать файлы WAL и разделяемой памяти. Четвертый параметр sqlite3_file_control() для этого кода операции должен быть указателем на целое число. Значение 0 отключает постоянный режим WAL, а значение 1 включает его. Если значение равно -1, оно заменяется текущим значением настройки сохранения WAL.
Код операции SQLITE_FCNTL_POWERSAFE_OVERWRITE используется для установки или запроса постоянной настройки «powersafe-overwrite» или «PSOW». Настройка PSOW определяет бит SQLITE_IOCAP_POWERSAFE_OVERWRITE методов xDeviceCharacteristics. Четвертый параметр sqlite3_file_control() для этого кода операции должен быть указателем на целое число. Значение 0 отключает режим нулевого повреждения, а значение 1 включает его. Если значение равно -1, оно заменяется текущим значением настройки режима нулевого повреждения.
Код операции SQLITE_FCNTL_OVERWRITE вызывается SQLite после открытия транзакции записи, чтобы указать, что текущая транзакция перезапишет весь файл базы данных, если по какой-либо причине не будет отменена. Эта операция используется при выполнении VACUUM.
Код операции SQLITE_FCNTL_VFSNAME позволяет получить имена всех VFS в стеке VFS. Имена всех прослоек VFS и конечной нижнеуровневой VFS записываются в память, выделенную с помощью sqlite3_malloc(), а результат сохраняется в переменной char*, на которую указывает четвертый параметр sqlite3_file_control(). Вызывающая сторона отвечает за освобождение памяти после использования. Как и для всех операций управления файлами, нет гарантии, что эта операция что-либо выполнит. Вызывающей стороне следует инициализировать переменную char* указателем NULL на случай, если эта операция управления файлом не реализована. Эта операция управления файлом предназначена только для диагностики.
Код операции SQLITE_FCNTL_VFS_POINTER находит указатель на используемую в данный момент верхнеуровневую VFS. Аргумент X в sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) должен иметь тип «sqlite3_vfs **». Этот код операции присваивает *X указатель на верхнеуровневую VFS. Если в стеке несколько прослоек VFS, этот код операции находит только самую верхнюю прослойку.
При разборе оператора PRAGMA открытый объект sqlite3_file, соответствующий файлу базы данных, к которому относится оператор pragma, получает операцию управления файлом SQLITE_FCNTL_PRAGMA. Аргумент этой операции — массив указателей на строки (char**), в котором второй элемент содержит имя pragma, а третий — аргумент pragma или NULL, если у pragma нет аргумента. Обработчик операции управления файлом SQLITE_FCNTL_PRAGMA может при необходимости заставить первый элемент аргумента char** указывать на строку, полученную с помощью sqlite3_mprintf() или эквивалентного средства; эта строка станет результатом pragma или сообщением об ошибке, если pragma завершится неудачно. Если операция управления файлом SQLITE_FCNTL_PRAGMA возвращает SQLITE_NOTFOUND, обычная обработка PRAGMA продолжается. Если операция управления файлом SQLITE_FCNTL_PRAGMA возвращает SQLITE_OK, анализатор предполагает, что VFS обработала PRAGMA самостоятельно, и генерирует пустой подготовленный оператор, если строка результата равна NULL, либо оператор, возвращающий копию строки результата, если строка не равна NULL. Если операция управления файлом SQLITE_FCNTL_PRAGMA возвращает любой код результата, кроме SQLITE_OK или SQLITE_NOTFOUND, это означает, что при обработке PRAGMA VFS столкнулась с ошибкой и компиляция PRAGMA завершается с ошибкой. Операция управления файлом SQLITE_FCNTL_PRAGMA выполняется в начале анализа оператора pragma, поэтому она может переопределять встроенные операторы PRAGMA.
Операция управления файлом SQLITE_FCNTL_BUSYHANDLER может быть вызвана SQLite для дескриптора файла базы данных вскоре после его открытия, чтобы предоставить пользовательской VFS доступ к функции обратного вызова обработчика занятости соединения. Аргумент имеет тип (void**) — массив из двух значений (void *). Первое значение (void *) фактически указывает на функцию типа (int (*)(void *)). Чтобы вызвать обработчик занятости соединения, эту функцию следует вызвать, передав ей в качестве единственного аргумента второе значение (void *) из массива. Если функция возвращает ненулевое значение, операцию следует повторить. Если она возвращает ноль, пользовательская VFS должна прервать текущую операцию.
Приложения могут вызвать операцию управления файлом SQLITE_FCNTL_TEMPFILENAME, чтобы SQLite создала временное имя файла, используя тот же алгоритм, что и для генерации имен временных файлов таблиц TEMP и других внутренних целей. Аргумент должен иметь тип char**; в него будет записано имя файла в памяти, выделенной с помощью sqlite3_malloc(). Во избежание утечки памяти вызывающей стороне следует вызвать sqlite3_free() для полученного результата.
Операция управления файлом SQLITE_FCNTL_MMAP_SIZE используется для запроса или установки максимального количества байтов, используемых для ввода-вывода с отображением в память. Аргумент — указатель на значение типа sqlite3_int64, задающее рекомендуемый максимум числа байтов файла, отображаемых в память. Указатель перезаписывается старым значением. Предел не изменяется, если исходное значение отрицательное, поэтому текущий предел можно запросить, передав указатель на отрицательное число. Эта операция управления файлом используется внутри SQLite для реализации PRAGMA mmap_size.
Операция управления файлом SQLITE_FCNTL_TRACE предоставляет VFS справочную информацию о действиях вышележащих уровней стека SQLite. Эта операция управления файлом используется некоторыми прослойками трассировки активности VFS. Аргумент — строка с нулевым завершающим символом. Вышележащие уровни стека SQLite могут генерировать эту операцию управления файлом, если включен параметр компиляции SQLITE_USE_FCNTL_TRACE.
Операция управления файлом SQLITE_FCNTL_HAS_MOVED рассматривает свой аргумент как указатель на целое число и записывает в него логическое значение в зависимости от того, был ли файл переименован, перемещен или удален с момента первого открытия.
Код операции SQLITE_FCNTL_WIN32_GET_HANDLE можно использовать для получения базового системного дескриптора файла, связанного с дескриптором файла. Эта операция управления файлом рассматривает свой аргумент как указатель на системный дескриптор файла и записывает туда полученное значение.
Код операции SQLITE_FCNTL_WIN32_SET_HANDLE используется для отладки. Этот код операции заставляет метод xFileControl поменять местами дескриптор файла с тем, на который указывает аргумент pArg. Эта возможность используется при тестировании и должна поддерживаться только при определенном SQLITE_TEST.
Код операции SQLITE_FCNTL_NULL_IO устанавливает низкоуровневый файловый дескриптор или описатель объекта sqlite3_file таким образом, что он больше не будет читать файл базы данных или записывать в него.
Код операции SQLITE_FCNTL_WAL_BLOCK сигнализирует слою VFS, что может быть полезно заблокировать выполнение при следующей блокировке WAL, если она недоступна немедленно. Подсистема WAL отправляет этот сигнал в редких случаях, чтобы устранить проблему инверсии приоритетов. Приложениям не следует использовать эту операцию управления файлом.
Код операции SQLITE_FCNTL_ZIPVFS реализован только в zipvfs. Все остальные VFS должны возвращать SQLITE_NOTFOUND для этого кода операции.
Код операции SQLITE_FCNTL_RBU реализован только в специальной VFS, используемой расширением RBU. Все остальные VFS должны возвращать SQLITE_NOTFOUND для этого кода операции.
Если код операции SQLITE_FCNTL_BEGIN_ATOMIC_WRITE возвращает SQLITE_OK, файловый дескриптор переводится в «режим пакетной записи», то есть все последующие операции записи откладываются и выполняются атомарно при следующем вызове SQLITE_FCNTL_COMMIT_ATOMIC_WRITE. Системы, не поддерживающие атомарную пакетную запись, возвращают SQLITE_NOTFOUND. После успешного вызова SQLITE_FCNTL_BEGIN_ATOMIC_WRITE и до завершающего вызова SQLITE_FCNTL_COMMIT_ATOMIC_WRITE или SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE SQLite не будет вызывать интерфейс VFS для того же файлового дескриптора sqlite3_file, кроме вызовов метода xWrite и метода xFileControl с кодом SQLITE_FCNTL_SIZE_HINT.
Код операции SQLITE_FCNTL_COMMIT_ATOMIC_WRITE заставляет атомарно выполнить все операции записи, сделанные после предыдущего успешного вызова SQLITE_FCNTL_BEGIN_ATOMIC_WRITE. Эта операция управления файлом возвращает SQLITE_OK только в том случае, если все операции записи выполнены успешно и зафиксированы в постоянном хранилище. Независимо от успешности выполнения эта операция управления файлом выводит файловый дескриптор из режима пакетной записи, так что все последующие операции записи выполняются независимо. SQLite никогда не вызывает SQLITE_FCNTL_COMMIT_ATOMIC_WRITE без предшествующего успешного вызова SQLITE_FCNTL_BEGIN_ATOMIC_WRITE.
Код операции SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE отменяет все операции записи, сделанные после предыдущего успешного вызова SQLITE_FCNTL_BEGIN_ATOMIC_WRITE. Эта операция управления файлом выводит файловый дескриптор из режима пакетной записи, так что все последующие операции записи выполняются независимо. SQLite никогда не вызывает SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE без предшествующего успешного вызова SQLITE_FCNTL_BEGIN_ATOMIC_WRITE.
Код операции SQLITE_FCNTL_LOCK_TIMEOUT используется для настройки VFS на ожидание до M миллисекунд перед возвратом ошибки при попытке получить файловую блокировку с помощью методов xLock или xShmLock VFS. Параметр — указатель на 32-разрядное целое число со знаком, содержащее значение, которое следует присвоить M. Перед возвратом в это 32-разрядное целое число со знаком записывается предыдущее значение M.
Код операции SQLITE_FCNTL_BLOCK_ON_CONNECT используется для настройки VFS на ожидание при получении блокировки SHARED для подключения к базе данных в режиме WAL. Это используется для реализации функциональности, связанной с SQLITE_SETLK_BLOCK_ON_CONNECT.
Код операции SQLITE_FCNTL_DATA_VERSION используется для обнаружения изменений файла базы данных. Аргумент — указатель на 32-разрядное беззнаковое целое число. В указатель записывается «версия данных» для pager. «Версия данных» изменяется при любом изменении соответствующего файла базы данных — как при выполнении SQL-операторов в том же соединении с базой данных, так и при фиксации транзакций отдельными соединениями, возможно в других процессах. Интерфейс sqlite3_total_changes() позволяет определить, изменились ли какие-либо базы данных в соединении, но он учитывает изменения как в TEMP, так и в MAIN и не предоставляет способа обнаружить изменения только в MAIN. Кроме того, интерфейс sqlite3_total_changes() учитывает только внутренние изменения и не учитывает изменения, внесенные другими соединениями с базой данных. Команда PRAGMA data_version позволяет обнаруживать изменения одной подключенной базы данных, произошедшие из-за других соединений с базой данных, но не учитывает изменения, внесенные самим соединением, в котором она вызвана. Эта операция управления файлом — единственный способ обнаружить как внутренние, так и внешние изменения, относящиеся к определенной подключенной базе данных.
Код операции SQLITE_FCNTL_CKPT_START вызывается во время контрольной точки в режиме WAL перед тем, как клиент начнет копировать страницы из файла WAL в файл базы данных.
Код операции SQLITE_FCNTL_CKPT_DONE вызывается во время контрольной точки в режиме WAL после того, как клиент завершил копирование страниц из файла WAL в файл базы данных, но до обновления файла *-shm, фиксирующего факт создания контрольной точки для этих страниц.
ЭКСПЕРИМЕНТАЛЬНЫЙ код операции SQLITE_FCNTL_EXTERNAL_READER используется для определения наличия клиента базы данных в другом процессе с открытой транзакцией в режиме WAL для этой базы данных. Он доступен только в Unix. Аргумент (void*), передаваемый вместе с этой операцией управления файлом, должен быть указателем на значение типа (int). Целому числу присваивается значение 1, если база данных работает в режиме WAL и существует хотя бы один клиент в другом процессе, у которого в данный момент открыта SQL-транзакция для этой базы данных. Ему присваивается значение 0, если база данных не работает в режиме WAL или если в других процессах нет такого соединения. Этот код операции позволяет обнаруживать транзакции, открытые клиентами в других процессах, но не клиентами в текущем процессе.
Код операции SQLITE_FCNTL_CKSM_FILE предназначен только для внутреннего использования прослойкой VFS контрольных сумм.
Если в данный момент для базы данных нет открытой транзакции и база данных не является временной, операция управления файлом SQLITE_FCNTL_RESET_CACHE очищает содержимое кэша страниц в памяти. Если транзакция открыта или база данных является временной, этот код операции ничего не делает и не считается ошибкой.
Код операции SQLITE_FCNTL_FILESTAT возвращает низкоуровневую диагностическую информацию об объектах sqlite3_file, используемых для доступа к файлам базы данных и журналов указанной схемы. Четвертый параметр sqlite3_file_control() должен быть инициализированным указателем sqlite3_str. К sqlite3_str добавляется текст JSON с описанием различных аспектов объекта sqlite3_file. Код операции SQLITE_FCNTL_FILESTAT обычно ничего не делает, если только он не включен параметрами компиляции.

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

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