*** DRAFT ***

SQLite Requirement Matrix Details
open.html

Index Summary Markup Original


R-39350-14264-06804-50075-43758-39518-52551-62265 tcl slt th3 src

These routines open an SQLite database file as specified by the filename argument.

/* IMP: R-39350-14264 */
# EVIDENCE-OF: R-39350-14264 These routines open an SQLite database file
# as specified by the filename argument.

R-43415-05262-05879-65095-11903-46844-51636-40644 tcl slt th3 src

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().

th3/req1/autoext01.test:159

/* IMP: R-43415-05262 */
# EVIDENCE-OF: R-43415-05262 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().

R-47032-28289-44184-46595-09836-48485-53901-64968 tcl slt th3 src

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.

/* IMP: R-47032-28289 */
# EVIDENCE-OF: R-47032-28289 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.

R-08348-34672-30710-39534-43438-18204-53248-46501 tcl slt th3 src

If the database is opened (and/or created) successfully, then SQLITE_OK is returned. Otherwise an error code is returned.

/* IMP: R-08348-34672 */
# EVIDENCE-OF: R-08348-34672 If the database is opened (and/or created)
# successfully, then SQLITE_OK is returned. Otherwise an error code is
# returned.

R-35739-57436-25800-46947-32358-09819-57778-06393 tcl slt th3 src

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.

/* IMP: R-35739-57436 */
# EVIDENCE-OF: R-35739-57436 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.

R-63260-45699-31431-11817-19083-14661-24808-60223 tcl slt th3 src

The default encoding will be UTF-8 for databases created using sqlite3_open() or sqlite3_open_v2().

th3/cov1/main12.test:124

/* IMP: R-63260-45699 */
# EVIDENCE-OF: R-63260-45699 The default encoding will be UTF-8 for
# databases created using sqlite3_open() or sqlite3_open_v2().

R-56593-29586-46477-05582-12262-16741-07169-41199 tcl slt th3 src

The default encoding for databases created using sqlite3_open16() will be UTF-16 in the native byte order.

th3/cov1/main12.test:116

/* IMP: R-56593-29586 */
# EVIDENCE-OF: R-56593-29586 The default encoding for databases created
# using sqlite3_open16() will be UTF-16 in the native byte order.

R-18321-05872-40763-16666-14015-36142-16508-50881 tcl slt th3 src

The flags parameter to sqlite3_open_v2() must include, at a minimum, one of the following three flag combinations:

src/main.c:3406

/* IMP: R-18321-05872 */
# EVIDENCE-OF: R-18321-05872 The flags parameter to sqlite3_open_v2()
# must include, at a minimum, one of the following three flag
# combinations:

R-33401-06099-44102-08352-15092-58623-33401-34005 tcl slt th3 src

SQLITE_OPEN_READONLY The database is opened in read-only mode. If the database does not already exist, an error is returned.

/* IMP: R-33401-06099 */
# EVIDENCE-OF: R-33401-06099 SQLITE_OPEN_READONLY The database is opened
# in read-only mode. If the database does not already exist, an error is
# returned.

R-45025-26790-12861-22163-48141-57722-01332-42216 tcl slt th3 src

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. sqlite3_db_readonly() can be used to determine whether the database is actually read-write.

/* IMP: R-45025-26790 */
# EVIDENCE-OF: R-45025-26790 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.
# sqlite3_db_readonly() can be used to determine whether the database is
# actually read-write.

R-24663-27339-41709-46831-61109-18753-41935-55210 tcl slt th3 src

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().

/* IMP: R-24663-27339 */
# EVIDENCE-OF: R-24663-27339 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().

R-20589-01955-18800-07127-42802-30893-02013-32671 tcl slt th3 src

SQLITE_OPEN_URI The filename can be interpreted as a URI if this flag is set.

/* IMP: R-20589-01955 */
# EVIDENCE-OF: R-20589-01955 SQLITE_OPEN_URI The filename can be
# interpreted as a URI if this flag is set.

R-25882-51550-16212-06454-16146-64979-21023-53530 tcl slt th3 src

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.

/* IMP: R-25882-51550 */
# EVIDENCE-OF: R-25882-51550 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.

R-57259-65459-47411-32536-55813-09226-48634-58743 tcl slt th3 src

SQLITE_OPEN_NOMUTEX The new database connection will use the "multi-thread" threading mode.

th3/cov1/main12.test:227

/* IMP: R-57259-65459 */
# EVIDENCE-OF: R-57259-65459 SQLITE_OPEN_NOMUTEX The new database
# connection will use the "multi-thread" threading mode.

R-59964-54038-02693-18271-12639-43179-21789-28572 tcl slt th3 src

SQLITE_OPEN_FULLMUTEX The new database connection will use the "serialized" threading mode.

th3/cov1/main12.test:238

/* IMP: R-59964-54038 */
# EVIDENCE-OF: R-59964-54038 SQLITE_OPEN_FULLMUTEX The new database
# connection will use the "serialized" threading mode.

R-62978-45795-36249-12857-49090-15958-00681-53876 tcl slt th3 src

SQLITE_OPEN_SHAREDCACHE The database is opened shared cache enabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache().

/* IMP: R-62978-45795 */
# EVIDENCE-OF: R-62978-45795 SQLITE_OPEN_SHAREDCACHE The database is
# opened shared cache enabled, overriding the default shared cache
# setting provided by sqlite3_enable_shared_cache().

R-34068-60670-00760-36695-36282-03640-02435-26992 tcl slt th3 src

SQLITE_OPEN_PRIVATECACHE The database is opened shared cache disabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache().

/* IMP: R-34068-60670 */
# EVIDENCE-OF: R-34068-60670 SQLITE_OPEN_PRIVATECACHE The database is
# opened shared cache disabled, overriding the default shared cache
# setting provided by sqlite3_enable_shared_cache().

R-22568-45663-55668-47915-50757-16894-43976-31844 tcl slt th3 src

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 sqlite3_open_v2() to return an extended result code.

^(SQLITE_OPEN_NOFOLLOW The database filename is not allowed to contain a symbolic link

/* IMP: R-22568-45663 */
# EVIDENCE-OF: R-22568-45663 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 sqlite3_open_v2() to return an extended result code.
# ^(SQLITE_OPEN_NOFOLLOW The database filename is not allowed to contain
# a symbolic link

R-40858-03003-08666-12472-31051-52566-61637-28947 tcl slt th3 src

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.

/* IMP: R-40858-03003 */
# EVIDENCE-OF: R-40858-03003 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.

R-51885-22945-13735-45717-24021-29019-43116-06433 tcl slt th3 src

If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used.

/* IMP: R-51885-22945 */
# EVIDENCE-OF: R-51885-22945 If the fourth parameter is a NULL pointer
# then the default sqlite3_vfs object is used.

R-38255-01123-17984-58641-36613-29376-16056-55612 tcl slt th3 src

If the filename is ":memory:", then a private, temporary in-memory database is created for the connection.

th3/cov1/sharedcache03.test:25

/* IMP: R-38255-01123 */
# EVIDENCE-OF: R-38255-01123 If the filename is ":memory:", then a
# private, temporary in-memory database is created for the connection.

R-02452-55255-23051-52258-05350-24145-51359-57873 tcl slt th3 src

This in-memory database will vanish when the database connection is closed.

th3/cov1/sharedcache03.test:28

/* IMP: R-02452-55255 */
# EVIDENCE-OF: R-02452-55255 This in-memory database will vanish when
# the database connection is closed.

R-02552-35840-06241-57542-28930-20966-35259-36291 tcl slt th3 src

If the filename is an empty string, then a private, temporary on-disk database will be created.

/* IMP: R-02552-35840 */
# EVIDENCE-OF: R-02552-35840 If the filename is an empty string, then a
# private, temporary on-disk database will be created.

R-03805-18240-25396-23037-09576-28411-40508-44417 tcl slt th3 src

This private database will be automatically deleted as soon as the database connection is closed.

/* IMP: R-03805-18240 */
# EVIDENCE-OF: R-03805-18240 This private database will be automatically
# deleted as soon as the database connection is closed.

R-35840-33204-13129-04501-28754-46758-55672-28059 tcl slt th3 src

If URI filename interpretation is enabled, and the filename argument begins with "file:", then the filename is interpreted as a URI.

tcl/e_uri.test:50

/* IMP: R-35840-33204 */
# EVIDENCE-OF: R-35840-33204 If URI filename interpretation is enabled,
# and the filename argument begins with "file:", then the filename is
# interpreted as a URI.

R-27632-24205-25477-34441-62508-04163-16390-61608 tcl slt th3 src

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 sqlite3_config() method or by the SQLITE_USE_URI compile-time option.

tcl/e_uri.test:54

/* IMP: R-27632-24205 */
# EVIDENCE-OF: R-27632-24205 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 sqlite3_config() method or by the
# SQLITE_USE_URI compile-time option.

R-06842-00595-27459-11943-09880-13369-18922-07215 tcl slt th3 src

If the URI contains an authority, then it must be either an empty string or the string "localhost".

tcl/e_uri.test:131

/* IMP: R-06842-00595 */
# EVIDENCE-OF: R-06842-00595 If the URI contains an authority, then it
# must be either an empty string or the string "localhost".

R-17482-00398-10630-63000-62255-53684-56492-08333 tcl slt th3 src

If the authority is not an empty string or "localhost", an error is returned to the caller.

tcl/e_uri.test:134

/* IMP: R-17482-00398 */
# EVIDENCE-OF: R-17482-00398 If the authority is not an empty string or
# "localhost", an error is returned to the caller.

R-45981-25528-39449-05041-45662-56122-46761-09278 tcl slt th3 src

The fragment component of a URI, if present, is ignored.

tcl/e_uri.test:154

/* IMP: R-45981-25528 */
# EVIDENCE-OF: R-45981-25528 The fragment component of a URI, if
# present, is ignored.

R-62557-09390-19199-07054-57696-39577-58389-44787 tcl slt th3 src

SQLite uses the path component of the URI as the name of the disk file which contains the database.

tcl/e_uri.test:169

/* IMP: R-62557-09390 */
# EVIDENCE-OF: R-62557-09390 SQLite uses the path component of the URI
# as the name of the disk file which contains the database.

R-28659-11035-10621-07368-12698-03611-12155-24539 tcl slt th3 src

If the path begins with a '/' character, then it is interpreted as an absolute path.

tcl/e_uri.test:172

/* IMP: R-28659-11035 */
# EVIDENCE-OF: R-28659-11035 If the path begins with a '/' character,
# then it is interpreted as an absolute path.

R-46234-61323-27035-49381-04828-37598-41286-52895 tcl slt th3 src

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.

tcl/e_uri.test:175

/* IMP: R-46234-61323 */
# EVIDENCE-OF: R-46234-61323 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.

R-20051-05832-30877-26776-57299-30715-57449-61816 tcl slt th3 src

On windows, the first component of an absolute path is a drive specification (e.g. "C:").

/* IMP: R-20051-05832 */
# EVIDENCE-OF: R-20051-05832 On windows, the first component of an
# absolute path is a drive specification (e.g. "C:").

R-01612-30877-07572-17003-08953-37118-55537-45996 tcl slt th3 src

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.

tcl/e_uri.test:189

/* IMP: R-01612-30877 */
# EVIDENCE-OF: R-01612-30877 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.

R-52293-58497-02008-48685-44667-03336-29126-34066 tcl slt th3 src

If this option is set to an empty string the default VFS object is used.

tcl/e_uri.test:195

/* IMP: R-52293-58497 */
# EVIDENCE-OF: R-52293-58497 If this option is set to an empty string
# the default VFS object is used.

R-48365-36308-32644-24714-49385-43742-45411-08326 tcl slt th3 src

Specifying an unknown VFS is an error.

tcl/e_uri.test:239

/* IMP: R-48365-36308 */
# EVIDENCE-OF: R-48365-36308 Specifying an unknown VFS is an error.

R-31855-18665-44731-17316-60627-29707-46771-04515 tcl slt th3 src

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().

tcl/e_uri.test:200

/* IMP: R-31855-18665 */
# EVIDENCE-OF: R-31855-18665 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().

R-44013-13102-10441-32146-65192-28233-37032-42173 tcl slt th3 src

The mode parameter may be set to either "ro", "rw", "rwc", or "memory". Attempting to set it to any other value is an error

tcl/e_uri.test:250

/* IMP: R-44013-13102 */
# EVIDENCE-OF: R-44013-13102 The mode parameter may be set to either
# "ro", "rw", "rwc", or "memory". Attempting to set it to any other
# value is an error

R-43036-46756-34715-46322-50618-48036-10639-21553 tcl slt th3 src

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().

tcl/e_uri.test:270

/* IMP: R-43036-46756 */
# EVIDENCE-OF: R-43036-46756 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().

R-40137-26050-25715-27051-43009-42599-25608-04347 tcl slt th3 src

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.

tcl/e_uri.test:274

/* IMP: R-40137-26050 */
# EVIDENCE-OF: R-40137-26050 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.

R-26845-32976-14599-31607-31221-37786-17413-24156 tcl slt th3 src

Value "rwc" is equivalent to setting both SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE.

tcl/e_uri.test:278

/* IMP: R-26845-32976 */
# EVIDENCE-OF: R-26845-32976 Value "rwc" is equivalent to setting both
# SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE.

R-43042-25245-03668-43553-25952-57766-42536-13209 tcl slt th3 src

If the mode option is set to "memory" then a pure in-memory database that never reads or writes from disk is used.

th3/cov1/sharedcache03.test:204

/* IMP: R-43042-25245 */
# EVIDENCE-OF: R-43042-25245 If the mode option is set to "memory" then
# a pure in-memory database that never reads or writes from disk is
# used.

R-20590-08726-45565-50300-40304-23510-62801-34037 tcl slt th3 src

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().

tcl/e_uri.test:317

/* IMP: R-20590-08726 */
# EVIDENCE-OF: R-20590-08726 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().

R-23182-54295-50785-24596-08451-02370-06326-41675 tcl slt th3 src

The cache parameter may be set to either "shared" or "private".

tcl/e_uri.test:348

/* IMP: R-23182-54295 */
# EVIDENCE-OF: R-23182-54295 The cache parameter may be set to either
# "shared" or "private".

R-23027-03515-05606-08970-61667-55431-59935-24913 tcl slt th3 src

Setting it to "shared" is equivalent to setting the SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to sqlite3_open_v2().

tcl/e_uri.test:362

/* IMP: R-23027-03515 */
# EVIDENCE-OF: R-23027-03515 Setting it to "shared" is equivalent to
# setting the SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed
# to sqlite3_open_v2().

R-49793-28525-19299-21644-21029-37441-20100-31652 tcl slt th3 src

Setting the cache parameter to "private" is equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.

tcl/e_uri.test:366

/* IMP: R-49793-28525 */
# EVIDENCE-OF: R-49793-28525 Setting the cache parameter to "private" is
# equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.

R-31773-41793-43777-15026-65463-02438-20954-63890 tcl slt th3 src

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.

tcl/e_uri.test:369

/* IMP: R-31773-41793 */
# EVIDENCE-OF: R-31773-41793 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.

R-30025-13801-01234-26643-63886-25441-43268-35607 tcl slt th3 src

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.

th3/cov1/psow01.test:10

/* IMP: R-30025-13801 */
# EVIDENCE-OF: R-30025-13801 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.

R-58160-63457-25230-02228-13087-65392-10512-19880 tcl slt th3 src

The nolock parameter is a boolean query parameter which if set disables file locking in rollback journal modes.

th3/cov1/nolock01.test:10

/* IMP: R-58160-63457 */
# EVIDENCE-OF: R-58160-63457 The nolock parameter is a boolean query
# parameter which if set disables file locking in rollback journal
# modes.

R-09247-46544-65339-05337-14094-58644-44779-17885 tcl slt th3 src

The immutable parameter is a boolean query parameter that indicates that the database file is stored on read-only media.

th3/cov1/nolock01.test:56

/* IMP: R-09247-46544 */
# EVIDENCE-OF: R-09247-46544 The immutable parameter is a boolean query
# parameter that indicates that the database file is stored on read-only
# media.

R-13549-01731-45628-33361-33638-05320-24749-58227 tcl slt th3 src

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.

th3/cov1/nolock01.test:60

/* IMP: R-13549-01731 */
# EVIDENCE-OF: R-13549-01731 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.

R-63472-46769-27275-37406-54575-06040-42542-11572 tcl slt th3 src

Specifying an unknown parameter in the query component of a URI is not an error.

tcl/e_uri.test:436

/* IMP: R-63472-46769 */
# EVIDENCE-OF: R-63472-46769 Specifying an unknown parameter in the
# query component of a URI is not an error.

R-27458-04043-31882-50848-08148-11623-61104-53512 tcl slt th3 src

URI hexadecimal escape sequences (%HH) are supported within the path and query components of a URI.

tcl/e_uri.test:446

/* IMP: R-27458-04043 */
# EVIDENCE-OF: R-27458-04043 URI hexadecimal escape sequences (%HH) are
# supported within the path and query components of a URI.

R-52765-50368-61769-61482-53990-53504-23409-31144 tcl slt th3 src

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.

tcl/e_uri.test:449

/* IMP: R-52765-50368 */
# EVIDENCE-OF: R-52765-50368 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.