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

#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

Эти константы целого числа это коды операции для метода 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), содержащий новый размер куска, чтобы использовать для назначенной базы данных. Распределение файлового пространства базы данных в больших кусках (например, 1MB за раз) может уменьшить фрагментацию файловой системы и улучшить работу относительно некоторых систем.

• SQLITE_FCNTL_FILE_POINTER используется, чтобы получить указатель на объект sqlite3_file, связанный с конкретным соединением с базой данных. См. также SQLITE_FCNTL_JOURNAL_POINTER.

• SQLITE_FCNTL_JOURNAL_POINTER используется, чтобы получить указатель на объект sqlite3_file, связанный с файлом журнала (журнал обратной перемотки или журнал с упреждающей записью) для конкретного соединения с базой данных. См. также SQLITE_FCNTL_FILE_POINTER.

• Больше не используется.

• SQLITE_FCNTL_SYNC произведен внутренне SQLite и немедленно послан в VFS, прежде чем метод xSync будет вызван на дескрипторе файла базы данных. Или, если метод xSync не вызван, потому что пользователь формировал SQLite с PRAGMA synchronous=OFF это вызвано вместо метода xSync. В большинстве случаев аргументом указателя, переданным с этим контролем файла, является NULL. Однако, если файл базы данных синхронизируется, поскольку часть мультибазы данных передает, аргумент указывает на nul-законченную последовательность, содержащую операционное имя файла супержурнала. VFS, которым не нужен этот сигнал, должны тихо проигнорировать этот код операции. Приложения не должны вызывать sqlite3_file_control() с этим кодом операции, поскольку выполнение этого может разрушить работу специализированных VFS, которые действительно требуют его.

• SQLITE_FCNTL_COMMIT_PHASETWO произведен внутренне SQLite и послан в VFS после того, как транзакция была немедленно передана, но прежде чем базу данных открывают. VFS, которым не нужен этот сигнал, должны тихо проигнорировать этот код операции. Приложения не должны вызывать sqlite3_file_control() с этим кодом операции, поскольку выполнение этого может разрушить работу специализированных VFS, которые действительно требуют его.

• SQLITE_FCNTL_WIN32_AV_RETRY используется, чтобы формировать автоматическое количество повторных попыток и интервалы для определенной дисковой операции I/O для windows VFS, чтобы обеспечить надежность в присутствии антивирусных программ. По умолчанию windows VFS повторит чтение, запись и удаление файла до 10 раз с задержкой 25 миллисекунд перед первой повторной попыткой и с задержкой, увеличивающейся еще на 25 миллисекунд с каждой последующей повторной попыткой. Этот код операции позволяет этим двум значениям (10 повторений и 25 миллисекунд задержки) быть пренастроенными. Значения изменяются для всех соединений с базой данных в рамках того же самого процесса. Аргумент это указатель на множество двух целых чисел, где первое целое число это новое количество повторных попыток, второе целое число задержка. Если любое целое число отрицательно, то настройки не изменяются, но вместо этого предшествующее значение написано в запись массива, позволив текущим параметрам настройки повторной попытки быть опрошенными. Параметр zDbName игнорируется.

• SQLITE_FCNTL_PERSIST_WAL используется, чтобы установить или запрость постоянное значение журнала с упреждающей записью. По умолчанию вспомогательный журнал с упреждающей записью (WAL-файл) и файлы общей памяти, используемые для управления транзакциями, автоматически удалены, когда последняя связь с базой данных закрывается. Урегулирование постоянного режима WAL заставляет те файлы сохраняться после закрытия. Упорство файлов полезно, когда другие процессы, которые не имеют права записи на каталог, содержащий файл базы данных, хотят прочитать файл базы данных, поскольку WAL и файлы общей памяти должны существовать для базы данных, чтобы быть читаемыми. Четвертый параметр sqlite3_file_control() для этого кода операции должен быть указателем на целое число. Это целое число 0, чтобы отключить постоянный режим WAL или 1, чтобы позволить постоянный режим WAL. Если целое число -1, то оно переписано текущим значением.

• 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 может использоваться, чтобы получить названия всех VFSes в стеке 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 размечено, контроль за файлом SQLITE_FCNTL_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, это означает, что VFS столкнулся с ошибкой, обращаясь к PRAGMA и компиляция 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 используется, чтобы запросить или определить максимальное число байтов, которое будет использоваться для I/O с отображенной памятью. Аргумент это указатель на значение типа sqlite3_int64, является консультативным максимальным количеством байтов в файле для карты распределения памяти. Указатель переписан старым значением. Предел не изменяется, если указано негативное значение, таким образом, текущий предел может быть запрошен, передав указатель на отрицательное число. Этот контроль файла используется внутренне, чтобы осуществить PRAGMA mmap_size.

• SQLITE_FCNTL_TRACE предоставляет консультативную информацию VFS о том, что делают более высокие слои стека SQLite. Этот контроль за файлом используется некоторыми поисковыми shims деятельности VFS. Аргумент это законченная нолем последовательность. Более высокие слои в стеке SQLite могут произвести экземпляры этого контроля за файлом, если включен выбор времени компиляции SQLITE_USE_FCNTL_TRACE.

• SQLITE_FCNTL_HAS_MOVED интерпретирует свой аргумент как указатель на целое число, и он пишет boolean в этот integer в зависимости от того, был ли файл переименован, перемещен или удален после его первого открытия.

• SQLITE_FCNTL_WIN32_GET_HANDLE может использоваться, чтобы получить основной родной дескриптор файла, связанный с дескриптором файла. Этот контроль за файлом интерпретирует свой аргумент как указатель на родной дескриптор файла и пишет получающееся значение.

• SQLITE_FCNTL_WIN32_SET_HANDLE используется для отладки. Этот код операции заставляет метод xFileControl обменивать дескриптор файла с тем, на который указывает аргумент pArg. Это используется во время тестирования и должно быть поддержано только когда SQLITE_TEST определяется.

• 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, то дескриптор файла помещается в "batch write mode", что означает, что все последующие операции записи будут отсрочены и сделаны атомарно в следующем 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_DATA_VERSION используется, чтобы обнаружить изменения файла базы данных. Аргумент это указатель на 32-битное целое без знака. "Версия данных" для страниц написана в указатель. "Версия данных" изменяется каждый раз, когда любое изменение происходит с соответствующим файлом базы данных через 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 только для использования внутренне checksum VFS shim.

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