diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_open.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_open.3 | 335 |
1 files changed, 335 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_open.3 b/static/netbsd/man3/sqlite3_open.3 new file mode 100644 index 00000000..63581d34 --- /dev/null +++ b/static/netbsd/man3/sqlite3_open.3 @@ -0,0 +1,335 @@ +.Dd January 24, 2024 +.Dt SQLITE3_OPEN 3 +.Os +.Sh NAME +.Nm sqlite3_open , +.Nm sqlite3_open16 , +.Nm sqlite3_open_v2 +.Nd opening a new database connection +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_open +.Fa "const char *filename" +.Fa "sqlite3 **ppDb" +.Fc +.Ft int +.Fo sqlite3_open16 +.Fa "const void *filename" +.Fa "sqlite3 **ppDb" +.Fc +.Ft int +.Fo sqlite3_open_v2 +.Fa "const char *filename" +.Fa "sqlite3 **ppDb" +.Fa "int flags" +.Fa "const char *zVfs" +.Fc +.Sh DESCRIPTION +These routines open an SQLite database file as specified by the filename +argument. +The filename argument is interpreted as UTF-8 for sqlite3_open() and +sqlite3_open_v2() and as UTF-16 in the native byte order for sqlite3_open16(). +A database connection handle is usually returned +in *ppDb, even if an error occurs. +The only exception is that if SQLite is unable to allocate memory to +hold the sqlite3 object, a NULL will be written into *ppDb instead +of a pointer to the sqlite3 object. +If the database is opened (and/or created) successfully, then SQLITE_OK +is returned. +Otherwise an error code is returned. +The +.Fn sqlite3_errmsg +or +.Fn sqlite3_errmsg16 +routines can be used to obtain an English language description of the +error following a failure of any of the sqlite3_open() routines. +.Pp +The default encoding will be UTF-8 for databases created using sqlite3_open() +or sqlite3_open_v2(). +The default encoding for databases created using sqlite3_open16() will +be UTF-16 in the native byte order. +.Pp +Whether or not an error occurs when it is opened, resources associated +with the database connection handle should be released +by passing it to +.Fn sqlite3_close +when it is no longer required. +.Pp +The sqlite3_open_v2() interface works like sqlite3_open() except that +it accepts two additional parameters for additional control over the +new database connection. +The flags parameter to sqlite3_open_v2() must include, at a minimum, +one of the following three flag combinations: +.Bl -tag -width Ds +.It SQLITE_OPEN_READONLY +The database is opened in read-only mode. +If the database does not already exist, an error is returned. +.It SQLITE_OPEN_READWRITE +The database is opened for reading and writing if possible, or reading +only if the file is write protected by the operating system. +In either case the database must already exist, otherwise an error +is returned. +For historical reasons, if opening in read-write mode fails due to +OS-level permissions, an attempt is made to open it in read-only mode. +.Fn sqlite3_db_readonly +can be used to determine whether the database is actually read-write. +.It SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE +The database is opened for reading and writing, and is created if it +does not already exist. +This is the behavior that is always used for sqlite3_open() and sqlite3_open16(). +.El +.Pp +In addition to the required flags, the following optional flags are +also supported: +.Bl -tag -width Ds +.It SQLITE_OPEN_URI +The filename can be interpreted as a URI if this flag is set. +.It SQLITE_OPEN_MEMORY +The database will be opened as an in-memory database. +The database is named by the "filename" argument for the purposes of +cache-sharing, if shared cache mode is enabled, but the "filename" +is otherwise ignored. +.It SQLITE_OPEN_NOMUTEX +The new database connection will use the "multi-thread" threading mode. +This means that separate threads are allowed to use SQLite at the same +time, as long as each thread is using a different database connection. +.It SQLITE_OPEN_FULLMUTEX +The new database connection will use the "serialized" threading mode. +This means the multiple threads can safely attempt to use the same +database connection at the same time. +(Mutexes will block any actual concurrency, but in this mode there +is no harm in trying.) +.It SQLITE_OPEN_SHAREDCACHE +The database is opened shared cache enabled, overriding +the default shared cache setting provided by +.Fn sqlite3_enable_shared_cache . +The use of shared cache mode is discouraged +and hence shared cache capabilities may be omitted from many builds +of SQLite. +In such cases, this option is a no-op. +.It SQLITE_OPEN_PRIVATECACHE +The database is opened shared cache disabled, overriding +the default shared cache setting provided by +.Fn sqlite3_enable_shared_cache . +.It SQLITE_OPEN_EXRESCODE +The database connection comes up in "extended result code mode". +In other words, the database behaves has if sqlite3_extended_result_codes(db,1) +where called on the database connection as soon as the connection is +created. +In addition to setting the extended result code mode, this flag also +causes +.Fn sqlite3_open_v2 +to return an extended result code. +.It SQLITE_OPEN_NOFOLLOW +The database filename is not allowed to contain a symbolic link +.El +.Pp +If the 3rd parameter to sqlite3_open_v2() is not one of the required +combinations shown above optionally combined with other SQLITE_OPEN_* bits +then the behavior is undefined. +Historic versions of SQLite have silently ignored surplus bits in the +flags parameter to sqlite3_open_v2(), however that behavior might not +be carried through into future versions of SQLite and so applications +should not rely upon it. +Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op for +sqlite3_open_v2(). +The SQLITE_OPEN_EXCLUSIVE does *not* cause the open to fail if the +database already exists. +The SQLITE_OPEN_EXCLUSIVE flag is intended for use by the VFS interface +only, and not by sqlite3_open_v2(). +.Pp +The fourth parameter to sqlite3_open_v2() is the name of the sqlite3_vfs +object that defines the operating system interface that the new database +connection should use. +If the fourth parameter is a NULL pointer then the default sqlite3_vfs +object is used. +.Pp +If the filename is ":memory:", then a private, temporary in-memory +database is created for the connection. +This in-memory database will vanish when the database connection is +closed. +Future versions of SQLite might make use of additional special filenames +that begin with the ":" character. +It is recommended that when a database filename actually does begin +with a ":" character you should prefix the filename with a pathname +such as "./" to avoid ambiguity. +.Pp +If the filename is an empty string, then a private, temporary on-disk +database will be created. +This private database will be automatically deleted as soon as the +database connection is closed. +.Ss URI Filenames +If URI filename interpretation is enabled, and the filename +argument begins with "file:", then the filename is interpreted as a +URI. +URI filename interpretation is enabled if the SQLITE_OPEN_URI +flag is set in the third argument to sqlite3_open_v2(), or if it has +been enabled globally using the SQLITE_CONFIG_URI +option with the +.Fn sqlite3_config +method or by the SQLITE_USE_URI compile-time option. +URI filename interpretation is turned off by default, but future releases +of SQLite might enable URI filename interpretation by default. +See "URI filenames" for additional information. +.Pp +URI filenames are parsed according to RFC 3986. +If the URI contains an authority, then it must be either an empty string +or the string "localhost". +If the authority is not an empty string or "localhost", an error is +returned to the caller. +The fragment component of a URI, if present, is ignored. +.Pp +SQLite uses the path component of the URI as the name of the disk file +which contains the database. +If the path begins with a '/' character, then it is interpreted as +an absolute path. +If the path does not begin with a '/' (meaning that the authority section +is omitted from the URI) then the path is interpreted as a relative +path. +On windows, the first component of an absolute path is a drive specification +(e.g. "C:"). +.Pp +The query component of a URI may contain parameters that are interpreted +either by SQLite itself, or by a custom VFS implementation. +SQLite and its built-in VFSes interpret the following query parameters: +.Bl -bullet +.It +\fBvfs\fP: 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 present, then the +VFS specified by the option takes precedence over the value passed +as the fourth parameter to sqlite3_open_v2(). +.It +\fBmode\fP: The mode parameter may be set to either "ro", "rw", "rwc", or +"memory". +Attempting to set it to any other value is an error. +If "ro" is specified, then the database is opened for read-only access, +just as if the SQLITE_OPEN_READONLY flag had been +set in the third argument to sqlite3_open_v2(). +If the mode option is set to "rw", then the database is opened for +read-write (but not create) access, as if SQLITE_OPEN_READWRITE (but +not SQLITE_OPEN_CREATE) had been set. +Value "rwc" is equivalent to setting both SQLITE_OPEN_READWRITE and +SQLITE_OPEN_CREATE. +If the mode option is set to "memory" then a pure in-memory database +that never reads or writes from disk is used. +It is an error to specify a value for the mode parameter that is less +restrictive than that specified by the flags passed in the third parameter +to sqlite3_open_v2(). +.It +\fBcache\fP: The cache parameter may be set to either "shared" or "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 behavior requested by setting +SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag. +.It +\fBpsow\fP: The psow parameter indicates whether or not the powersafe overwrite +property does or does not apply to the storage media on which the database +file resides. +.It +\fBnolock\fP: The nolock parameter is a boolean query parameter which if +set disables file locking in rollback journal modes. +This is useful for accessing a database on a filesystem that does not +support locking. +Caution: Database corruption might result if two or more processes +write to the same database and any one of those processes uses nolock=1. +.It +\fBimmutable\fP: The immutable parameter is a boolean query parameter that +indicates that the database file is stored on read-only media. +When immutable is set, SQLite assumes that the database file cannot +be changed, even by a process with higher privilege, and so the database +is opened read-only and all locking and change detection is disabled. +Caution: Setting the immutable property on a database file that does +in fact change can result in incorrect query results and/or SQLITE_CORRUPT +errors. +.El +.Pp +Specifying an unknown parameter in the query component of a URI is +not an error. +Future versions of SQLite might understand additional query parameters. +See "query parameters with special meaning to SQLite" +for additional information. +.Ss URI filename examples +.Pp + URI filenames Results + file:data.db Open the file "data.db" in the current directory. + file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db + Open the database file "/home/fred/data.db". + file://darkstar/home/fred/data.db An error. +"darkstar" is not a recognized authority. + file:///C:/Documents%20and%20Settings/fred/Desktop/data.db Windows +only: Open the file "data.db" on fred's desktop on drive C:. +Note that the %20 escaping in this example is not strictly necessary +- space characters can be used literally in URI filenames. + file:data.db?mode=ro&cache=private Open file "data.db" in the current +directory for read-only access. +Regardless of whether or not shared-cache mode is enabled by default, +use a private cache. + file:/home/fred/data.db?vfs=unix-dotfile Open file "/home/fred/data.db". +Use the special VFS "unix-dotfile" that uses dot-files in place of +posix advisory locking. + file:data.db?mode=readonly An error. +"readonly" is not a valid option for the "mode" parameter. +Use "ro" instead: "file:data.db?mode=ro". +.Pp +URI hexadecimal escape sequences (%HH) are supported within the path +and query components of a URI. +A hexadecimal escape sequence consists of a percent sign - "%" - followed +by exactly two hexadecimal digits specifying an octet value. +Before the path or query components of a URI filename are interpreted, +they are encoded using UTF-8 and all hexadecimal escape sequences replaced +by a single byte containing the corresponding octet. +If this process generates an invalid UTF-8 encoding, the results are +undefined. +.Pp +\fBNote to Windows users:\fP The encoding used for the filename argument +of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever +codepage is currently defined. +Filenames containing international characters must be converted to +UTF-8 prior to passing them into sqlite3_open() or sqlite3_open_v2(). +.Pp +\fBNote to Windows Runtime users:\fP The temporary directory must be set +prior to calling sqlite3_open() or sqlite3_open_v2(). +Otherwise, various features that require the use of temporary files +may fail. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3462. +.Bd -literal +SQLITE_API int sqlite3_open( + const char *filename, /* Database filename (UTF-8) */ + sqlite3 **ppDb /* OUT: SQLite db handle */ +); +SQLITE_API int sqlite3_open16( + const void *filename, /* Database filename (UTF-16) */ + sqlite3 **ppDb /* OUT: SQLite db handle */ +); +SQLITE_API int sqlite3_open_v2( + const char *filename, /* Database filename (UTF-8) */ + sqlite3 **ppDb, /* OUT: SQLite db handle */ + int flags, /* Flags */ + const char *zVfs /* Name of VFS module to use */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_close 3 , +.Xr sqlite3_config 3 , +.Xr sqlite3_db_readonly 3 , +.Xr sqlite3_enable_shared_cache 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_temp_directory 3 , +.Xr sqlite3_vfs 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 , +.Xr SQLITE_IOCAP_ATOMIC 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_OPEN_READONLY 3 |