Стандартные кодовые операции управления файлами
#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 используется для запроса расширения и усечения файла базы данных в блоках заданного пользователем размера. Четвертый аргумент функции 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 генерируется внутри 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 используется для настройки автоматических подсчетов повторов и интервалов для определенных операций ввода-вывода на диске для виртуальной файловой системы (VFS) Windows, чтобы обеспечить надежность при наличии антивирусных программ. По умолчанию VFS Windows будет повторять операции чтения, записи и удаления файлов до 10 раз, с задержкой в 25 миллисекунд перед первым повтором и с увеличением задержки на 25 миллисекунд с каждым последующим повтором. Эта операция позволяет настроить эти два значения (10 повторов и 25 миллисекунд задержки). Значения изменяются для всех подключений к базе данных в одном процессе. Аргумент является указателем на массив из двух целых чисел, где первое целое число — новое количество повторов, а второе целое число — задержка. Если любое целое число отрицательное, то настройка не изменяется, а вместо этого предыдущее значение этой настройки записывается в запись массива, что позволяет получить текущие настройки повторов. Параметр zDbName игнорируется.
- Код операции SQLITE_FCNTL_PERSIST_WAL используется для установки или запроса настройки сохранения журнала предварительной записи (WAL). По умолчанию вспомогательный журнал предварительной записи (файл WAL) и файлы общей памяти, используемые для управления транзакциями, автоматически удаляются, когда закрывается последнее подключение к базе данных. Установка режима сохранения WAL приводит к сохранению этих файлов после закрытия. Сохранение файлов полезно, когда другие процессы, которые не имеют права записи в каталог, содержащий файл базы данных, хотят прочитать файл базы данных, так как файлы WAL и общей памяти должны существовать для того, чтобы база данных была читаемой. Четвертый параметр для sqlite3_file_control() для этой операции должен указывать на указатель на целое число. Это целое число равно 0 для отключения режима сохранения WAL или 1 для включения режима сохранения WAL. Если целое число равно -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, управление файлом 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 доступ к обратной функции busy-обработчика соединения. Аргумент имеет тип (void**) — массив из двух (void *) значений. Первый (void *) фактически указывает на функцию типа (int (*)(void *)). Для вызова busy-обработчика соединения эту функцию следует вызвать со вторым (void *) в массиве в качестве единственного аргумента. Если она возвращает ненулевое значение, операция должна быть повторена. Если она возвращает ноль, настраиваемый VFS должен отказаться от текущей операции.
- Приложения могут вызвать управление файлом SQLITE_FCNTL_TEMPFILENAME, чтобы SQLite сгенерировал временное имя файла, используя тот же алгоритм, что и для генерации временных имен файлов для TEMP-таблиц и других внутренних целей. Аргументом должен быть char**, который будет заполнен именем файла, записанным в память, полученную из sqlite3_malloc(). Вызывающий код должен вызвать sqlite3_free() для результата, чтобы избежать утечки памяти.
- Управление файлом SQLITE_FCNTL_MMAP_SIZE используется для запроса или установки максимального количества байтов, которые будут использоваться для отображения памяти. Аргументом является указатель на значение типа sqlite3_int64, которое является рекомендуемым максимальным количеством байтов в файле для отображения памяти. Указатель перезаписывается старым значением. Предел не меняется, если первоначально указанное значение отрицательное, и таким образом текущий предел можно запросить, передав указатель на отрицательное число. Это управление файлом используется внутри для реализации 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_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_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 используется только внутри платформы VFS проверки контрольной суммы.
- Если в данный момент нет открытой транзакции в базе данных и база данных не является временной, то управление файлом SQLITE_FCNTL_RESET_CACHE очищает содержимое кэш-памяти страниц в оперативной памяти. Если открыта транзакция или база данных — это временная база данных, этот код является пустой операцией, а не ошибкой.
См. также списки объектов, констант и функций.
SQLite is in the Public Domain.
https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html
