From 63847496f14c813a5d80efd5b7de0f1294ffe1e3 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 13 Apr 2024 16:07:11 +0200 Subject: Adding upstream version 3.45.1. Signed-off-by: Daniel Baumann --- www/c3ref/io_methods.html | 252 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 www/c3ref/io_methods.html (limited to 'www/c3ref/io_methods.html') diff --git a/www/c3ref/io_methods.html b/www/c3ref/io_methods.html new file mode 100644 index 0000000..67ddcd0 --- /dev/null +++ b/www/c3ref/io_methods.html @@ -0,0 +1,252 @@ + + + + + +OS Interface File Virtual Methods Object + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ + +
+

SQLite C Interface

 +

OS Interface File Virtual Methods Object

+
+
+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 */
+};
+
+

+Every file opened by the sqlite3_vfs.xOpen method populates an +sqlite3_file object (or, more commonly, a subclass of the +sqlite3_file object) with a pointer to an instance of this object. +This object defines the methods used to perform various operations +against the open file represented by the sqlite3_file object.

+ +

If the sqlite3_vfs.xOpen method sets the sqlite3_file.pMethods element +to a non-NULL pointer, then the sqlite3_io_methods.xClose method +may be invoked even if the sqlite3_vfs.xOpen reported that it failed. The +only way to prevent a call to xClose following a failed sqlite3_vfs.xOpen +is for the sqlite3_vfs.xOpen to set the sqlite3_file.pMethods element +to NULL.

+ +

The flags argument to xSync may be one of SQLITE_SYNC_NORMAL or +SQLITE_SYNC_FULL. The first choice is the normal fsync(). +The second choice is a Mac OS X style fullsync. The SQLITE_SYNC_DATAONLY +flag may be ORed in to indicate that only the data of the file +and not its inode needs to be synced.

+ +

The integer values to xLock() and xUnlock() are one of +

+xLock() upgrades the database file lock. In other words, xLock() moves the +database file lock in the direction NONE toward EXCLUSIVE. The argument to +xLock() is always on of SHARED, RESERVED, PENDING, or EXCLUSIVE, never +SQLITE_LOCK_NONE. If the database file lock is already at or above the +requested lock, then the call to xLock() is a no-op. +xUnlock() downgrades the database file lock to either SHARED or NONE. +to xUnlock() is a no-op. +The xCheckReservedLock() method checks whether any database connection, +either in this process or in some other process, is holding a RESERVED, +PENDING, or EXCLUSIVE lock on the file. It returns true +if such a lock exists and false otherwise.

+ +

The xFileControl() method is a generic interface that allows custom +VFS implementations to directly control an open file using the +sqlite3_file_control() interface. The second "op" argument is an +integer opcode. The third argument is a generic pointer intended to +point to a structure that may contain arguments or space in which to +write return values. Potential uses for xFileControl() might be +functions to enable blocking locks with timeouts, to change the +locking strategy (for example to use dot-file locks), to inquire +about the status of a lock, or to break stale locks. The SQLite +core reserves all opcodes less than 100 for its own use. +A list of opcodes less than 100 is available. +Applications that define a custom xFileControl method should use opcodes +greater than 100 to avoid conflicts. VFS implementations should +return SQLITE_NOTFOUND for file control opcodes that they do not +recognize.

+ +

The xSectorSize() method returns the sector size of the +device that underlies the file. The sector size is the +minimum write that can be performed without disturbing +other bytes in the file. The xDeviceCharacteristics() +method returns a bit vector describing behaviors of the +underlying device:

+ +

+ +

The SQLITE_IOCAP_ATOMIC property means that all writes of +any size are atomic. The SQLITE_IOCAP_ATOMICnnn values +mean that writes of blocks that are nnn bytes in size and +are aligned to an address which is an integer multiple of +nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means +that when data is appended to a file, the data is appended +first then the size of the file is extended, never the other +way around. The SQLITE_IOCAP_SEQUENTIAL property means that +information is written to disk in the same order as calls +to xWrite().

+ +

If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill +in the unread portions of the buffer with zeros. A VFS that +fails to zero-fill short reads might seem to work. However, +failure to zero-fill short reads will eventually lead to +database corruption. +

See also lists of + Objects, + Constants, and + Functions.

+ -- cgit v1.2.3