From: drh Date: Tue, 6 Mar 2018 21:43:19 +0000 (+0000) Subject: Improved documentation for sqlite3_serialize() and sqlite3_deserialize(). X-Git-Tag: version-3.23.0~85^2~1 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=9c6396ecc788531b166dcbba833ab65a39abf501;p=thirdparty%2Fsqlite.git 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 962981e679..18c42ee4e2 100644 --- 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 fb3d8af9ee..6fe0b07e1f 100644 --- 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 09bd02be89..f85952f7c6 100644 --- 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 2fef116868..af93a011e3 100644 --- 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 88eaaba4ee..646f788feb 100644 --- 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 175c94ddd8..f4ac88c206 100644 --- 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 75a96d50d6..4e7939ebda 100644 --- 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 341cfe97a6..3f34f48e15 100644 --- 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 878cdd961d..285fbbda2e 100644 --- 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 de693850d3..aa0626ab2d 100644 --- 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 48f9fca5ec..b52517fcf3 100644 --- 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 }