Improved documentation for sqlite3_serialize() and sqlite3_deserialize().

Change the name of the compile-time option to enable these interfaces
from SQLITE_ENABLE_MEMDB to SQLITE_ENABLE_DESERIALIZE.

FossilOrigin-Name: f07e97aed435b02e1473053c0257ec5c89bf0b3e46076b7a9382de432bbc2497

diff --git a/manifest b/manifest
index 962981e679446074c08541294d420135d73c59f2..18c42ee4e285b6fe2867a30df9b494ab54f9c6f1 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Handle\ssome\sboundary\scases\sin\smemdb\sassociated\swith\sOOM\sfaults.
-D 2018-03-06T20:54:27.966
+C Improved\sdocumentation\sfor\ssqlite3_serialize()\sand\ssqlite3_deserialize().\nChange\sthe\sname\sof\sthe\scompile-time\soption\sto\senable\sthese\sinterfaces\nfrom\sSQLITE_ENABLE_MEMDB\sto\sSQLITE_ENABLE_DESERIALIZE.
+D 2018-03-06T21:43:19.244
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F Makefile.in 1d5a68043cc4d8a6e45b37e2639b148cdd7973aa75e90ec71e12d55cd95e32c0
@@ -425,7 +425,7 @@ F sqlite3.1 fc7ad8990fc8409983309bb80de8c811a7506786
 F sqlite3.pc.in 48fed132e7cb71ab676105d2a4dc77127d8c1f3a
 F src/alter.c cf7a8af45cb0ace672f47a1b29ab24092a9e8cd8d945a9974e3b5d925f548594
 F src/analyze.c 6b42e36a5dcc2703a771f2411bd5e99524bd62c7ecde209bb88dfb04c72f046e
-F src/attach.c 6a5619eaf0101b355922cb006e63458312d1067b80499e1df41cdd0ce37af99f
+F src/attach.c f6f212c43dddba79dfcb723fb9470785f3ff55bde8953cd9d2546f3022070a41
 F src/auth.c 6277d63837357549fe14e723490d6dc1a38768d71c795c5eb5c0f8a99f918f73
 F src/backup.c faf17e60b43233c214aae6a8179d24503a61e83b
 F src/bitvec.c 17ea48eff8ba979f1f5b04cc484c7bb2be632f33
@@ -453,14 +453,14 @@ F src/in-operator.md 10cd8f4bcd225a32518407c2fb2484089112fd71
 F src/insert.c 14686083cedc198540b15a79586cdd4be2acf6d5fa97627e355f817ab07e9fee
 F src/legacy.c 134ab3e3fae00a0f67a5187981d6935b24b337bcf0f4b3e5c9fa5763da95bf4e
 F src/loadext.c f6e4e416a736369f9e80eba609f0acda97148a8b0453784d670c78d3eed2f302
-F src/main.c d45d07a1c707f88cf734ec7699d9c393247f18682d748ab53065fb669231f66a
+F src/main.c c1e97e4c6fffff1fb1a6f1c48807386819af78657b4ae4acfd6d6d17353b8277
 F src/malloc.c 07295435093ce354c6d9063ac05a2eeae28bd251d2e63c48b3d67c12c76f7e18
 F src/mem0.c 6a55ebe57c46ca1a7d98da93aaa07f99f1059645
 F src/mem1.c c12a42539b1ba105e3707d0e628ad70e611040d8f5e38cf942cee30c867083de
 F src/mem2.c f1940d9e91948dd6a908fbb9ce3835c36b5d83c3
 F src/mem3.c 8768ac94694f31ffaf8b4d0ea5dc08af7010a35a
 F src/mem5.c 9bf955937b07f8c32541c8a9991f33ce3173d944
-F src/memdb.c 3f14ea29aea3a43c39b83c392016a03790692007d751320ea8c19df03bb0b393
+F src/memdb.c f5d49ef349a07df3b855885c4a0f3d8d688ca9a9c82093e9ed6a399a4826abea
 F src/memjournal.c 6f3d36a0a8f72f48f6c3c722f04301ac64f2515435fa42924293e46fc7994661
 F src/msvc.h 4942752b6a253116baaa8de75256c51a459a5e81
 F src/mutex.c b021263554c8a3995e9d53193b8194b96d1ed28e06c3b532dd7f7d29cf0c7d53
@@ -476,7 +476,7 @@ F src/os_setup.h 0dbaea40a7d36bf311613d31342e0b99e2536586
 F src/os_unix.c 928586cbde31890538854f1657463392d63b2d7794f577774573ae53ec283d7b
 F src/os_win.c eb03c6d52f893bcd7fdd4c6006674c13c1b5e49543fec98d605201af2997171c
 F src/os_win.h 7b073010f1451abe501be30d12f6bc599824944a
-F src/pager.c 0dc92667c803ed2e9566c35521bed2c53717197b011bc7b64d17cd552a241a7b
+F src/pager.c aa764a01a5548e633ea083521f48c2b128245fae1a8157a16a3490b9b9718f55
 F src/pager.h 581698f2177e8bd4008fe4760898ce20b6133d1df22139b9101b5155f900df7a
 F src/parse.y 3be4b2b5e33ef7dab3128b765898ee786fc6cd698a7f053f756a68f2f238f0aa
 F src/pcache.c 7ae91a4557a43d77d449accbfdc68846e6516f8e2eda46e8bbe4536fb669b201
@@ -491,14 +491,14 @@ F src/resolve.c 66c73fcb7719b8ff0e841b58338f13604ff3e2b50a723f9b8f383595735262f6
 F src/rowset.c 7b7e7e479212e65b723bf40128c7b36dc5afdfac
 F src/select.c f02352ac5cbb6fad3804add825743b924cfb6c742ba2e8666d726828a9985d73
 F src/shell.c.in 8c6ea9b4da9450c26551bbe7de24170e5c6c6e3af4dedaa663e3f5ef05659a96
-F src/sqlite.h.in 82eb2b02de6dda3ca9797a5a5418c8409e2aaf5b4f20530a9036722faa0cc43c
+F src/sqlite.h.in 8125abd15ff083591e53e1bc874319fbfaf239b1c57563c9685bd42723f8926a
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h 83a3c4ce93d650bedfd1aa558cb85a516bd6d094445ee989740827d0d944368d
-F src/sqliteInt.h 574a0dd6978197cc1f9b8d571744c9a30e256d29a3092050bd8a95e37c7229b9
+F src/sqliteInt.h 2ef60a6d9a50e6eef224e9eae71b29a9fb91c301e882d9fbbb77afd50b6cf815
 F src/sqliteLimit.h 1513bfb7b20378aa0041e7022d04acb73525de35b80b252f1b83fedb4de6a76b
 F src/status.c 9737ed017279a9e0c5da748701c3c7bf1e8ae0dae459aad20dd64fcff97a7e35
 F src/table.c b46ad567748f24a326d9de40e5b9659f96ffff34
-F src/tclsqlite.c d05dde2bb9534ee39a5095c4c4a43625997e0f3ab6889b55e76393b05b6895b1
+F src/tclsqlite.c 3c3e085e02edf4c416792050d288944fd0fad3f7b283a81fa45241a633d78c80
 F src/test1.c 1ab7cbbb6693e08364c1a9241e2aee17f8c4925e4cc52396be77ae6845a05828
 F src/test2.c 3efb99ab7f1fc8d154933e02ae1378bac9637da5
 F src/test3.c b8434949dfb8aff8dfa082c8b592109e77844c2135ed3c492113839b6956255b
@@ -514,7 +514,7 @@ F src/test_backup.c bf5da90c9926df0a4b941f2d92825a01bbe090a0
 F src/test_bestindex.c 78809f11026f18a93fcfd798d9479cba37e1201c830260bf1edc674b2fa9b857
 F src/test_blob.c ae4a0620b478548afb67963095a7417cd06a4ec0a56adb453542203bfdcb31ce
 F src/test_btree.c 8b2dc8b8848cf3a4db93f11578f075e82252a274
-F src/test_config.c 09bd69f7e59bad08b67dd7bd8e7de6d992f1a668466b4500c870139fe1792126
+F src/test_config.c 097c6189803886a1fb26ec37d8bc62b90512cb53ab79a1fb6d35196c1ec42ded
 F src/test_delete.c e2fe07646dff6300b48d49b2fee2fe192ed389e834dd635e3b3bac0ce0bf9f8f
 F src/test_demovfs.c a0c3bdd45ed044115c2c9f7779e56eafff18741e
 F src/test_devsym.c 1960abbb234b97e9b920f07e99503fc04b443f62bbc3c6ff2c2cea2133e3b8a2
@@ -1067,7 +1067,7 @@ F test/malloc_common.tcl aac62499b76be719fac31e7a3e54a7fd53272e7f
 F test/manydb.test 28385ae2087967aa05c38624cec7d96ec74feb3e
 F test/mem5.test c6460fba403c5703141348cd90de1c294188c68f
 F test/memdb.test c1f2a343ad14398d5d6debda6ea33e80d0dafcc7
-F test/memdb1.test 526252d466ecc3701550000651e1405d08ccefe0bf23e2dc86ada90e81a8eacc
+F test/memdb1.test fbe47f36c12725ebdd2760f846371e6eb09f403bd7236fbdddb21aa6e3c652b4
 F test/memleak.test 10b9c6c57e19fc68c32941495e9ba1c50123f6e2
 F test/memsubsys1.test 9e7555a22173b8f1c96c281ce289b338fcba2abe8b157f8798ca195bbf1d347e
 F test/memsubsys2.test 3e4a8d0c05fd3e5fa92017c64666730a520c7e08
@@ -1710,7 +1710,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 6c3f723a6856fa38ea3f11a36b56f46c5c1fcf17f4daf712e5e0b42562d5f4c6
-R 93b06b41fb0db58473fe3890ab6bb440
+P b58ca4cb0c921e81efad527c80b220be120263cfdb04528ae26ecf8b8f66f44a
+R 8d936538e4c856e0f588396347b85dcc
 U drh
-Z f2d702ac0939e1489f368e13dd72bca2
+Z c61ba7a8db0957766315d0dc5cf0b993

diff --git a/manifest.uuid b/manifest.uuid
index fb3d8af9ee49149ba10c07c527479f7043c1c42b..6fe0b07e1fcee561643857f4799d8c6df27f772b 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-b58ca4cb0c921e81efad527c80b220be120263cfdb04528ae26ecf8b8f66f44a
\ No newline at end of file
+f07e97aed435b02e1473053c0257ec5c89bf0b3e46076b7a9382de432bbc2497
\ No newline at end of file

diff --git a/src/attach.c b/src/attach.c
index 09bd02be89a79d7adbb70e66c55380c9cf53dd4e..f85952f7c6b5d6c31556d3f124e0858ebc244d05 100644 (file)
--- a/src/attach.c
+++ b/src/attach.c
@@ -84,7 +84,7 @@ static void attachFunc(
   if( zFile==0 ) zFile = "";
   if( zName==0 ) zName = "";
 
-#ifdef SQLITE_ENABLE_MEMDB
+#ifdef SQLITE_ENABLE_DESERIALIZE
 # define REOPEN_AS_MEMDB(db)  (db->init.reopenMemdb)
 #else
 # define REOPEN_AS_MEMDB(db)  (0)

diff --git a/src/main.c b/src/main.c
index 2fef116868ba04a71f751bd1052e9722a2e5215b..af93a011e38e646c683e6d53b1c06334969356c1 100644 (file)
--- a/src/main.c
+++ b/src/main.c
@@ -239,7 +239,7 @@ int sqlite3_initialize(void){
       sqlite3GlobalConfig.isPCacheInit = 1;
       rc = sqlite3OsInit();
     }
-#ifdef SQLITE_ENABLE_MEMDB
+#ifdef SQLITE_ENABLE_DESERIALIZE
     if( rc==SQLITE_OK ){
       rc = sqlite3MemdbInit();
     }

diff --git a/src/memdb.c b/src/memdb.c
index 88eaaba4eef4131a72e4c01dd33690ea7285211d..646f788febcdd326daef134546f2ec12d3339327 100644 (file)
--- a/src/memdb.c
+++ b/src/memdb.c
@@ -16,7 +16,7 @@
 ** This file also implements interface sqlite3_serialize() and
 ** sqlite3_deserialize().
 */
-#ifdef SQLITE_ENABLE_MEMDB
+#ifdef SQLITE_ENABLE_DESERIALIZE
 #include "sqliteInt.h"
 
 /*
@@ -568,4 +568,4 @@ int sqlite3MemdbInit(void){
   memdb_vfs.szOsFile = sz;
   return sqlite3_vfs_register(&memdb_vfs, 0);
 }
-#endif /* SQLITE_ENABLE_MEMDB */
+#endif /* SQLITE_ENABLE_DESERIALIZE */

diff --git a/src/pager.c b/src/pager.c
index 175c94ddd8fce5f8155b30ad92fe6162dffde6c3..f4ac88c206be77c3bac8b7e919e70494c2e34395 100644 (file)
--- a/src/pager.c
+++ b/src/pager.c
@@ -4723,7 +4723,11 @@ int sqlite3PagerOpen(
   int rc = SQLITE_OK;      /* Return code */
   int tempFile = 0;        /* True for temp files (incl. in-memory files) */
   int memDb = 0;           /* True if this is an in-memory file */
+#ifdef SQLITE_ENABLE_DESERIALIZE
   int memJM = 0;           /* Memory journal mode */
+#else
+# define memJM 0
+#endif
   int readOnly = 0;        /* True if this is a read-only file */
   int journalFileSize;     /* Bytes to allocate for each journal fd */
   char *zPathname = 0;     /* Full path to database file */
@@ -4851,7 +4855,9 @@ int sqlite3PagerOpen(
     int fout = 0;                    /* VFS flags returned by xOpen() */
     rc = sqlite3OsOpen(pVfs, pPager->zFilename, pPager->fd, vfsFlags, &fout);
     assert( !memDb );
+#ifdef SQLITE_ENABLE_DESERIALIZE
     memJM = (fout&SQLITE_OPEN_MEMORY)!=0;
+#endif
     readOnly = (fout&SQLITE_OPEN_READONLY)!=0;
 
     /* If the file was successfully opened for read/write access,

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 75a96d50d6fdc0a27aaeaf8551eeac326229500d..4e7939ebda8cd05676282d29d0d3a2d74b3d3f4b 100644 (file)
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -8762,6 +8762,9 @@ SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
 ** A call to sqlite3_serialize(D,S,P,F) might return NULL even if the
 ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
 ** allocation error occurs.
+**
+** This interface is only available if SQLite is compiled with the
+** [SQLITE_ENABLE_DESERIALIZE] option.
 */
 unsigned char *sqlite3_serialize(
   sqlite3 *db,           /* The database connection */
@@ -8773,6 +8776,17 @@ unsigned char *sqlite3_serialize(
 /*
 ** CAPI3REF: Flags for sqlite3_serialize
 ** EXPERIMENTAL
+**
+** Zero or more of the following constants can be OR-ed together for
+** the F argument to [sqlite3_serialize(D,S,P,F)].
+**
+** SQLITE_SERIALIZE_NOCOPY means that [sqlite3_serialize()] will return
+** a pointer to contiguous in-memory database that it is currently using,
+** without making a copy of the database.  If SQLite is not currently using
+** a contiguous in-memory database, then this option causes
+** [sqlite3_serialize()] to return a NULL pointer.  SQLite will only be
+** using a contiguous in-memory database if it has been initialized by a
+** prior call to [sqlite3_deserialize()].
 */
 #define SQLITE_SERIALIZE_NOCOPY 0x001   /* Do no memory allocations */
 
@@ -8802,6 +8816,9 @@ unsigned char *sqlite3_serialize(
 ** If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the 
 ** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
 ** [sqlite3_free()] is invoked on argument P prior to returning.
+**
+** This interface is only available if SQLite is compiled with the
+** [SQLITE_ENABLE_DESERIALIZE] option.
 */
 int sqlite3_deserialize(
   sqlite3 *db,            /* The database connection */
@@ -8816,8 +8833,23 @@ int sqlite3_deserialize(
 ** CAPI3REF: Flags for sqlite3_deserialize()
 ** EXPERIMENTAL
 **
-** The following are allowed values for the 6th argument (the "flags" or "F"
-** argument) of the [sqlite3_deserialize()] interface.
+** The following are allowed values for 6th argument (the F argument) to
+** the [sqlite3_deserialize(D,S,P,N,M,F)] interface.
+**
+** The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization
+** in the P argument is held in memory obtained from [sqlite3_malloc64()]
+** and that SQLite should take ownership of this memory and automatically
+** free it when it has finished using it.  Without this flag, the caller
+** is resposible for freeing any dynamically allocated memory.
+**
+** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
+** grow the size of the database usign calls to [sqlite3_realloc64()].  This
+** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.
+** Without this flag, the deserialized database cannot increase in size beyond
+** the number of bytes specified by the M parameter.
+**
+** The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database
+** should be treated as read-only.
 */
 #define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */
 #define SQLITE_DESERIALIZE_RESIZEABLE  2 /* Resize using sqlite3_realloc64() */

diff --git a/src/sqliteInt.h b/src/sqliteInt.h
index 341cfe97a62c193595bce168c3479bbc2c728951..3f34f48e15e2d2130f91b2a520cbf3d2e36a1888 100644 (file)
--- a/src/sqliteInt.h
+++ b/src/sqliteInt.h
@@ -4024,7 +4024,7 @@ int sqlite3TwoPartName(Parse *, Token *, Token *, Token **);
 const char *sqlite3ErrName(int);
 #endif
 
-#ifdef SQLITE_ENABLE_MEMDB
+#ifdef SQLITE_ENABLE_DESERIALIZE
 int sqlite3MemdbInit(void);
 #endif
 

diff --git a/src/tclsqlite.c b/src/tclsqlite.c
index 878cdd961d045c284b808ecdf48075e8315f43ed..285fbbda2ef0c18976e384cec1ae89341e132d8e 100644 (file)
--- a/src/tclsqlite.c
+++ b/src/tclsqlite.c
@@ -2420,7 +2420,7 @@ static int SQLITE_TCLAPI DbObjCmd(
   ** Reopen DATABASE (default "main") using the content in $VALUE
   */
   case DB_DESERIALIZE: {
-#ifndef SQLITE_ENABLE_MEMDB
+#ifndef SQLITE_ENABLE_DESERIALIZE
     Tcl_AppendResult(interp, "MEMDB not available in this build",
                      (char*)0);
     rc = TCL_ERROR;
@@ -2942,7 +2942,7 @@ static int SQLITE_TCLAPI DbObjCmd(
   ** Return a serialization of a database.  
   */
   case DB_SERIALIZE: {
-#ifndef SQLITE_ENABLE_MEMDB
+#ifndef SQLITE_ENABLE_DESERIALIZE
     Tcl_AppendResult(interp, "MEMDB not available in this build",
                      (char*)0);
     rc = TCL_ERROR;

diff --git a/src/test_config.c b/src/test_config.c
index de693850d37aff3e81be6ceb14eddcd99b7442f0..aa0626ab2da8b7e541073f8d9da8201637abe0e2 100644 (file)
--- a/src/test_config.c
+++ b/src/test_config.c
@@ -148,10 +148,10 @@ static void set_options(Tcl_Interp *interp){
   Tcl_SetVar2(interp, "sqlite_options", "hiddencolumns", "0", TCL_GLOBAL_ONLY);
 #endif
 
-#ifdef SQLITE_ENABLE_MEMDB
-  Tcl_SetVar2(interp, "sqlite_options", "memdb", "1", TCL_GLOBAL_ONLY);
+#ifdef SQLITE_ENABLE_DESERIALIZE
+  Tcl_SetVar2(interp, "sqlite_options", "deserialize", "1", TCL_GLOBAL_ONLY);
 #else
-  Tcl_SetVar2(interp, "sqlite_options", "memdb", "0", TCL_GLOBAL_ONLY);
+  Tcl_SetVar2(interp, "sqlite_options", "deserialize", "0", TCL_GLOBAL_ONLY);
 #endif
 
 #ifdef SQLITE_ENABLE_MEMSYS3

diff --git a/test/memdb1.test b/test/memdb1.test
index 48f9fca5ec28a3d64492611cc21d73378ef6a34c..b52517fcf3efb522028a6e56418bc32305d640f9 100644 (file)
--- a/test/memdb1.test
+++ b/test/memdb1.test
@@ -17,7 +17,7 @@ source $testdir/tester.tcl
 set testprefix memdb1
 do_not_use_codec
 
-ifcapable !memdb {
+ifcapable !deserialize {
   finish_test
   return
 }