📄 open.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html><head><title>Opening A New Database Connection</title><style type="text/css">body { margin: auto; font-family: "Verdana" "sans-serif"; padding: 8px 1%;}a { color: #45735f }a:visited { color: #734559 }.logo { position:absolute; margin:3px; }.tagline { float:right; text-align:right; font-style:italic; width:240px; margin:12px; margin-top:58px;}.toolbar { font-variant: small-caps; text-align: center; line-height: 1.6em; margin: 0; padding:1px 8px;}.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }.toolbar a:visited { color: white; }.toolbar a:hover { color: #80a796; background: white; }.content { margin: 5%; }.content dt { font-weight:bold; }.content dd { margin-bottom: 25px; margin-left:20%; }.content ul { padding:0px; padding-left: 15px; margin:0px; }/* rounded corners */.se { background: url(../images/se.png) 100% 100% no-repeat #80a796}.sw { background: url(../images/sw.png) 0% 100% no-repeat }.ne { background: url(../images/ne.png) 100% 0% no-repeat }.nw { background: url(../images/nw.png) 0% 0% no-repeat }</style><meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head><body><div><!-- container div to satisfy validator --><a href="../index.html"><img class="logo" src="../images/SQLite.gif" alt="SQLite Logo" border="0"></a><div><!-- IE hack to prevent disappearing logo--></div><div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div><table width=100% style="clear:both"><tr><td> <div class="se"><div class="sw"><div class="ne"><div class="nw"> <div class="toolbar"> <a href="../about.html">About</a> <a href="../sitemap.html">Sitemap</a> <a href="../docs.html">Documentation</a> <a href="../download.html">Download</a> <a href="../copyright.html">License</a> <a href="../news.html">News</a> <a href="http://www.sqlite.org/cvstrac/index">Developers</a> <a href="../support.html">Support</a> </div></div></div></div></div></td></tr></table> <a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Opening A New Database Connection</h2><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 whose name is given by thefilename argument. The filename argument is interpreted as UTF-8 forsqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byteorder for sqlite3_open16(). A <a href="../c3ref/sqlite3.html">database connection</a> handle is usuallyreturned in *ppDb, even if an error occurs. The only exception is thatif 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="../c3ref/c_abort.html">SQLITE_OK</a> is returned. Otherwise an <a href="../c3ref/c_abort.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 obtainan English language description of the error.</p><p>The default encoding for the database will be UTF-8 ifsqlite3_open() or sqlite3_open_v2() is called andUTF-16 in the native byte order if sqlite3_open16() is used.</p><p>Whether or not an error occurs when it is opened, resourcesassociated with the <a href="../c3ref/sqlite3.html">database connection</a> handle should be released bypassing 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 controlover the new database connection. The flags parameter can take one ofthe following three values, optionally combined with the<a href="../c3ref/c_open_create.html">SQLITE_OPEN_NOMUTEX</a> or <a href="../c3ref/c_open_create.html">SQLITE_OPEN_FULLMUTEX</a> flags:</p><p><dl><dt><a href="../c3ref/c_open_create.html">SQLITE_OPEN_READONLY</a></dt><dd>The database is opened in read-only mode. If the database does notalready exist, an error is returned.</dd></p><p><dt><a href="../c3ref/c_open_create.html">SQLITE_OPEN_READWRITE</a></dt><dd>The database is opened for reading and writing if possible, or readingonly if the file is write protected by the operating system. In eithercase the database must already exist, otherwise an error is returned.</dd></p><p><dt><a href="../c3ref/c_open_create.html">SQLITE_OPEN_READWRITE</a> | <a href="../c3ref/c_open_create.html">SQLITE_OPEN_CREATE</a></dt><dd>The database is opened for reading and writing, and is creates it ifit does not already exist. This is the behavior that is always used forsqlite3_open() and sqlite3_open16().</dd></dl></p><p>If the 3rd parameter to sqlite3_open_v2() is not one of thecombinations shown above or one of the combinations shown above combinedwith the <a href="../c3ref/c_open_create.html">SQLITE_OPEN_NOMUTEX</a> or <a href="../c3ref/c_open_create.html">SQLITE_OPEN_FULLMUTEX</a> flags,then the behavior is undefined.</p><p>If the <a href="../c3ref/c_open_create.html">SQLITE_OPEN_NOMUTEX</a> flag is set, then the database connectionopens in the multi-thread <a href="../threadsafe.html">threading mode</a> as long as the single-threadmode has not been set at compile-time or start-time. If the<a href="../c3ref/c_open_create.html">SQLITE_OPEN_FULLMUTEX</a> flag is set then the database connection opensin the serialized <a href="../threadsafe.html">threading mode</a> unless single-thread waspreviously selected at compile-time or start-time.</p><p>If the filename is ":memory:", then a private, temporary in-memory databaseis created for the connection. This in-memory database will vanish whenthe database connection is closed. Future versions of SQLite mightmake use of additional special filenames that begin with the ":" character.It is recommended that when a database filename actually does begin witha ":" 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, temporaryon-disk database will be created. This private database will beautomatically deleted as soon as the database connection is closed.</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 thatthe new database connection should use. If the fourth parameter isa NULL pointer then the default <a href="../c3ref/vfs.html">sqlite3_vfs</a> object is used.</p><p><b>Note to Windows users:</b> The encoding used for the filename argumentof sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatevercodepage is currently defined. Filenames containing internationalcharacters must be converted to UTF-8 prior to passing them intosqlite3_open() or sqlite3_open_v2().</p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">H12701</td> <td valign="top">The <a href="../c3ref/open.html">sqlite3_open()</a>, <a href="../c3ref/open.html">sqlite3_open16()</a>, and<a href="../c3ref/open.html">sqlite3_open_v2()</a> interfaces create a new<a href="../c3ref/sqlite3.html">database connection</a> associated withthe database file given in their first parameter.</td></tr><tr><td valign="top">H12702</td> <td valign="top">The filename argument is interpreted as UTF-8for <a href="../c3ref/open.html">sqlite3_open()</a> and <a href="../c3ref/open.html">sqlite3_open_v2()</a> and as UTF-16in the native byte order for <a href="../c3ref/open.html">sqlite3_open16()</a>.</td></tr><tr><td valign="top">H12703</td> <td valign="top">A successful invocation of <a href="../c3ref/open.html">sqlite3_open()</a>, <a href="../c3ref/open.html">sqlite3_open16()</a>,or <a href="../c3ref/open.html">sqlite3_open_v2()</a> writes a pointer to a new<a href="../c3ref/sqlite3.html">database connection</a> into *ppDb.</td></tr><tr><td valign="top">H12704</td> <td valign="top">The <a href="../c3ref/open.html">sqlite3_open()</a>, <a href="../c3ref/open.html">sqlite3_open16()</a>, and<a href="../c3ref/open.html">sqlite3_open_v2()</a> interfaces return <a href="../c3ref/c_abort.html">SQLITE_OK</a> upon success,or an appropriate <a href="../c3ref/c_abort.html">error code</a> on failure.</td></tr><tr><td valign="top">H12706</td> <td valign="top">The default text encoding for a new database created using<a href="../c3ref/open.html">sqlite3_open()</a> or <a href="../c3ref/open.html">sqlite3_open_v2()</a> will be UTF-8.</td></tr><tr><td valign="top">H12707</td> <td valign="top">The default text encoding for a new database created using<a href="../c3ref/open.html">sqlite3_open16()</a> will be UTF-16.</td></tr><tr><td valign="top">H12709</td> <td valign="top">The <a href="../c3ref/open.html">sqlite3_open(F,D)</a> interface is equivalent to<a href="../c3ref/open.html">sqlite3_open_v2(F,D,G,0)</a> where the G parameter is<a href="../c3ref/c_open_create.html">SQLITE_OPEN_READWRITE</a>|<a href="../c3ref/c_open_create.html">SQLITE_OPEN_CREATE</a>.</td></tr><tr><td valign="top">H12711</td> <td valign="top">If the G parameter to <a href="../c3ref/open.html">sqlite3_open_v2(F,D,G,V)</a> contains thebit value <a href="../c3ref/c_open_create.html">SQLITE_OPEN_READONLY</a> then the database is openedfor reading only.</td></tr><tr><td valign="top">H12712</td> <td valign="top">If the G parameter to <a href="../c3ref/open.html">sqlite3_open_v2(F,D,G,V)</a> contains thebit value <a href="../c3ref/c_open_create.html">SQLITE_OPEN_READWRITE</a> then the database is openedreading and writing if possible, or for reading only if thefile is write protected by the operating system.</td></tr><tr><td valign="top">H12713</td> <td valign="top">If the G parameter to <a href="../c3ref/open.html">sqlite3_open_v2(F,D,G,V)</a> omits thebit value <a href="../c3ref/c_open_create.html">SQLITE_OPEN_CREATE</a> and the database does notpreviously exist, an error is returned.</td></tr><tr><td valign="top">H12714</td> <td valign="top">If the G parameter to <a href="../c3ref/open.html">sqlite3_open_v2(F,D,G,V)</a> contains thebit value <a href="../c3ref/c_open_create.html">SQLITE_OPEN_CREATE</a> and the database does notpreviously exist, then an attempt is made to create andinitialize the database.</td></tr><tr><td valign="top">H12717</td> <td valign="top">If the filename argument to <a href="../c3ref/open.html">sqlite3_open()</a>, <a href="../c3ref/open.html">sqlite3_open16()</a>,or <a href="../c3ref/open.html">sqlite3_open_v2()</a> is ":memory:", then an private,ephemeral, in-memory database is created for the connection.<font color="red">(TODO: Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE requiredin sqlite3_open_v2()?)</font></td></tr><tr><td valign="top">H12719</td> <td valign="top">If the filename is NULL or an empty string, then a private,ephemeral on-disk database will be created.<font color="red">(TODO: Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE requiredin sqlite3_open_v2()?)</font></td></tr><tr><td valign="top">H12721</td> <td valign="top">The <a href="../c3ref/sqlite3.html">database connection</a> created by <a href="../c3ref/open.html">sqlite3_open_v2(F,D,G,V)</a>will use the <a href="../c3ref/vfs.html">sqlite3_vfs</a> object identified by the V parameter,or the default <a href="../c3ref/vfs.html">sqlite3_vfs</a> object if V is a NULL pointer.</td></tr><tr><td valign="top">H12723</td> <td valign="top">Two <a href="../c3ref/sqlite3.html">database connections</a> will share a common cache if both wereopened with the same VFS while <a href="../c3ref/enable_shared_cache.html">shared cache mode</a> was enabled andif both filenames compare equal using memcmp() after having beenprocessed by the <a href="../c3ref/vfs.html">xFullPathname</a> method of the VFS.</td></tr></table></p><p>See also lists of <a href="objlist.html">Objects</a>, <a href="constlist.html">Constants</a>, and <a href="funclist.html">Functions</a>.</p><hr><small><i>This page last modified 2008/08/11 17:57:43 UTC</i></small></div></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -