1/* 2** 2010 April 7 3** 4** The author disclaims copyright to this source code. In place of 5** a legal notice, here is a blessing: 6** 7** May you do good and not evil. 8** May you find forgiveness for yourself and forgive others. 9** May you share freely, never taking more than you give. 10** 11************************************************************************* 12** 13** An example of a simple VFS implementation that omits complex features 14** often not required or not possible on embedded platforms. Also includes 15** code to buffer writes to the journal file, which can be a significant 16** performance improvement on some embedded platforms. 17** 18*/ 19 20/* 21** OVERVIEW 22** 23** The code in this file implements a minimal SQLite VFS that can be 24** used on Linux and other posix-like operating systems. The following 25** system calls are used: 26** 27** File-system: access(), unlink(), getcwd() 28** File IO: open(), read(), write(), fsync(), close(), fstat() 29** Other: sleep(), usleep(), time() 30** 31** The following VFS features are omitted: 32** 33** 1. File locking. The user must ensure that there is at most one 34** connection to each database when using this VFS. Multiple 35** connections to a single shared-cache count as a single connection 36** for the purposes of the previous statement. 37** 38** 2. The loading of dynamic extensions (shared libraries). 39** 40** 3. Temporary files. The user must configure SQLite to use in-memory 41** temp files when using this VFS. The easiest way to do this is to 42** compile with: 43** 44** -DSQLITE_TEMP_STORE=3 45** 46** 4. File truncation. As of version 3.6.24, SQLite may run without 47** a working xTruncate() call, providing the user does not configure 48** SQLite to use "journal_mode=truncate", or use both 49** "journal_mode=persist" and ATTACHed databases. 50** 51** It is assumed that the system uses UNIX-like path-names. Specifically, 52** that '/' characters are used to separate path components and that 53** a path-name is a relative path unless it begins with a '/'. And that 54** no UTF-8 encoded paths are greater than 512 bytes in length. 55** 56** JOURNAL WRITE-BUFFERING 57** 58** To commit a transaction to the database, SQLite first writes rollback 59** information into the journal file. This usually consists of 4 steps: 60** 61** 1. The rollback information is sequentially written into the journal 62** file, starting at the start of the file. 63** 2. The journal file is synced to disk. 64** 3. A modification is made to the first few bytes of the journal file. 65** 4. The journal file is synced to disk again. 66** 67** Most of the data is written in step 1 using a series of calls to the 68** VFS xWrite() method. The buffers passed to the xWrite() calls are of 69** various sizes. For example, as of version 3.6.24, when committing a 70** transaction that modifies 3 pages of a database file that uses 4096 71** byte pages residing on a media with 512 byte sectors, SQLite makes 72** eleven calls to the xWrite() method to create the rollback journal, 73** as follows: 74** 75** Write offset | Bytes written 76** ---------------------------- 77** 0 512 78** 512 4 79** 516 4096 80** 4612 4 81** 4616 4 82** 4620 4096 83** 8716 4 84** 8720 4 85** 8724 4096 86** 12820 4 87** ++++++++++++SYNC+++++++++++ 88** 0 12 89** ++++++++++++SYNC+++++++++++ 90** 91** On many operating systems, this is an efficient way to write to a file. 92** However, on some embedded systems that do not cache writes in OS 93** buffers it is much more efficient to write data in blocks that are 94** an integer multiple of the sector-size in size and aligned at the 95** start of a sector. 96** 97** To work around this, the code in this file allocates a fixed size 98** buffer of SQLITE_DEMOVFS_BUFFERSZ using sqlite3_malloc() whenever a 99** journal file is opened. It uses the buffer to coalesce sequential 100** writes into aligned SQLITE_DEMOVFS_BUFFERSZ blocks. When SQLite 101** invokes the xSync() method to sync the contents of the file to disk, 102** all accumulated data is written out, even if it does not constitute 103** a complete block. This means the actual IO to create the rollback 104** journal for the example transaction above is this: 105** 106** Write offset | Bytes written 107** ---------------------------- 108** 0 8192 109** 8192 4632 110** ++++++++++++SYNC+++++++++++ 111** 0 12 112** ++++++++++++SYNC+++++++++++ 113** 114** Much more efficient if the underlying OS is not caching write 115** operations. 116*/ 117 118#if !defined(SQLITE_TEST) || SQLITE_OS_UNIX 119 120#include <sqlite3.h> 121 122#include <assert.h> 123#include <string.h> 124#include <sys/types.h> 125#include <sys/stat.h> 126#include <sys/file.h> 127#include <sys/param.h> 128#include <unistd.h> 129#include <time.h> 130#include <errno.h> 131 132/* 133** Size of the write buffer used by journal files in bytes. 134*/ 135#ifndef SQLITE_DEMOVFS_BUFFERSZ 136# define SQLITE_DEMOVFS_BUFFERSZ 8192 137#endif 138 139/* 140** The maximum pathname length supported by this VFS. 141*/ 142#define MAXPATHNAME 512 143 144/* 145** When using this VFS, the sqlite3_file* handles that SQLite uses are 146** actually pointers to instances of type DemoFile. 147*/ 148typedef struct DemoFile DemoFile; 149struct DemoFile { 150 sqlite3_file base; /* Base class. Must be first. */ 151 int fd; /* File descriptor */ 152 153 char *aBuffer; /* Pointer to malloc'd buffer */ 154 int nBuffer; /* Valid bytes of data in zBuffer */ 155 sqlite3_int64 iBufferOfst; /* Offset in file of zBuffer[0] */ 156}; 157 158/* 159** Write directly to the file passed as the first argument. Even if the 160** file has a write-buffer (DemoFile.aBuffer), ignore it. 161*/ 162static int demoDirectWrite( 163 DemoFile *p, /* File handle */ 164 const void *zBuf, /* Buffer containing data to write */ 165 int iAmt, /* Size of data to write in bytes */ 166 sqlite_int64 iOfst /* File offset to write to */ 167){ 168 off_t ofst; /* Return value from lseek() */ 169 size_t nWrite; /* Return value from write() */ 170 171 ofst = lseek(p->fd, iOfst, SEEK_SET); 172 if( ofst!=iOfst ){ 173 return SQLITE_IOERR_WRITE; 174 } 175 176 nWrite = write(p->fd, zBuf, iAmt); 177 if( nWrite!=iAmt ){ 178 return SQLITE_IOERR_WRITE; 179 } 180 181 return SQLITE_OK; 182} 183 184/* 185** Flush the contents of the DemoFile.aBuffer buffer to disk. This is a 186** no-op if this particular file does not have a buffer (i.e. it is not 187** a journal file) or if the buffer is currently empty. 188*/ 189static int demoFlushBuffer(DemoFile *p){ 190 int rc = SQLITE_OK; 191 if( p->nBuffer ){ 192 rc = demoDirectWrite(p, p->aBuffer, p->nBuffer, p->iBufferOfst); 193 p->nBuffer = 0; 194 } 195 return rc; 196} 197 198/* 199** Close a file. 200*/ 201static int demoClose(sqlite3_file *pFile){ 202 int rc; 203 DemoFile *p = (DemoFile*)pFile; 204 rc = demoFlushBuffer(p); 205 sqlite3_free(p->aBuffer); 206 close(p->fd); 207 return rc; 208} 209 210/* 211** Read data from a file. 212*/ 213static int demoRead( 214 sqlite3_file *pFile, 215 void *zBuf, 216 int iAmt, 217 sqlite_int64 iOfst 218){ 219 DemoFile *p = (DemoFile*)pFile; 220 off_t ofst; /* Return value from lseek() */ 221 int nRead; /* Return value from read() */ 222 int rc; /* Return code from demoFlushBuffer() */ 223 224 /* Flush any data in the write buffer to disk in case this operation 225 ** is trying to read data the file-region currently cached in the buffer. 226 ** It would be possible to detect this case and possibly save an 227 ** unnecessary write here, but in practice SQLite will rarely read from 228 ** a journal file when there is data cached in the write-buffer. 229 */ 230 rc = demoFlushBuffer(p); 231 if( rc!=SQLITE_OK ){ 232 return rc; 233 } 234 235 ofst = lseek(p->fd, iOfst, SEEK_SET); 236 if( ofst!=iOfst ){ 237 return SQLITE_IOERR_READ; 238 } 239 nRead = read(p->fd, zBuf, iAmt); 240 241 if( nRead==iAmt ){ 242 return SQLITE_OK; 243 }else if( nRead>=0 ){ 244 return SQLITE_IOERR_SHORT_READ; 245 } 246 247 return SQLITE_IOERR_READ; 248} 249 250/* 251** Write data to a crash-file. 252*/ 253static int demoWrite( 254 sqlite3_file *pFile, 255 const void *zBuf, 256 int iAmt, 257 sqlite_int64 iOfst 258){ 259 DemoFile *p = (DemoFile*)pFile; 260 261 if( p->aBuffer ){ 262 char *z = (char *)zBuf; /* Pointer to remaining data to write */ 263 int n = iAmt; /* Number of bytes at z */ 264 sqlite3_int64 i = iOfst; /* File offset to write to */ 265 266 while( n>0 ){ 267 int nCopy; /* Number of bytes to copy into buffer */ 268 269 /* If the buffer is full, or if this data is not being written directly 270 ** following the data already buffered, flush the buffer. Flushing 271 ** the buffer is a no-op if it is empty. 272 */ 273 if( p->nBuffer==SQLITE_DEMOVFS_BUFFERSZ || p->iBufferOfst+p->nBuffer!=i ){ 274 int rc = demoFlushBuffer(p); 275 if( rc!=SQLITE_OK ){ 276 return rc; 277 } 278 } 279 assert( p->nBuffer==0 || p->iBufferOfst+p->nBuffer==i ); 280 p->iBufferOfst = i - p->nBuffer; 281 282 /* Copy as much data as possible into the buffer. */ 283 nCopy = SQLITE_DEMOVFS_BUFFERSZ - p->nBuffer; 284 if( nCopy>n ){ 285 nCopy = n; 286 } 287 memcpy(&p->aBuffer[p->nBuffer], z, nCopy); 288 p->nBuffer += nCopy; 289 290 n -= nCopy; 291 i += nCopy; 292 z += nCopy; 293 } 294 }else{ 295 return demoDirectWrite(p, zBuf, iAmt, iOfst); 296 } 297 298 return SQLITE_OK; 299} 300 301/* 302** Truncate a file. This is a no-op for this VFS (see header comments at 303** the top of the file). 304*/ 305static int demoTruncate(sqlite3_file *pFile, sqlite_int64 size){ 306#if 0 307 if( ftruncate(((DemoFile *)pFile)->fd, size) ) return SQLITE_IOERR_TRUNCATE; 308#endif 309 return SQLITE_OK; 310} 311 312/* 313** Sync the contents of the file to the persistent media. 314*/ 315static int demoSync(sqlite3_file *pFile, int flags){ 316 DemoFile *p = (DemoFile*)pFile; 317 int rc; 318 319 rc = demoFlushBuffer(p); 320 if( rc!=SQLITE_OK ){ 321 return rc; 322 } 323 324 rc = fsync(p->fd); 325 return (rc==0 ? SQLITE_OK : SQLITE_IOERR_FSYNC); 326} 327 328/* 329** Write the size of the file in bytes to *pSize. 330*/ 331static int demoFileSize(sqlite3_file *pFile, sqlite_int64 *pSize){ 332 DemoFile *p = (DemoFile*)pFile; 333 int rc; /* Return code from fstat() call */ 334 struct stat sStat; /* Output of fstat() call */ 335 336 /* Flush the contents of the buffer to disk. As with the flush in the 337 ** demoRead() method, it would be possible to avoid this and save a write 338 ** here and there. But in practice this comes up so infrequently it is 339 ** not worth the trouble. 340 */ 341 rc = demoFlushBuffer(p); 342 if( rc!=SQLITE_OK ){ 343 return rc; 344 } 345 346 rc = fstat(p->fd, &sStat); 347 if( rc!=0 ) return SQLITE_IOERR_FSTAT; 348 *pSize = sStat.st_size; 349 return SQLITE_OK; 350} 351 352/* 353** Locking functions. The xLock() and xUnlock() methods are both no-ops. 354** The xCheckReservedLock() always indicates that no other process holds 355** a reserved lock on the database file. This ensures that if a hot-journal 356** file is found in the file-system it is rolled back. 357*/ 358static int demoLock(sqlite3_file *pFile, int eLock){ 359 return SQLITE_OK; 360} 361static int demoUnlock(sqlite3_file *pFile, int eLock){ 362 return SQLITE_OK; 363} 364static int demoCheckReservedLock(sqlite3_file *pFile, int *pResOut){ 365 *pResOut = 0; 366 return SQLITE_OK; 367} 368 369/* 370** No xFileControl() verbs are implemented by this VFS. 371*/ 372static int demoFileControl(sqlite3_file *pFile, int op, void *pArg){ 373 return SQLITE_OK; 374} 375 376/* 377** The xSectorSize() and xDeviceCharacteristics() methods. These two 378** may return special values allowing SQLite to optimize file-system 379** access to some extent. But it is also safe to simply return 0. 380*/ 381static int demoSectorSize(sqlite3_file *pFile){ 382 return 0; 383} 384static int demoDeviceCharacteristics(sqlite3_file *pFile){ 385 return 0; 386} 387 388/* 389** Open a file handle. 390*/ 391static int demoOpen( 392 sqlite3_vfs *pVfs, /* VFS */ 393 const char *zName, /* File to open, or 0 for a temp file */ 394 sqlite3_file *pFile, /* Pointer to DemoFile struct to populate */ 395 int flags, /* Input SQLITE_OPEN_XXX flags */ 396 int *pOutFlags /* Output SQLITE_OPEN_XXX flags (or NULL) */ 397){ 398 static const sqlite3_io_methods demoio = { 399 1, /* iVersion */ 400 demoClose, /* xClose */ 401 demoRead, /* xRead */ 402 demoWrite, /* xWrite */ 403 demoTruncate, /* xTruncate */ 404 demoSync, /* xSync */ 405 demoFileSize, /* xFileSize */ 406 demoLock, /* xLock */ 407 demoUnlock, /* xUnlock */ 408 demoCheckReservedLock, /* xCheckReservedLock */ 409 demoFileControl, /* xFileControl */ 410 demoSectorSize, /* xSectorSize */ 411 demoDeviceCharacteristics /* xDeviceCharacteristics */ 412 }; 413 414 DemoFile *p = (DemoFile*)pFile; /* Populate this structure */ 415 int oflags = 0; /* flags to pass to open() call */ 416 char *aBuf = 0; 417 418 if( zName==0 ){ 419 return SQLITE_IOERR; 420 } 421 422 if( flags&SQLITE_OPEN_MAIN_JOURNAL ){ 423 aBuf = (char *)sqlite3_malloc(SQLITE_DEMOVFS_BUFFERSZ); 424 if( !aBuf ){ 425 return SQLITE_NOMEM; 426 } 427 } 428 429 if( flags&SQLITE_OPEN_EXCLUSIVE ) oflags |= O_EXCL; 430 if( flags&SQLITE_OPEN_CREATE ) oflags |= O_CREAT; 431 if( flags&SQLITE_OPEN_READONLY ) oflags |= O_RDONLY; 432 if( flags&SQLITE_OPEN_READWRITE ) oflags |= O_RDWR; 433 434 memset(p, 0, sizeof(DemoFile)); 435 p->fd = open(zName, oflags, 0600); 436 if( p->fd<0 ){ 437 sqlite3_free(aBuf); 438 return SQLITE_CANTOPEN; 439 } 440 p->aBuffer = aBuf; 441 442 if( pOutFlags ){ 443 *pOutFlags = flags; 444 } 445 p->base.pMethods = &demoio; 446 return SQLITE_OK; 447} 448 449/* 450** Delete the file identified by argument zPath. If the dirSync parameter 451** is non-zero, then ensure the file-system modification to delete the 452** file has been synced to disk before returning. 453*/ 454static int demoDelete(sqlite3_vfs *pVfs, const char *zPath, int dirSync){ 455 int rc; /* Return code */ 456 457 rc = unlink(zPath); 458 if( rc!=0 && errno==ENOENT ) return SQLITE_OK; 459 460 if( rc==0 && dirSync ){ 461 int dfd; /* File descriptor open on directory */ 462 int i; /* Iterator variable */ 463 char zDir[MAXPATHNAME+1]; /* Name of directory containing file zPath */ 464 465 /* Figure out the directory name from the path of the file deleted. */ 466 sqlite3_snprintf(MAXPATHNAME, zDir, "%s", zPath); 467 zDir[MAXPATHNAME] = '\0'; 468 for(i=strlen(zDir); i>1 && zDir[i]!='/'; i++); 469 zDir[i] = '\0'; 470 471 /* Open a file-descriptor on the directory. Sync. Close. */ 472 dfd = open(zDir, O_RDONLY, 0); 473 if( dfd<0 ){ 474 rc = -1; 475 }else{ 476 rc = fsync(dfd); 477 close(dfd); 478 } 479 } 480 return (rc==0 ? SQLITE_OK : SQLITE_IOERR_DELETE); 481} 482 483#ifndef F_OK 484# define F_OK 0 485#endif 486#ifndef R_OK 487# define R_OK 4 488#endif 489#ifndef W_OK 490# define W_OK 2 491#endif 492 493/* 494** Query the file-system to see if the named file exists, is readable or 495** is both readable and writable. 496*/ 497static int demoAccess( 498 sqlite3_vfs *pVfs, 499 const char *zPath, 500 int flags, 501 int *pResOut 502){ 503 int rc; /* access() return code */ 504 int eAccess = F_OK; /* Second argument to access() */ 505 506 assert( flags==SQLITE_ACCESS_EXISTS /* access(zPath, F_OK) */ 507 || flags==SQLITE_ACCESS_READ /* access(zPath, R_OK) */ 508 || flags==SQLITE_ACCESS_READWRITE /* access(zPath, R_OK|W_OK) */ 509 ); 510 511 if( flags==SQLITE_ACCESS_READWRITE ) eAccess = R_OK|W_OK; 512 if( flags==SQLITE_ACCESS_READ ) eAccess = R_OK; 513 514 rc = access(zPath, eAccess); 515 *pResOut = (rc==0); 516 return SQLITE_OK; 517} 518 519/* 520** Argument zPath points to a nul-terminated string containing a file path. 521** If zPath is an absolute path, then it is copied as is into the output 522** buffer. Otherwise, if it is a relative path, then the equivalent full 523** path is written to the output buffer. 524** 525** This function assumes that paths are UNIX style. Specifically, that: 526** 527** 1. Path components are separated by a '/'. and 528** 2. Full paths begin with a '/' character. 529*/ 530static int demoFullPathname( 531 sqlite3_vfs *pVfs, /* VFS */ 532 const char *zPath, /* Input path (possibly a relative path) */ 533 int nPathOut, /* Size of output buffer in bytes */ 534 char *zPathOut /* Pointer to output buffer */ 535){ 536 char zDir[MAXPATHNAME+1]; 537 if( zPath[0]=='/' ){ 538 zDir[0] = '\0'; 539 }else{ 540 getcwd(zDir, sizeof(zDir)); 541 } 542 zDir[MAXPATHNAME] = '\0'; 543 544 sqlite3_snprintf(nPathOut, zPathOut, "%s/%s", zDir, zPath); 545 zPathOut[nPathOut-1] = '\0'; 546 547 return SQLITE_OK; 548} 549 550/* 551** The following four VFS methods: 552** 553** xDlOpen 554** xDlError 555** xDlSym 556** xDlClose 557** 558** are supposed to implement the functionality needed by SQLite to load 559** extensions compiled as shared objects. This simple VFS does not support 560** this functionality, so the following functions are no-ops. 561*/ 562static void *demoDlOpen(sqlite3_vfs *pVfs, const char *zPath){ 563 return 0; 564} 565static void demoDlError(sqlite3_vfs *pVfs, int nByte, char *zErrMsg){ 566 sqlite3_snprintf(nByte, zErrMsg, "Loadable extensions are not supported"); 567 zErrMsg[nByte-1] = '\0'; 568} 569static void (*demoDlSym(sqlite3_vfs *pVfs, void *pH, const char *z))(void){ 570 return 0; 571} 572static void demoDlClose(sqlite3_vfs *pVfs, void *pHandle){ 573 return; 574} 575 576/* 577** Parameter zByte points to a buffer nByte bytes in size. Populate this 578** buffer with pseudo-random data. 579*/ 580static int demoRandomness(sqlite3_vfs *pVfs, int nByte, char *zByte){ 581 return SQLITE_OK; 582} 583 584/* 585** Sleep for at least nMicro microseconds. Return the (approximate) number 586** of microseconds slept for. 587*/ 588static int demoSleep(sqlite3_vfs *pVfs, int nMicro){ 589 sleep(nMicro / 1000000); 590 usleep(nMicro % 1000000); 591 return nMicro; 592} 593 594/* 595** Set *pTime to the current UTC time expressed as a Julian day. Return 596** SQLITE_OK if successful, or an error code otherwise. 597** 598** http://en.wikipedia.org/wiki/Julian_day 599** 600** This implementation is not very good. The current time is rounded to 601** an integer number of seconds. Also, assuming time_t is a signed 32-bit 602** value, it will stop working some time in the year 2038 AD (the so-called 603** "year 2038" problem that afflicts systems that store time this way). 604*/ 605static int demoCurrentTime(sqlite3_vfs *pVfs, double *pTime){ 606 time_t t = time(0); 607 *pTime = t/86400.0 + 2440587.5; 608 return SQLITE_OK; 609} 610 611/* 612** This function returns a pointer to the VFS implemented in this file. 613** To make the VFS available to SQLite: 614** 615** sqlite3_vfs_register(sqlite3_demovfs(), 0); 616*/ 617sqlite3_vfs *sqlite3_demovfs(void){ 618 static sqlite3_vfs demovfs = { 619 1, /* iVersion */ 620 sizeof(DemoFile), /* szOsFile */ 621 MAXPATHNAME, /* mxPathname */ 622 0, /* pNext */ 623 "demo", /* zName */ 624 0, /* pAppData */ 625 demoOpen, /* xOpen */ 626 demoDelete, /* xDelete */ 627 demoAccess, /* xAccess */ 628 demoFullPathname, /* xFullPathname */ 629 demoDlOpen, /* xDlOpen */ 630 demoDlError, /* xDlError */ 631 demoDlSym, /* xDlSym */ 632 demoDlClose, /* xDlClose */ 633 demoRandomness, /* xRandomness */ 634 demoSleep, /* xSleep */ 635 demoCurrentTime, /* xCurrentTime */ 636 }; 637 return &demovfs; 638} 639 640#endif /* !defined(SQLITE_TEST) || SQLITE_OS_UNIX */ 641 642 643#ifdef SQLITE_TEST 644 645#include <tcl.h> 646 647#if SQLITE_OS_UNIX 648static int register_demovfs( 649 ClientData clientData, /* Pointer to sqlite3_enable_XXX function */ 650 Tcl_Interp *interp, /* The TCL interpreter that invoked this command */ 651 int objc, /* Number of arguments */ 652 Tcl_Obj *CONST objv[] /* Command arguments */ 653){ 654 sqlite3_vfs_register(sqlite3_demovfs(), 1); 655 return TCL_OK; 656} 657static int unregister_demovfs( 658 ClientData clientData, /* Pointer to sqlite3_enable_XXX function */ 659 Tcl_Interp *interp, /* The TCL interpreter that invoked this command */ 660 int objc, /* Number of arguments */ 661 Tcl_Obj *CONST objv[] /* Command arguments */ 662){ 663 sqlite3_vfs_unregister(sqlite3_demovfs()); 664 return TCL_OK; 665} 666 667/* 668** Register commands with the TCL interpreter. 669*/ 670int Sqlitetest_demovfs_Init(Tcl_Interp *interp){ 671 Tcl_CreateObjCommand(interp, "register_demovfs", register_demovfs, 0, 0); 672 Tcl_CreateObjCommand(interp, "unregister_demovfs", unregister_demovfs, 0, 0); 673 return TCL_OK; 674} 675 676#else 677int Sqlitetest_demovfs_Init(Tcl_Interp *interp){ return TCL_OK; } 678#endif 679 680#endif /* SQLITE_TEST */ 681