Updates to the sqlite3_open() documentation. Method the magic

:memory: filename.  Ticket #2591. (CVS 4311)

FossilOrigin-Name: 5f55b2fc4ecdfc1bb68f479751b8642926fd8833

manifest

@@ -1,5 +1,5 @@
-C Update\sthe\ssqlite3_vfs_register()\sdocumentation\sto\smake\r\nthe\sbehavior\sundefined\sfor\sVFSes\swith\sa\sNULL\sor\sempty\sstring\r\nas\sthe\sname\sor\swith\sduplicate\snames.\s(CVS\s4310)
-D 2007-08-28T15:21:45
+C Updates\sto\sthe\ssqlite3_open()\sdocumentation.\s\sMethod\sthe\smagic\n:memory:\sfilename.\s\sTicket\s#2591.\s(CVS\s4311)
+D 2007-08-28T15:47:45
 F Makefile.in e8296e112b8942a96c0ed504398bd0d43e3c67ce
 F Makefile.linux-gcc 65241babba6faf1152bf86574477baab19190499
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -126,7 +126,7 @@ F src/random.c 4a22746501bf36b0a088c66e38dde5daba6a35da
 F src/select.c 98c367bce3f38c5adfcc97de9ab5c79b0e5dc2b2
 F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96
 F src/shell.c ac29402b538515fa4697282387be9c1205e6e9eb
-F src/sqlite.h.in da8b9380c32ad72cca3deb25ef43ed5707b6b6bd
+F src/sqlite.h.in 679cfc7927f843cd30a7b7a0fa17173752939a36
 F src/sqlite3ext.h 9a26028378c288af500d8b94ed079666fed5806b
 F src/sqliteInt.h e681df44a19ffb6750d129802f124132ae240c83
 F src/sqliteLimit.h 1bcbbdfa856f8b71b561abb31edb864b0eca1d12
@@ -563,7 +563,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P 4c5631ce347a25dd6df90e7e4395a55cd750c1c9
-R 3046317a55b31ec340f798a75ee5fd0a
+P e7a98b48384ea581d98dad5118ee33468d526c62
+R 79b1204662164ac9dfde3b22f0e8e0d8
 U drh
-Z 4d0250ba3b6ebc171f9648b0cd34f1b0
+Z 512659d0af1bbd911b2ca09d7e649b66

manifest.uuid

@@ -1 +1 @@
-e7a98b48384ea581d98dad5118ee33468d526c62
+5f55b2fc4ecdfc1bb68f479751b8642926fd8833

src/sqlite.h.in

@@ -30,7 +30,7 @@
 ** the version number) and changes its name to "sqlite3.h" as
 ** part of the build process.
 **
-** @(#) $Id: sqlite.h.in,v 1.245 2007/08/28 15:21:45 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.246 2007/08/28 15:47:45 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -1327,22 +1327,23 @@ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
 ** CAPI3REF: Opening A New Database Connection
 **
 ** Open the sqlite database file "filename".  The "filename" is UTF-8
-** encoded for sqlite3_open() and UTF-16 encoded in the native byte order
-** for sqlite3_open16().  An [sqlite3*] handle is returned in *ppDb, even
+** encoded for [sqlite3_open()] and [sqlite3_open_v2()] and UTF-16 encoded
+** in the native byte order for [sqlite3_open16()].
+** An [sqlite3*] handle is returned in *ppDb, even
 ** if an error occurs. If the database is opened (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.
 **
-** If the database file does not exist, then a new database will be created
-** as needed.  The default encoding for the database will be UTF-8 if
-** sqlite3_open() is called and UTF-16 if sqlite3_open16 is used.
+** The default encoding for the database will be UTF-8 if
+** [sqlite3_open()] or [sqlite3_open_v2()] is called and
+** UTF-16 if [sqlite3_open16()] is used.
 **
 ** Whether or not an error occurs when it is opened, resources associated
 ** with the [sqlite3*] handle should be released by passing it to
 ** [sqlite3_close()] when it is no longer required.
 **
-** The sqlite3_open_v2() interface works like sqlite3_open() except that
+** The [sqlite3_open_v2()] interface works like [sqlite3_open()] except that
 ** provides two additional parameters for additional control over the
 ** new database connection.  The flags parameter can be one of:
 **
@@ -1354,22 +1355,33 @@ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
 **
 ** The first value opens the database read-only.  If the database does
 ** not previously exist, an error is returned.  The second option opens
-** the database for reading and writing but the database must already
+** the database for reading and writing if possible, or reading only if
+** if the file is write protected.  In either case the database must already
 ** exist or an error is returned.  The third option opens the database
 ** for reading and writing and creates it if it does not already exist.
-** The third options is behavior that is used always for sqlite3_open()
-** and sqlite3_open16().
+** The third options is behavior that is always used for [sqlite3_open()]
+** and [sqlite3_open16()].
+**
+** If the filename is ":memory:" or an empty string, then an private
+** in-memory database is created for the connection.  This in-memory
+** database will vanish when the database connection is closed.  Future
+** version of SQLite might make use of additional special filenames
+** that begin with the ":" character.  It is recommended that 
+** when a database filename really does begin with
+** ":" that you prefix the filename with a pathname like "./" to
+** avoid ambiguity.
 **
 ** 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 a default suitable for
-** the host environment is substituted.
+** fourth parameter is a NULL pointer then the default [sqlite3_vfs]
+** object is used.
 **
-** Note to windows users:  The encoding used for the filename argument
-** of sqlite3_open() 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().
+** <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()].
 */
 int sqlite3_open(
   const char *filename,   /* Database filename (UTF-8) */