273 lines
12 KiB
Groff
273 lines
12 KiB
Groff
.Dd March 11, 2017
|
|
.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
|
|
.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 sqlite3_errmsg() or 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 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() can take one of the following
|
|
three values, optionally combined with the SQLITE_OPEN_NOMUTEX,
|
|
SQLITE_OPEN_FULLMUTEX, SQLITE_OPEN_SHAREDCACHE,
|
|
SQLITE_OPEN_PRIVATECACHE, and/or SQLITE_OPEN_URI
|
|
flags:
|
|
.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.
|
|
.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
|
|
If the 3rd parameter to sqlite3_open_v2() is not one of the combinations
|
|
shown above optionally combined with other SQLITE_OPEN_* bits
|
|
then the behavior is undefined.
|
|
.Pp
|
|
If the SQLITE_OPEN_NOMUTEX flag is set, then the
|
|
database connection opens in the multi-thread threading mode
|
|
as long as the single-thread mode has not been set at compile-time
|
|
or start-time.
|
|
If the SQLITE_OPEN_FULLMUTEX flag is set then
|
|
the database connection opens in the serialized threading mode
|
|
unless single-thread was previously selected at compile-time or start-time.
|
|
The SQLITE_OPEN_SHAREDCACHE flag causes the
|
|
database connection to be eligible to use shared cache mode,
|
|
regardless of whether or not shared cache is enabled using sqlite3_enable_shared_cache().
|
|
The SQLITE_OPEN_PRIVATECACHE flag causes the
|
|
database connection to not participate in shared cache mode
|
|
even if it is enabled.
|
|
.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 fourth argument to sqlite3_open_v2(), or if it has
|
|
been enabled globally using the SQLITE_CONFIG_URI
|
|
option with the sqlite3_config() method or by the SQLITE_USE_URI
|
|
compile-time option.
|
|
As of SQLite version 3.7.7, 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
|
|
<table border="1" align=center cellpadding=5> <tr><th> URI filenames
|
|
<th> Results <tr><td> file:data.db <td> Open the file "data.db" in
|
|
the current directory.
|
|
<tr><td> file:/home/fred/data.db<br> file:///home/fred/data.db <br>
|
|
file://localhost/home/fred/data.db <br> <td> Open the database file
|
|
"/home/fred/data.db".
|
|
<tr><td> file://darkstar/home/fred/data.db <td> An error.
|
|
"darkstar" is not a recognized authority.
|
|
<tr><td style="white-space:nowrap"> file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
|
|
<td> 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.
|
|
<tr><td> file:data.db?mode=ro&cache=private <td> 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.
|
|
<tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td> Open file "/home/fred/data.db".
|
|
Use the special VFS "unix-dotfile" that uses dot-files in place of
|
|
posix advisory locking.
|
|
<tr><td> file:data.db?mode=readonly <td> An error.
|
|
"readonly" is not a valid option for the "mode" parameter.
|
|
</table>
|
|
.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 SEE ALSO
|
|
.Xr sqlite3 3 ,
|
|
.Xr sqlite3_close 3 ,
|
|
.Xr sqlite3_config 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_OK 3 ,
|
|
.Xr SQLITE_IOCAP_ATOMIC 3 ,
|
|
.Xr SQLITE_OK 3 ,
|
|
.Xr SQLITE_OPEN_READONLY 3
|