1.Dd January 24, 2024 2.Dt SQLITE3_URI_PARAMETER 3 3.Os 4.Sh NAME 5.Nm sqlite3_uri_parameter , 6.Nm sqlite3_uri_boolean , 7.Nm sqlite3_uri_int64 , 8.Nm sqlite3_uri_key 9.Nd obtain values for URI parameters 10.Sh SYNOPSIS 11.In sqlite3.h 12.Ft const char * 13.Fo sqlite3_uri_parameter 14.Fa "sqlite3_filename z" 15.Fa "const char *zParam" 16.Fc 17.Ft int 18.Fo sqlite3_uri_boolean 19.Fa "sqlite3_filename z" 20.Fa "const char *zParam" 21.Fa "int bDefault" 22.Fc 23.Ft sqlite3_int64 24.Fo sqlite3_uri_int64 25.Fa "sqlite3_filename" 26.Fa "const char*" 27.Fa "sqlite3_int64" 28.Fc 29.Ft const char * 30.Fo sqlite3_uri_key 31.Fa "sqlite3_filename z" 32.Fa "int N" 33.Fc 34.Sh DESCRIPTION 35These are utility routines, useful to custom VFS implementations, 36that check if a database file was a URI that contained a specific query 37parameter, and if so obtains the value of that query parameter. 38.Pp 39The first parameter to these interfaces (hereafter referred to as F) 40must be one of: 41.Bl -bullet 42.It 43A database filename pointer created by the SQLite core and passed into 44the xOpen() method of a VFS implementation, or 45.It 46A filename obtained from 47.Fn sqlite3_db_filename , 48or 49.It 50A new filename constructed using 51.Fn sqlite3_create_filename . 52.El 53.Pp 54If the F parameter is not one of the above, then the behavior is undefined 55and probably undesirable. 56Older versions of SQLite were more tolerant of invalid F parameters 57than newer versions. 58.Pp 59If F is a suitable filename (as described in the previous paragraph) 60and if P is the name of the query parameter, then sqlite3_uri_parameter(F,P) 61returns the value of the P parameter if it exists or a NULL pointer 62if P does not appear as a query parameter on F. 63If P is a query parameter of F and it has no explicit value, then sqlite3_uri_parameter(F,P) 64returns a pointer to an empty string. 65.Pp 66The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean 67parameter and returns true (1) or false (0) according to the value 68of P. 69The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the value 70of query parameter P is one of "yes", "true", or "on" in any case or 71if the value begins with a non-zero number. 72The sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value 73of query parameter P is one of "no", "false", or "off" in any case 74or if the value begins with a numeric zero. 75If P is not a query parameter on F or if the value of P does not match 76any of the above, then sqlite3_uri_boolean(F,P,B) returns (B!=0). 77.Pp 78The sqlite3_uri_int64(F,P,D) routine converts the value of P into a 7964-bit signed integer and returns that integer, or D if P does not 80exist. 81If the value of P is something other than an integer, then zero is 82returned. 83.Pp 84The sqlite3_uri_key(F,N) returns a pointer to the name (not the value) 85of the N-th query parameter for filename F, or a NULL pointer if N 86is less than zero or greater than the number of query parameters minus 871. 88The N value is zero-based so N should be 0 to obtain the name of the 89first query parameter, 1 for the second parameter, and so forth. 90.Pp 91If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL 92and sqlite3_uri_boolean(F,P,B) returns B. 93If F is not a NULL pointer and is not a database file pathname pointer 94that the SQLite core passed into the xOpen VFS method, then the behavior 95of this routine is undefined and probably undesirable. 96.Pp 97Beginning with SQLite version 3.31.0 (dateof:3.31.0) 98the input F parameter can also be the name of a rollback journal file 99or WAL file in addition to the main database file. 100Prior to version 3.31.0, these routines would only work if F was the 101name of the main database file. 102When the F parameter is the name of the rollback journal or WAL file, 103it has access to all the same query parameters as were found on the 104main database file. 105.Pp 106See the URI filename documentation for additional information. 107.Sh IMPLEMENTATION NOTES 108These declarations were extracted from the 109interface documentation at line 3755. 110.Bd -literal 111SQLITE_API const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam); 112SQLITE_API int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault); 113SQLITE_API sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64); 114SQLITE_API const char *sqlite3_uri_key(sqlite3_filename z, int N); 115.Ed 116.Sh SEE ALSO 117.Xr sqlite3_create_filename 3 , 118.Xr sqlite3_db_filename 3 119