SQLite

** The first argument to this function is the name of the VFS to use (or
** a NULL to signify the default VFS) if the URI does not contain a "vfs=xxx"
** query parameter. The second argument contains the URI (or non-URI filename)
** itself. When this function is called the *pFlags variable should contain
** the default flags to open the database handle with. The value stored in
** *pFlags may be updated before returning if the URI filename contains 
** "cache=xxx" or "mode=xxx" query parameters.
**
** The third argument, pBtflags, points to an integer containing the flags
** that will be passed as the 5th argument to sqlite3BtreeOpen (BTREE_XXX
** flags). This value will be edited if the URI filename contains a
** "readonly_shm=1" or "readonly_shm=0" query parameter.
**
** If successful, SQLITE_OK is returned. In this case *ppVfs is set to point to
** the VFS that should be used to open the database file. *pzFile is set to
** point to a buffer containing the name of the file to open. It is the 
** responsibility of the caller to eventually call sqlite3_free() to release
** this buffer.
**

** when the database connection has [PRAGMA synchronous] set to OFF.)^
** Some specialized VFSes need this signal in order to operate correctly
** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most 
** VFSes do not need this signal and should silently ignore this opcode.
** Applications should not call [sqlite3_file_control()] with this
** opcode as doing so may disrupt the operation of the specialized VFSes
** that do require it.  
**
** The [SQLITE_FCNTL_READONLY_SHM] may be generated internally by SQLite if
** the "readonly_shm=1" URI option is specified when the database is opened.
** The fourth argument passed to the VFS xFileControl methods is a pointer
** to a variable of type "int" containing the value 1 or 0. If the variable
** contains the value 1, then this indicates to the VFS that a read-only
** mapping of the shared-memory region is acceptable. If it is set to 0, then
** this indicates that a read-write mapping is required (as normal). If
** a read-only mapping is returned, then the VFS may also return read-only
** mappings for any subsequent requests via the same file-descriptor -
** regardless of the value most recently configured using
** SQLITE_FCNTL_READONLY_SHM.
**
** In practice, if "readonly_shm=1" is specified and the first attempt to
** map a shared-memory region fails, then this file-control is invoked with
** the argument variable set to 1 and a second attempt to map the shared-memory
** region is made. If this mapping succeeds, then the connection continues
** with the read-only mapping. Otherwise, if it fails, SQLITE_CANTOPEN is
** returned to the caller. Whether or not the second (read-only) mapping
** attempt succeeds, the file-control is invoked again with the argument
** variable set to 0.
*/
#define SQLITE_FCNTL_LOCKSTATE        1
#define SQLITE_GET_LOCKPROXYFILE      2
#define SQLITE_SET_LOCKPROXYFILE      3
#define SQLITE_LAST_ERRNO             4
#define SQLITE_FCNTL_SIZE_HINT        5
#define SQLITE_FCNTL_CHUNK_SIZE       6

** to open. ^If the path begins with a '/' character, then it is interpreted as
** an absolute path. ^If it does not begin with a '/', it is interpreted as a 
** relative path. ^On windows, the first component of an absolute path 
** is a drive specification (e.g. "C:").
**
** The query component of a URI may contain parameters that are interpreted
** either by SQLite itself, or by a [sqlite3_vfs | custom VFS implementation].
** SQLite interprets the following four query parameters:
**
** <ul>
**   <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
**     a VFS object that provides the operating system interface that should
**     be used to access the database file on disk. ^If this option is set to
**     an empty string the default VFS object is used. ^Specifying an unknown
**     VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is

**     "private". ^Setting it to "shared" is equivalent to setting the
**     SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
**     sqlite3_open_v2(). ^Setting the cache parameter to "private" is 
**     equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
**     ^If sqlite3_open_v2() is used and the "cache" parameter is present in
**     a URI filename, its value overrides any behaviour requested by setting
**     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
**
**   <li> <b>readonly_shm</b>: ^The readonly_shm parameter may be set to 
**     either "1" or "0". Setting it to "1" indicates that if the database
**     is in WAL mode and read-write access to the associated shared 
**     memory region cannot be obtained, then an attempt should be made to open
**     the shared-memory in read-only mode instead. If there exist one or
**     more other database clients that have read-write connections to the
**     database shared-memory, then a read-only shared-memory connection works 
**     fine. However, if there exist no clients with read-write connections 
**     to the shared-memory and the most recent such crashed or was interrupted
**     by a power failure, then it is possible for a database client using a
**     read-only connection to return incorrect data, incorrectly report 
**     database corruption, or return an SQLITE_READONLY error. Or if the
**     most recent read-write connection shut down cleanly, it may not be
**     possible to open the shared-memory in read-only mode at all, and SQLite
**     will return SQLITE_CANTOPEN.
** </ul>
**
** ^Specifying an unknown parameter in the query component of a URI is not an
** error.
**
** URI filename examples:
**

#define walFrameOffset(iFrame, szPage) (                               \
  WAL_HDRSIZE + ((iFrame)-1)*(i64)((szPage)+WAL_FRAME_HDRSIZE)         \
)

/*
** An open write-ahead log file is represented by an instance of the
** following object.
**
** The readOnlyShm variable is normally set to 0. If it is set to 1, then
** the connection to shared-memory is read-only. This means it cannot
** be written at all (even when read-locking the database). If it is set
** to 2, then the shared-memory region is not yet open, but a read-only
** connection is acceptable. In this case when the shared-memory is opened
** (see function walIndexPage()), readOnlyShm is set to either 0 or 1 as
** appropriate.
*/
struct Wal {
  sqlite3_vfs *pVfs;         /* The VFS used to create pDbFd */
  sqlite3_file *pDbFd;       /* File handle for the database file */
  sqlite3_file *pWalFd;      /* File handle for WAL file */
  u32 iCallback;             /* Value to pass to log callback (or 0) */
  int nWiData;               /* Size of array apWiData */