Initial implementation of the sqlite3_file_control() interface.

Compiles and passes all historical tests but the new method is itself
untested. (CVS 4353)

FossilOrigin-Name: d3ab3e3911f10b17d0859a34f4f007c790a0cd82

manifest

@@ -1,5 +1,5 @@
-C Convert\sthe\sTCL\sinterface\sto\suse\ssqlite3_open_v2\s(CVS\s4352)
+C Initial\simplementation\sof\sthe\ssqlite3_file_control()\sinterface.\nCompiles\sand\spasses\sall\shistorical\stests\sbut\sthe\snew\smethod\sis\sitself\nuntested.\s(CVS\s4353)
-D 2007-08-31T14:31:45
+D 2007-08-31T16:11:36
 F Makefile.in bfcc303429a5d9dcd552d807ee016c77427418c3
 F Makefile.linux-gcc 65241babba6faf1152bf86574477baab19190499
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -98,8 +98,8 @@ F src/insert.c b11e5ca0d68bf2a7a56f47a052a0ee67dd4e2f89
 F src/journal.c 573911e274738b3fda813d4f0a6e319f8a9ecd36
 F src/legacy.c 4ac53191fad2e3c4d59bde1228879b2dc5a96d66
 F src/limits.h 71ab25f17e35e0a9f3f6f234b8ed49cc56731d35
-F src/loadext.c 9e6bbbc0955c882a2ef11c88d6a0896d2e7b02a4
+F src/loadext.c d8a41422b7c2a79d4cf89a62da404d6b786704cf
-F src/main.c 80ebc68e5a270e55b06b233ac475b6c56b11ec17
+F src/main.c 00a894cd348d8d3651097bb8136f03e53afa644b
 F src/malloc.c de4e77fe70a9a0ac47a1c3a874422b107231bf31
 F src/md5.c c5fdfa5c2593eaee2e32a5ce6c6927c986eaf217
 F src/mem1.c afe2fbf6d7e8247c6c9f69c1481358b1cad60c08
@@ -109,19 +109,19 @@ F src/mutex.h 079fa6fe9da18ceb89e79012c010594c6672addb
 F src/mutex_os2.c d47e9bd495583dd31263d8fe55160a31eb600a3c
 F src/mutex_unix.c ff77650261a245035b79c5c8a174f4e05d3cae8a
 F src/mutex_w32.c 54beb16ade8f80ea2bc30bc4dfb2087be3487ef3
-F src/os.c a8ed3c495161475dbce255f7003144144fb425f1
+F src/os.c 8e6ffe83863341b744c426254b3430b756a5115d
-F src/os.h 2bfbbad126a775e4d8c7d59eb4d9585a5fd7dfb5
+F src/os.h efcdddd63d172857d9d769d56a0a0f161ac573dd
 F src/os_common.h 98862f120ca6bf7a48ce8b16f158b77d00bc9d2f
 F src/os_os2.c 8769301bff502de642ad2634cedcb77d967ce199
 F src/os_os2.h c3f7d0af7e3453d1d7aa81b06c0a56f5a226530b
 F src/os_test.c 49833426101f99aee4bb5f6a44b7c4b2029fda1c
 F src/os_test.h 903c93554c23d88f34f667f1979e4a1cee792af3
-F src/os_unix.c 84dcfc01006ae0b4f8e16cf094de4bdaf7ddf1a8
+F src/os_unix.c 5c8fd11fa182b66f7e4f28ac0594e4092535551a
 F src/os_unix.h 5768d56d28240d3fe4537fac08cc85e4fb52279e
-F src/os_win.c 85e5661c852492e6bda9e79542932d7edf0e2177
+F src/os_win.c d8f9a643bbf627380bdc7166cbf70a06d115d2db
 F src/os_win.h 41a946bea10f61c158ce8645e7646b29d44f122b
-F src/pager.c 847674a74c232f3f7c386d4b902df41a60f781c4
+F src/pager.c 0c5fd990734174566ec6d67aebbdc3144f0f67fb
-F src/pager.h 1ac4468049348ec72df09d138fc1d7e3a9d0d3a6
+F src/pager.h 80fcf5218fdd46baee07ba8ad899a2da15671014
 F src/parse.y 2d2ce439dc6184621fb0b86f4fc5aca7f391a590
 F src/pragma.c 59a5e12ad0972ca2403503c12efb77f208c9a144
 F src/prepare.c 1506fd279824b1f4bac97514966d0370101f9a6b
@@ -130,8 +130,8 @@ F src/random.c 4a22746501bf36b0a088c66e38dde5daba6a35da
 F src/select.c e5cc50e8d22b2490c4fb47f2ef08a9b43bcb52d9
 F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96
 F src/shell.c ac29402b538515fa4697282387be9c1205e6e9eb
-F src/sqlite.h.in b4cca54d8c3aa61c033dcb0d48f11ebcdb354627
+F src/sqlite.h.in fa367ce8e8a9b50eb65189788bad12e6240c82bb
-F src/sqlite3ext.h 3e5368b64a28602ef8abf9cfb6c8c1643903f238
+F src/sqlite3ext.h a93f59cdee3638dc0c9c086f80df743a4e68c3cb
 F src/sqliteInt.h 5dbb7a934a88dfa9893e2627f4821b0464f5edc0
 F src/sqliteLimit.h 1bcbbdfa856f8b71b561abb31edb864b0eca1d12
 F src/table.c 1aeb9eab57b4235db86fe15a35dec76fb445a9c4
@@ -141,7 +141,7 @@ F src/test2.c 4ab230fbdc0decfa7422f6a052b609ba54f4dfac
 F src/test3.c 199a440ba2b38b26251393b609451a3484a15907
 F src/test4.c c2c0f5dc907f1346f5d4b65eb5799f11eb9e4071
 F src/test5.c 3a6a5717a149d7ca2e6d14f5be72cf7555d54dc4
-F src/test6.c a6223d9d938aba83f20611a2c01680d8043cd2f7
+F src/test6.c a3480a6e7dafc8b18af59221063bf90a7bfa1990
 F src/test7.c a9d509d0e9ad214b4772696f49f6e61be26213d1
 F src/test8.c 88e033aefdf5d5522dff46655a14ea7360fb1d26
 F src/test9.c b46c8fe02ac7cca1a7316436d8d38d50c66f4b2f
@@ -568,7 +568,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P ee9b3e5e38c52f5669009a08aec58678ccad0d87
+P 3434b7a9213f210498f43cb5094a0f3f5c25b957
-R b9ef3977fd4686cc6e05c610911a5a80
+R e134a1f025d06e94c6b0a8b3051d2ea3
 U drh
-Z edb6e93aa3250c0879e9ae9ba46c5a0f
+Z 292d7d222b18b61dd3924bd523487d55

manifest.uuid

@@ -1 +1 @@
-3434b7a9213f210498f43cb5094a0f3f5c25b957
+d3ab3e3911f10b17d0859a34f4f007c790a0cd82

src/loadext.c

@@ -256,6 +256,7 @@ const sqlite3_api_routines sqlite3_apis = {
   sqlite3_blob_read,
   sqlite3_blob_write,
   sqlite3_create_collation_v2,
+  sqlite3_file_control,
   sqlite3_memory_highwater,
   sqlite3_memory_used,
 #ifdef SQLITE_MUTEX_NOOP

src/main.c

@@ -14,7 +14,7 @@
 ** other files are for internal use by SQLite and should not be
 ** accessed by users of the library.
 **
-** $Id: main.c,v 1.400 2007/08/30 20:09:48 drh Exp $
+** $Id: main.c,v 1.401 2007/08/31 16:11:36 drh Exp $
 */
 #include "sqliteInt.h"
 #include <ctype.h>
@@ -1432,3 +1432,36 @@ int sqlite3_extended_result_codes(sqlite3 *db, int onoff){
   sqlite3_mutex_leave(db->mutex);
   return SQLITE_OK;
 }
+
+/*
+** Invoke the xFileControl method on a particular database.
+*/
+int sqlite3_file_control(sqlite3 *db, const char *zDbName, int op, void *pArg){
+  int rc = SQLITE_ERROR;
+  int iDb;
+  sqlite3_mutex_enter(db->mutex);
+  if( zDbName==0 ){
+    iDb = 0;
+  }else{
+    for(iDb=0; iDb<db->nDb; iDb++){
+      if( strcmp(db->aDb[iDb].zName, zDbName)==0 ) break;
+    }
+  }
+  if( iDb<db->nDb ){
+    Btree *pBtree = db->aDb[iDb].pBt;
+    if( pBtree ){
+      Pager *pPager;
+      sqlite3BtreeEnter(pBtree);
+      pPager = sqlite3BtreePager(pBtree);
+      if( pPager ){
+        sqlite3_file *fd = sqlite3PagerFile(pPager);
+        if( fd ){
+          rc = sqlite3OsFileControl(fd, op, pArg);
+        }
+      }
+      sqlite3BtreeLeave(pBtree);
+    }
+  }
+  sqlite3_mutex_leave(db->mutex);
+  return rc;   
+}

src/os.c

@@ -52,12 +52,12 @@ int sqlite3OsLock(sqlite3_file *id, int lockType){
 int sqlite3OsUnlock(sqlite3_file *id, int lockType){
   return id->pMethods->xUnlock(id, lockType);
 }
-int sqlite3OsBreakLock(sqlite3_file *id){
-  return id->pMethods->xBreakLock(id);
-}
 int sqlite3OsCheckReservedLock(sqlite3_file *id){
   return id->pMethods->xCheckReservedLock(id);
 }
+int sqlite3OsFileControl(sqlite3_file *id, int op, void *pArg){
+  return id->pMethods->xFileControl(id,op,pArg);
+}
 
 #ifdef SQLITE_TEST
   /* The following two variables are used to override the values returned

src/os.h

@@ -239,9 +239,9 @@ int sqlite3OsSync(sqlite3_file*, int);
 int sqlite3OsFileSize(sqlite3_file*, i64 *pSize);
 int sqlite3OsLock(sqlite3_file*, int);
 int sqlite3OsUnlock(sqlite3_file*, int);
-int sqlite3OsBreakLock(sqlite3_file*);
 int sqlite3OsCheckReservedLock(sqlite3_file *id);
 int sqlite3OsLockState(sqlite3_file *id);
+int sqlite3OsFileControl(sqlite3_file*,int,void*);
 int sqlite3OsSectorSize(sqlite3_file *id);
 int sqlite3OsDeviceCharacteristics(sqlite3_file *id);
 

src/os_unix.c

@@ -2016,11 +2016,10 @@ static int nolockUnixClose(sqlite3_file *id) {
 
 
 /*
-** TODO: xBreakLock() for this vfs.
+** No xFileControl opcodes are implemented by this VFS.
 */
-static int unixBreakLock(sqlite3_file *id){
+static int unixFileControl(sqlite3_file *id, int op, void *pArg){
-  assert(!"TODO: unixBreakLock()");
+  return SQLITE_ERROR;
-  return 0;
 }
 
 /*
@@ -2067,8 +2066,8 @@ static const sqlite3_io_methods sqlite3UnixIoMethod = {
   unixLock,
   unixUnlock,
   unixCheckReservedLock,
-  unixBreakLock,
   unixLockState,
+  unixFileControl,
   unixSectorSize,
   unixDeviceCharacteristics
 };
@@ -2089,8 +2088,8 @@ static const sqlite3_io_methods sqlite3AFPLockingUnixIoMethod = {
   afpUnixLock,
   afpUnixUnlock,
   afpUnixCheckReservedLock,
-  unixBreakLock,
   unixLockState,
+  unixFileControl,
   unixSectorSize,
   unixDeviceCharacteristics
 };
@@ -2110,8 +2109,8 @@ static const sqlite3_io_methods sqlite3FlockLockingUnixIoMethod = {
   flockUnixLock,
   flockUnixUnlock,
   flockUnixCheckReservedLock,
-  unixBreakLock,
   unixLockState,
+  unixFileControl,
   unixSectorSize,
   unixDeviceCharacteristics
 };
@@ -2131,8 +2130,8 @@ static const sqlite3_io_methods sqlite3DotlockLockingUnixIoMethod = {
   dotlockUnixLock,
   dotlockUnixUnlock,
   dotlockUnixCheckReservedLock,
-  unixBreakLock,
   unixLockState,
+  unixFileControl,
   unixSectorSize,
   unixDeviceCharacteristics
 };
@@ -2152,8 +2151,8 @@ static const sqlite3_io_methods sqlite3NolockLockingUnixIoMethod = {
   nolockUnixLock,
   nolockUnixUnlock,
   nolockUnixCheckReservedLock,
-  unixBreakLock,
   unixLockState,
+  unixFileControl,
   unixSectorSize,
   unixDeviceCharacteristics
 };

src/os_win.c

@@ -977,9 +977,9 @@ static int winUnlock(sqlite3_file *id, int locktype){
 }
 
 /*
-** Currently unimplemented
+** No xFileControl operations are currently implemented.
 */
-static int winBreakLock(sqlite3_file *id){
+static int winFileControl(sqlite3_file *id){
   return SQLITE_ERROR;
 }
 
@@ -1028,8 +1028,8 @@ static const sqlite3_io_methods winIoMethod = {
   winLock,
   winUnlock,
   winCheckReservedLock,
-  winBreakLock,
   winLockState,
+  winFileControl,
   winSectorSize,
   winDeviceCharacteristics
 };

src/pager.c

@@ -18,7 +18,7 @@
 ** file simultaneously, or one process from reading the database while
 ** another is writing.
 **
-** @(#) $Id: pager.c,v 1.381 2007/08/30 08:08:17 danielk1977 Exp $
+** @(#) $Id: pager.c,v 1.382 2007/08/31 16:11:36 drh Exp $
 */
 #ifndef SQLITE_OMIT_DISKIO
 #include "sqliteInt.h"
@@ -4822,6 +4822,15 @@ const sqlite3_vfs *sqlite3PagerVfs(Pager *pPager){
   return pPager->pVfs;
 }
 
+/*
+** Return the file handle for the database file associated
+** with the pager.  This might return NULL if the file has
+** not yet been opened.
+*/
+sqlite3_file *sqlite3PagerFile(Pager *pPager){
+  return pPager->fd;
+}
+
 /*
 ** Return the directory of the database file.
 */

src/pager.h

@@ -13,7 +13,7 @@
 ** subsystem.  The page cache subsystem reads and writes a file a page
 ** at a time and provides a journal for rollback.
 **
-** @(#) $Id: pager.h,v 1.64 2007/08/29 12:31:27 danielk1977 Exp $
+** @(#) $Id: pager.h,v 1.65 2007/08/31 16:11:36 drh Exp $
 */
 
 #ifndef _PAGER_H_
@@ -86,6 +86,7 @@ int sqlite3PagerRefcount(Pager*);
 void sqlite3PagerSetSafetyLevel(Pager*,int,int);
 const char *sqlite3PagerFilename(Pager*);
 const sqlite3_vfs *sqlite3PagerVfs(Pager*);
+sqlite3_file *sqlite3PagerFile(Pager*);
 const char *sqlite3PagerDirname(Pager*);
 const char *sqlite3PagerJournalname(Pager*);
 int sqlite3PagerNosync(Pager*);

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.251 2007/08/30 20:09:48 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.252 2007/08/31 16:11:36 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -472,9 +472,20 @@ struct sqlite3_file {
 ** PENDING, or EXCLUSIVE lock on the file.  It returns true
 ** if such a lock exists and false if not.
 ** 
-** xBreakLock() attempts to break a lock held by another process.
+** The xFileControl() method is a generic interface that allows custom
-** This can be used to remove a stale dot-file lock, for example.
+** VFS implementations to directly control an open file using the
-** It returns 0 on success and non-zero for a failure.
+** [sqlite3_file_control()] interface.  The second argument (the
+** "op" argument) is intended to be an integer opcode.  The third
+** argument is a generic pointer which is intended to be a pointer
+** to a structure that may contain arguments or space in which to
+** write return values.  Potential uses for xFileControl() might be
+** functions to enable blocking locks with timeouts, to change the
+** locking strategy (for example to use dot-file locks), to inquire
+** about the status of a lock, or to break stale locks.  No standard
+** xFileControl opcodes are currently defined, but this may change in 
+** future releases.  Applications that define a custom xFileControl
+** method should use opcodes greater than 100 to avoid conflicts
+** with future official opcodes which will be less than that value.
 **
 ** The xSectorSize() method returns the sector size of the
 ** device that underlies the file.  The sector size is the
@@ -520,8 +531,8 @@ struct sqlite3_io_methods {
   int (*xLock)(sqlite3_file*, int);
   int (*xUnlock)(sqlite3_file*, int);
   int (*xCheckReservedLock)(sqlite3_file*);
-  int (*xBreakLock)(sqlite3_file*);
   int (*xLockState)(sqlite3_file *);
+  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
   int (*xSectorSize)(sqlite3_file*);
   int (*xDeviceCharacteristics)(sqlite3_file*);
   /* Additional methods may be added in future releases */
@@ -3438,6 +3449,29 @@ int sqlite3_mutex_notheld(sqlite3_mutex*);
 #define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_random() */
 #define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */
 
+/*
+** CAPI3REF: Low-Level Control Of Database Files
+**
+** The [sqlite3_file_control()] interface makes a direct call to the
+** xFileControl method for the [sqlite3_io_methods] object associated
+** with a particular database identified by the second argument.  The
+** name of the database is the name assigned to the database by the
+** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
+** database.  To control the main database file, use the name "main"
+** or a NULL pointer.  The third and fourth parameters to this routine
+** are passed directly through to the second and third parameters of
+** the xFileControl method.  The return value of the xFileControl
+** method becomes the return value of this routine.
+**
+** If the second parameter (zDbName) does not match the name of any
+** open database file, then SQLITE_ERROR is returned.  This error
+** code is not remembered and will not be recalled by [sqlite3_errcode()]
+** or [sqlite3_errmsg()].  The underlying xFileControl method might
+** also return SQLITE_ERROR.  There is no way to distinguish between
+** an incorrect zDbName and an SQLITE_ERROR return from the underlying
+** xFileControl method.
+*/
+int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
 
 /*
 ** Undo the hack that converts floating point types to integer for

src/sqlite3ext.h

@@ -15,7 +15,7 @@
 ** as extensions by SQLite should #include this file instead of 
 ** sqlite3.h.
 **
-** @(#) $Id: sqlite3ext.h,v 1.16 2007/08/30 17:15:38 drh Exp $
+** @(#) $Id: sqlite3ext.h,v 1.17 2007/08/31 16:11:36 drh Exp $
 */
 #ifndef _SQLITE3EXT_H_
 #define _SQLITE3EXT_H_
@@ -165,6 +165,7 @@ struct sqlite3_api_routines {
   int (*blob_read)(sqlite3_blob*,void*,int,int);
   int (*blob_write)(sqlite3_blob*,const void*,int,int);
   int (*create_collation_v2)(sqlite3*,const char*,int,void*,int(*)(void*,int,const void*,int,const void*),void(*)(void*));
+  int (*file_control)(sqlite3*,const char*,int,void*);
   sqlite3_int64 (*memory_highwater)(int);
   sqlite3_int64 (*memory_used)(void);
   sqlite3_mutex *(*mutex_alloc)(int);
@@ -324,6 +325,7 @@ struct sqlite3_api_routines {
 #define sqlite3_blob_read              sqlite3_api->blob_read
 #define sqlite3_blob_write             sqlite3_api->blob_write
 #define sqlite3_create_collation_v2    sqlite3_api->create_collation_v2
+#define sqlite3_file_control           sqlite3_api->file_control
 #define sqlite3_memory_highwater       sqlite3_api->memory_highwater
 #define sqlite3_memory_used            sqlite3_api->memory_used
 #define sqlite3_mutex_alloc            sqlite3_api->mutex_alloc

src/test6.c

@@ -476,8 +476,8 @@ static int cfCheckReservedLock(sqlite3_file *pFile){
 static int cfLockState(sqlite3_file *pFile){
   return sqlite3OsLockState(((CrashFile *)pFile)->pRealFile);
 }
-static int cfBreakLock(sqlite3_file *pFile){
+static int cfFileControl(sqlite3_file *pFile, int op, void *pArg){
-  return sqlite3OsBreakLock(((CrashFile *)pFile)->pRealFile);
+  return sqlite3OsFileControl(((CrashFile *)pFile)->pRealFile, op, pArg);
 }
 
 /*
@@ -503,8 +503,8 @@ static const sqlite3_io_methods CrashFileVtab = {
   cfLock,                       /* xLock */
   cfUnlock,                     /* xUnlock */
   cfCheckReservedLock,          /* xCheckReservedLock */
-  cfBreakLock,                  /* xBreakLock */
   cfLockState,                  /* xLockState */
+  cfFileControl,                /* xFileControl */
   cfSectorSize,                 /* xSectorSize */
   cfDeviceCharacteristics       /* xDeviceCharacteristics */
 };