Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

SQLITE3_URI_PARAMETER(3)   Library Functions Manual   SQLITE3_URI_PARAMETER(3)

NAME
     sqlite3_uri_parameter, sqlite3_uri_boolean, sqlite3_uri_int64,
     sqlite3_uri_key - obtain values for URI parameters

SYNOPSIS
     #include <sqlite3.h>

     const char *
     sqlite3_uri_parameter(sqlite3_filename z, const char *zParam);

     int
     sqlite3_uri_boolean(sqlite3_filename z, const char *zParam,
         int bDefault);

     sqlite3_int64
     sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64);

     const char *
     sqlite3_uri_key(sqlite3_filename z, int N);

DESCRIPTION
     These are utility routines, useful to custom VFS implementations, that
     check if a database file was a URI that contained a specific query
     parameter, and if so obtains the value of that query parameter.

     The first parameter to these interfaces (hereafter referred to as F) must
     be one of:

     ⊕   A database filename pointer created by the SQLite core and passed
         into the xOpen() method of a VFS implementation, or

     ⊕   A filename obtained from sqlite3_db_filename(), or

     ⊕   A new filename constructed using sqlite3_create_filename().

     If the F parameter is not one of the above, then the behavior is
     undefined and probably undesirable.  Older versions of SQLite were more
     tolerant of invalid F parameters than newer versions.

     If F is a suitable filename (as described in the previous paragraph) and
     if P is the name of the query parameter, then sqlite3_uri_parameter(F,P)
     returns the value of the P parameter if it exists or a NULL pointer if P
     does not appear as a query parameter on F.  If P is a query parameter of
     F and it has no explicit value, then sqlite3_uri_parameter(F,P) returns a
     pointer to an empty string.

     The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
     parameter and returns true (1) or false (0) according to the value of P.
     The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the value of
     query parameter P is one of "yes", "true", or "on" in any case or if the
     value begins with a non-zero number.  The sqlite3_uri_boolean(F,P,B)
     routines returns false (0) if the value of query parameter P is one of
     "no", "false", or "off" in any case or if the value begins with a numeric
     zero.  If P is not a query parameter on F or if the value of P does not
     match any of the above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).

     The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
     64-bit signed integer and returns that integer, or D if P does not exist.
     If the value of P is something other than an integer, then zero is
     returned.

     The sqlite3_uri_key(F,N) returns a pointer to the name (not the value) of
     the N-th query parameter for filename F, or a NULL pointer if N is less
     than zero or greater than the number of query parameters minus 1.  The N
     value is zero-based so N should be 0 to obtain the name of the first
     query parameter, 1 for the second parameter, and so forth.

     If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
     sqlite3_uri_boolean(F,P,B) returns B.  If F is not a NULL pointer and is
     not a database file pathname pointer that the SQLite core passed into the
     xOpen VFS method, then the behavior of this routine is undefined and
     probably undesirable.

     Beginning with SQLite version 3.31.0 (dateof:3.31.0) the input F
     parameter can also be the name of a rollback journal file or WAL file in
     addition to the main database file.  Prior to version 3.31.0, these
     routines would only work if F was the name of the main database file.
     When the F parameter is the name of the rollback journal or WAL file, it
     has access to all the same query parameters as were found on the main
     database file.

     See the URI filename documentation for additional information.

IMPLEMENTATION NOTES
     These declarations were extracted from the interface documentation at
     line 3755.

     SQLITE_API const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam);
     SQLITE_API int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault);
     SQLITE_API sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64);
     SQLITE_API const char *sqlite3_uri_key(sqlite3_filename z, int N);

SEE ALSO
     sqlite3_create_filename(3), sqlite3_db_filename(3)

NetBSD 11.99                   January 24, 2024                   NetBSD 11.99