diff options
Diffstat (limited to 'www/c3ref/open.html')
| -rw-r--r-- | www/c3ref/open.html | 422 |
1 files changed, 422 insertions, 0 deletions
diff --git a/www/c3ref/open.html b/www/c3ref/open.html new file mode 100644 index 0000000..c9319ac --- /dev/null +++ b/www/c3ref/open.html @@ -0,0 +1,422 @@ +<!DOCTYPE html> +<html><head> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<meta http-equiv="content-type" content="text/html; charset=UTF-8"> +<link href="../sqlite.css" rel="stylesheet"> +<title>Opening A New Database Connection</title> +<!-- path=../ --> +</head> +<body> +<div class=nosearch> +<a href="../index.html"> +<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0"> +</a> +<div><!-- IE hack to prevent disappearing logo --></div> +<div class="tagline desktoponly"> +Small. Fast. Reliable.<br>Choose any three. +</div> +<div class="menu mainmenu"> +<ul> +<li><a href="../index.html">Home</a> +<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> +<li class='wideonly'><a href='../about.html'>About</a> +<li class='desktoponly'><a href="../docs.html">Documentation</a> +<li class='desktoponly'><a href="../download.html">Download</a> +<li class='wideonly'><a href='../copyright.html'>License</a> +<li class='desktoponly'><a href="../support.html">Support</a> +<li class='desktoponly'><a href="../prosupport.html">Purchase</a> +<li class='search' id='search_menubutton'> +<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> +</ul> +</div> +<div class="menu submenu" id="submenu"> +<ul> +<li><a href='../about.html'>About</a> +<li><a href='../docs.html'>Documentation</a> +<li><a href='../download.html'>Download</a> +<li><a href='../support.html'>Support</a> +<li><a href='../prosupport.html'>Purchase</a> +</ul> +</div> +<div class="searchmenu" id="searchmenu"> +<form method="GET" action="../search"> +<select name="s" id="searchtype"> +<option value="d">Search Documentation</option> +<option value="c">Search Changelog</option> +</select> +<input type="text" name="q" id="searchbox" value=""> +<input type="submit" value="Go"> +</form> +</div> +</div> +<script> +function toggle_div(nm) { +var w = document.getElementById(nm); +if( w.style.display=="block" ){ +w.style.display = "none"; +}else{ +w.style.display = "block"; +} +} +function toggle_search() { +var w = document.getElementById("searchmenu"); +if( w.style.display=="block" ){ +w.style.display = "none"; +} else { +w.style.display = "block"; +setTimeout(function(){ +document.getElementById("searchbox").focus() +}, 30); +} +} +function div_off(nm){document.getElementById(nm).style.display="none";} +window.onbeforeunload = function(e){div_off("submenu");} +/* Disable the Search feature if we are not operating from CGI, since */ +/* Search is accomplished using CGI and will not work without it. */ +if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ +document.getElementById("search_menubutton").style.display = "none"; +} +/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ +function hideorshow(btn,obj){ +var x = document.getElementById(obj); +var b = document.getElementById(btn); +if( x.style.display!='none' ){ +x.style.display = 'none'; +b.innerHTML='show'; +}else{ +x.style.display = ''; +b.innerHTML='hide'; +} +return false; +} +var antiRobot = 0; +function antiRobotGo(){ +if( antiRobot!=3 ) return; +antiRobot = 7; +var j = document.getElementById("mtimelink"); +if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); +} +function antiRobotDefense(){ +document.body.onmousedown=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousedown=null; +} +document.body.onmousemove=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousemove=null; +} +setTimeout(function(){ +antiRobot |= 1; +antiRobotGo(); +}, 100) +antiRobotGo(); +} +antiRobotDefense(); +</script> +<!-- keywords: sqlite3_open sqlite3_open16 sqlite3_open_v2 --> +<div class=nosearch> +<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a> +<h2>Opening A New Database Connection</h2> +</div> +<blockquote><pre> +int sqlite3_open( + const char *filename, /* Database filename (UTF-8) */ + sqlite3 **ppDb /* OUT: SQLite db handle */ +); +int sqlite3_open16( + const void *filename, /* Database filename (UTF-16) */ + sqlite3 **ppDb /* OUT: SQLite db handle */ +); +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 */ +); +</pre></blockquote> +<p> +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 <a href="../c3ref/sqlite3.html">database connection</a> 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 <a href="../c3ref/sqlite3.html">sqlite3</a> object, +a NULL will be written into *ppDb instead of a pointer to the <a href="../c3ref/sqlite3.html">sqlite3</a> +object. If the database is opened (and/or created) successfully, then +<a href="../rescode.html#ok">SQLITE_OK</a> is returned. Otherwise an <a href="../rescode.html">error code</a> is returned. The +<a href="../c3ref/errcode.html">sqlite3_errmsg()</a> or <a href="../c3ref/errcode.html">sqlite3_errmsg16()</a> routines can be used to obtain +an English language description of the error following a failure of any +of the sqlite3_open() routines.</p> + +<p>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.</p> + +<p>Whether or not an error occurs when it is opened, resources +associated with the <a href="../c3ref/sqlite3.html">database connection</a> handle should be released by +passing it to <a href="../c3ref/close.html">sqlite3_close()</a> when it is no longer required.</p> + +<p>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:</p> + +<p><dl> +<dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a></dt> +<dd>The database is opened in read-only mode. If the database does +not already exist, an error is returned.</dd></p> + +<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a></dt> +<dd>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. <a href="../c3ref/db_readonly.html">sqlite3_db_readonly()</a> can be +used to determine whether the database is actually +read-write.</dd></p> + +<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a> | <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a></dt> +<dd>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().</dd> +</dl></p> + +<p>In addition to the required flags, the following optional flags are +also supported:</p> + +<p><dl> +<dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a></dt> +<dd>The filename can be interpreted as a URI if this flag is set.</dd></p> + +<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MEMORY</a></dt> +<dd>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. +</dd></p> + +<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOMUTEX</a></dt> +<dd>The new database connection will use the "multi-thread" +<a href="../threadsafe.html">threading mode</a>. This means that separate threads are allowed +to use SQLite at the same time, as long as each thread is using +a different <a href="../c3ref/sqlite3.html">database connection</a>.</p> + +<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_FULLMUTEX</a></dt> +<dd>The new database connection will use the "serialized" +<a href="../threadsafe.html">threading mode</a>. 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.)</p> + +<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SHAREDCACHE</a></dt> +<dd>The database is opened <a href="../sharedcache.html">shared cache</a> enabled, overriding +the default shared cache setting provided by +<a href="../c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a>. +The <a href="../sharedcache.html#dontuse">use of shared cache mode is discouraged</a> and hence shared cache +capabilities may be omitted from many builds of SQLite. In such cases, +this option is a no-op.</p> + +<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_PRIVATECACHE</a></dt> +<dd>The database is opened <a href="../sharedcache.html">shared cache</a> disabled, overriding +the default shared cache setting provided by +<a href="../c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a>.</p> + +<p><a name="openexrescode"></a> + <dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXRESCODE</a></dt> +<dd>The database connection comes up in "extended result code mode". +In other words, the database behaves has if +<a href="../c3ref/extended_result_codes.html">sqlite3_extended_result_codes(db,1)</a> 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 <a href="../c3ref/open.html">sqlite3_open_v2()</a> +to return an extended result code.</dd></p> + +<p><a name="opennofollow"></a> + <dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOFOLLOW</a></dt> +<dd>The database filename is not allowed to contain a symbolic link</dd> +</dl></p> + +<p>If the 3rd parameter to sqlite3_open_v2() is not one of the +required combinations shown above optionally combined with other +<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_* bits</a> +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 <a href="../c3ref/vfs.html">VFS interface</a> only, and not +by sqlite3_open_v2().</p> + +<p>The fourth parameter to sqlite3_open_v2() is the name of the +<a href="../c3ref/vfs.html">sqlite3_vfs</a> 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 <a href="../c3ref/vfs.html">sqlite3_vfs</a> object is used.</p> + +<p>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.</p> + +<p>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.</p> + +<p><a name="urifilenamesinsqlite3open"></a> + <h3>URI Filenames</h3></p> + +<p>If <a href="../uri.html">URI filename</a> 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 <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> flag is +set in the third argument to sqlite3_open_v2(), or if it has +been enabled globally using the <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfiguri">SQLITE_CONFIG_URI</a> option with the +<a href="../c3ref/config.html">sqlite3_config()</a> method or by the <a href="../compile.html#use_uri">SQLITE_USE_URI</a> compile-time option. +URI filename interpretation is turned off +by default, but future releases of SQLite might enable URI filename +interpretation by default. See "<a href="../uri.html">URI filenames</a>" for additional +information.</p> + +<p>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.</p> + +<p>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:").</p> + +<p><a name="coreuriqueryparameters"></a> + +The query component of a URI may contain parameters that are interpreted +either by SQLite itself, or by a <a href="../vfs.html">custom VFS implementation</a>. +SQLite and its built-in <a href="../vfs.html">VFSes</a> interpret the +following query parameters:</p> + +<p><ul> +<li> <b>vfs</b>: 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().</p> + +<p><li> <b>mode</b>: 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 <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a> 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 <a href="../inmemorydb.html">in-memory database</a> 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().</p> + +<p><li> <b>cache</b>: 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.</p> + +<p><li> <b>psow</b>: The psow parameter indicates whether or not the +<a href="../psow.html">powersafe overwrite</a> property does or does not apply to the +storage media on which the database file resides.</p> + +<p><li> <b>nolock</b>: 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.</p> + +<p><li> <b>immutable</b>: 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 <a href="../rescode.html#corrupt">SQLITE_CORRUPT</a> errors. +See also: <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_IMMUTABLE</a>.</p> + +<p></ul></p> + +<p>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 "<a href="../uri.html#coreqp">query parameters with special meaning to SQLite</a>" for +additional information.</p> + +<p><a name="urifilenameexamples"></a> + <h3>URI filename examples</h3></p> + +<p><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. +Use "ro" instead: "file:data.db?mode=ro". +</table></p> + +<p>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.</p> + +<p><b>Note to Windows users:</b> 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().</p> + +<p><b>Note to Windows Runtime users:</b> 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.</p> + +<p>See also: <a href="../c3ref/temp_directory.html">sqlite3_temp_directory</a> +</p><p>See also lists of + <a href="../c3ref/objlist.html">Objects</a>, + <a href="../c3ref/constlist.html">Constants</a>, and + <a href="../c3ref/funclist.html">Functions</a>.</p> + |