SQLite

Check-in [c6809bf776]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Documentation updates in preparation for the release of version 3.5.0. (CVS 4386)
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: c6809bf77625f420ac62513635628ff4f1766f83
User & Date: drh 2007-09-03 20:32:45.000
Context
2007-09-03
22:00
Fix btree.c so that it works with -DSQLITE_THREADSAFE=0 and -DSQLITE_DEBUG=1 (CVS 4387) (check-in: fee2d7c0e6 user: drh tags: trunk)
20:32
Documentation updates in preparation for the release of version 3.5.0. (CVS 4386) (check-in: c6809bf776 user: drh tags: trunk)
18:01
In sqllimits1.test, set MAX_SQL_LENGTH to a value smaller than MAX_LENGTH. (CVS 4385) (check-in: 51726a9bb6 user: danielk1977 tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to VERSION.
1
3.4.2
|
1
3.5.0
Changes to src/sqlite.h.in.
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.255 2007/09/03 15:19:35 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.







|







26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.256 2007/09/03 20:32:45 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424




1425
1426
1427
1428
1429
1430
1431
** 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 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 the default [sqlite3_vfs]
** object is used.
**
** <b>Note to windows users:</b>  The encoding used for the filename argument







|








>
>
>
>







1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
** 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 always used for [sqlite3_open()]
** and [sqlite3_open16()].
**
** If the filename is ":memory:", 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.
**
** If the filename is an empty string, then a private temporary
** on-disk database will be created.  This private database will be
** automatically deleted as soon as the database connection is closed.
**
** 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 the default [sqlite3_vfs]
** object is used.
**
** <b>Note to windows users:</b>  The encoding used for the filename argument
Changes to www/34to35.tcl.
1
2
3
4
5
6
7
8
9
10
11
#
# Run this TCL script to generate HTML for the goals.html file.
#
set rcsid {$Id: 34to35.tcl,v 1.2 2007/09/03 12:34:57 drh Exp $}
source common.tcl
header {SQLite Changes From Version 3.4.2 To 3.5.0}

proc CODE {text} {
  puts "<blockquote><pre>"
  puts $text
  puts "</pre></blockquote>"



|







1
2
3
4
5
6
7
8
9
10
11
#
# Run this TCL script to generate HTML for the goals.html file.
#
set rcsid {$Id: 34to35.tcl,v 1.3 2007/09/03 20:32:45 drh Exp $}
source common.tcl
header {SQLite Changes From Version 3.4.2 To 3.5.0}

proc CODE {text} {
  puts "<blockquote><pre>"
  puts $text
  puts "</pre></blockquote>"
23
24
25
26
27
28
29
30
31











32
33
34
35
36
37
38
    puts "<br>$caption"
  }
  puts "</center>"
}
proc PARAGRAPH {text} {
  # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
  #regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
  regsub -all {\[([^]\n]+)\]} $text {<b>\1</b>} t3
  puts "<p>$t3</p>\n"











}
set level(0) 0
set level(1) 0
proc HEADING {n name {tag {}}} {
  if {$tag!=""} {
    puts "<a name=\"$tag\">"
  }







|
|
>
>
>
>
>
>
>
>
>
>
>







23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
    puts "<br>$caption"
  }
  puts "</center>"
}
proc PARAGRAPH {text} {
  # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
  #regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
  regsub -all {\[([^]\n]+)\]} $text {[resolve_link \1]} t3
  puts "<p>[subst -novar -noback $t3]</p>\n"
}
proc resolve_link {args} {
  set a2 [split $args |]
  set id [string trim [lindex $a2 0]]
  if {[lindex $a2 1]==""} {
    set display [string trim [lindex $a2 0]]
  } else {
    set display [string trim [lrange $a2 1 end]]
  }
  regsub -all {[^a-zA-Z0-9_]} $id {} id
  return "<a href=\"capi3ref.html#$id\">$display</a>"
}
set level(0) 0
set level(1) 0
proc HEADING {n name {tag {}}} {
  if {$tag!=""} {
    puts "<a name=\"$tag\">"
  }
75
76
77
78
79
80
81

82
83
84
85
86
87
88
89
90
  is provide here.  Subsequent sections will describe these
  changes in more detail.
}
PARAGRAPH {
  <ol>
  <li>The OS interface layer has been completely reworked:
  <ol type="a">

  <li>The [sqlite3_os_switch()] interface has been removed.</li>
  <li>The [SQLITE_ENABLE_REDEF_IO] compile-time flag no longer functions.
      I/O procedures are now always redefinable.</li>
  <li>Three new objects are defined for specifying I/O procedures:
      [sqlite3_vfs], [sqlite3_file], and [sqlite3_io_methods].</li>
  <li>Three new interfaces are used to create alternative OS interfaces:
      [sqlite3_vfs_register()], [sqlite3_vfs_unregister()], and
      [sqlite3_vfs_find()].</li>
  <li>A new interface has been added to provided additional control over







>
|
|







86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
  is provide here.  Subsequent sections will describe these
  changes in more detail.
}
PARAGRAPH {
  <ol>
  <li>The OS interface layer has been completely reworked:
  <ol type="a">
  <li>The undocumented <b>sqlite3_os_switch()</b> interface has
      been removed.</li>
  <li>The <b>SQLITE_ENABLE_REDEF_IO</b> compile-time flag no longer functions.
      I/O procedures are now always redefinable.</li>
  <li>Three new objects are defined for specifying I/O procedures:
      [sqlite3_vfs], [sqlite3_file], and [sqlite3_io_methods].</li>
  <li>Three new interfaces are used to create alternative OS interfaces:
      [sqlite3_vfs_register()], [sqlite3_vfs_unregister()], and
      [sqlite3_vfs_find()].</li>
  <li>A new interface has been added to provided additional control over
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
  systems. 
}

HEADING 1 {The OS Interface Layer}

PARAGRAPH {
  If your system defines a custom OS interface for SQLite or if you
  were using the (undocumented) [sqlite3_os_switch()]
  interface, then you will need to make modifications in order to
  upgrade to SQLite version 3.5.0.  This may seem painful at first
  glance.  But as you look more closely, you will probably discover
  that your changes are made smaller and easier to understand and manage
  by the new SQLite interface.  It is likely that your changes will
  now also work seamlessly with the SQLite amalgamation.  You will
  no longer need to make any changes to the code SQLite source code.







|







142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
  systems. 
}

HEADING 1 {The OS Interface Layer}

PARAGRAPH {
  If your system defines a custom OS interface for SQLite or if you
  were using the undocumented <b>sqlite3_os_switch()</b>
  interface, then you will need to make modifications in order to
  upgrade to SQLite version 3.5.0.  This may seem painful at first
  glance.  But as you look more closely, you will probably discover
  that your changes are made smaller and easier to understand and manage
  by the new SQLite interface.  It is likely that your changes will
  now also work seamlessly with the SQLite amalgamation.  You will
  no longer need to make any changes to the code SQLite source code.
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374

375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402














403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
  SQLite will guarantee that the zFilename string passed to
  xOpen() is a full pathname as generated by xFullPathname() and
  that the string will be valid and unchanged until xClose() is
  called.  So the [sqlite3_file] can store a pointer to the
   filename if it needs to remember the filename for some reason.
   The flags argument to xOpen() is a copy of the flags argument
   to sqlite3_open_v2().  If sqlite3_open() or sqlite3_open16()
   is used, then flags is SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE.
   If xOpen() opens a file read-only then it sets *pOutFlags to
   include SQLITE_OPEN_READONLY.  Other bits in *pOutFlags may be
   set.
   SQLite will also add one of the following flags to the xOpen()
   call, depending on the object being opened:
   <ul>
   <li>  [SQLITE_OPEN_MAIN_DB]
   <li>  [SQLITE_OPEN_MAIN_JOURNAL]
   <li>  [SQLITE_OPEN_TEMP_DB]
   <li>  [SQLITE_OPEN_TEMP_JOURNAL]

   <li>  [SQLITE_OPEN_SUBJOURNAL]
   <li>  [SQLITE_OPEN_MASTER_JOURNAL]
   </ul>
   The file I/O implementation can use the object type flags to
   changes the way it deals with files.  For example, an application
   that does not care about crash recovery or rollback, might make
   the open of a journal file a no-op.  Writes to this journal are
   also a no-op.  Any attempt to read the journal return SQLITE_IOERR.
   Or the implementation might recognize the a database file will
   be doing page-aligned sector reads and writes in a random order
   and set up its I/O subsystem accordingly.
   SQLite might also add one of the following flags to the xOpen
   method:
   <ul>
   <li> [SQLITE_OPEN_DELETEONCLOSE]
   <li> [SQLITE_OPEN_EXCLUSIVE]
   </ul>
   The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
   deleted when it is closed.  This will always be set for TEMP 
   databases and journals and for subjournals.  The 
   [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
   for exclusive access.  This flag is set for all files except
   for the main database file.
   The [sqlite3_file] structure passed as the third argument to
   xOpen is allocated by the caller.  xOpen just fills it in.  The
   caller allocates a minimum of szOsFile bytes for the [sqlite3_file]
   structure.
}















PARAGRAPH {
  The xDelete method is used delete a file.  The name of the file is
  given in the second parameter.  The filename will be in UTF-8.
  The VFS must convert the filename into whatever character representation
  the underlying operating system expects.  If the syncDir parameter is
  true, then the xDelete method should not return until the change
  to the directory contents for the directory containing the
  deleted file have been synced to disk in order to insure that the
  file does not "reappear" if a power failure occurs soon after.
}

PARAGRAPH {
  The xAccess method is used to check for access permissions on a file.
  The filename will be UTF-8 encoded.  The flags argument will be
  SQLITE_ACCESS_EXISTS to check for the existence of the file,
  SQLITE_ACCESS_READWRITE to check to see if the file is both readable
  and writable, or SQLITE_ACCESS_READ to check to see if the file is
  at least readable.  The "file" named by the second parameter might
  be a directory or folder name.
}

PARAGRAPH {
  The xGetTempName method computes the name of a temporary file that
  SQLite can use.  The name should be written into the buffer given







|

|








>







|




















>
>
>
>
>
>
>
>
>
>
>
>
>
>















|
|
|







369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
  SQLite will guarantee that the zFilename string passed to
  xOpen() is a full pathname as generated by xFullPathname() and
  that the string will be valid and unchanged until xClose() is
  called.  So the [sqlite3_file] can store a pointer to the
   filename if it needs to remember the filename for some reason.
   The flags argument to xOpen() is a copy of the flags argument
   to sqlite3_open_v2().  If sqlite3_open() or sqlite3_open16()
   is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
   If xOpen() opens a file read-only then it sets *pOutFlags to
   include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be
   set.
   SQLite will also add one of the following flags to the xOpen()
   call, depending on the object being opened:
   <ul>
   <li>  [SQLITE_OPEN_MAIN_DB]
   <li>  [SQLITE_OPEN_MAIN_JOURNAL]
   <li>  [SQLITE_OPEN_TEMP_DB]
   <li>  [SQLITE_OPEN_TEMP_JOURNAL]
   <li>  [SQLITE_OPEN_TRANSIENT_DB]
   <li>  [SQLITE_OPEN_SUBJOURNAL]
   <li>  [SQLITE_OPEN_MASTER_JOURNAL]
   </ul>
   The file I/O implementation can use the object type flags to
   changes the way it deals with files.  For example, an application
   that does not care about crash recovery or rollback, might make
   the open of a journal file a no-op.  Writes to this journal are
   also a no-op.  Any attempt to read the journal returns [SQLITE_IOERR].
   Or the implementation might recognize the a database file will
   be doing page-aligned sector reads and writes in a random order
   and set up its I/O subsystem accordingly.
   SQLite might also add one of the following flags to the xOpen
   method:
   <ul>
   <li> [SQLITE_OPEN_DELETEONCLOSE]
   <li> [SQLITE_OPEN_EXCLUSIVE]
   </ul>
   The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
   deleted when it is closed.  This will always be set for TEMP 
   databases and journals and for subjournals.  The 
   [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
   for exclusive access.  This flag is set for all files except
   for the main database file.
   The [sqlite3_file] structure passed as the third argument to
   xOpen is allocated by the caller.  xOpen just fills it in.  The
   caller allocates a minimum of szOsFile bytes for the [sqlite3_file]
   structure.
}

PARAGRAPH {
  The differences between an [SQLITE_OPEN_TEMP_DB] database and an
  [SQLITE_OPEN_TRANSIENT_DB] database is this:  The [SQLITE_OPEN_TEMP_DB]
  is used for explicitly declared and named TEMP tables (using the
  CREATE TEMP TABLE syntax) or for named tables in a temporary database
  that is created by opening a database with a filename that is an empty
  string.  An [SQLITE_OPEN_TRANSIENT_DB] holds an database table that
  SQLite creates automatically in order to evaluate a subquery or
  ORDER BY or GROUP BY clause.  Both TEMP_DB and TRANSIENT_DB databases
  are private and are deleted automatically.  TEMP_DB databases last
  for the duration of the database connection.  TRANSIENT_DB databases
  last only for the duration of a single SQL statement.
}

PARAGRAPH {
  The xDelete method is used delete a file.  The name of the file is
  given in the second parameter.  The filename will be in UTF-8.
  The VFS must convert the filename into whatever character representation
  the underlying operating system expects.  If the syncDir parameter is
  true, then the xDelete method should not return until the change
  to the directory contents for the directory containing the
  deleted file have been synced to disk in order to insure that the
  file does not "reappear" if a power failure occurs soon after.
}

PARAGRAPH {
  The xAccess method is used to check for access permissions on a file.
  The filename will be UTF-8 encoded.  The flags argument will be
  [SQLITE_ACCESS_EXISTS] to check for the existence of the file,
  [SQLITE_ACCESS_READWRITE] to check to see if the file is both readable
  and writable, or [SQLITE_ACCESS_READ] to check to see if the file is
  at least readable.  The "file" named by the second parameter might
  be a directory or folder name.
}

PARAGRAPH {
  The xGetTempName method computes the name of a temporary file that
  SQLite can use.  The name should be written into the buffer given
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*);
  int (*xBreakLock)(sqlite3_file*);
  int (*xLockState)(sqlite3_file *);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Additional methods may be added in future releases */
};
}

PARAGRAPH {







|
<







555
556
557
558
559
560
561
562

563
564
565
566
567
568
569
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(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 */
};
}

PARAGRAPH {
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650











651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684

685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
  contains pointers to other allocated memory or resources, those
  allocations should be released by the xClose method.
}

PARAGRAPH {
  The xRead method reads iAmt bytes from the file beginning at a byte
  offset to iOfst.  The data read is stored in the pointer of the
  second parameter.  xRead returns the SQLITE_OK on success,
  SQLITE_IOERR_SHORT_READ if it was not able to read the full number
  of bytes because it reached end-of-file, or SQLITE_IOERR_READ for
  any other error.
}

PARAGRAPH {
  The xWrite method writes iAmt bytes of data from the second parameter
  into the file beginning at an offset of iOfst bytes.  If the size of
  the file is less than iOfst bytes prior to the write, then xWrite should
  ensure that the file is extended with zeros up to iOfst bytes prior
  to beginning its write.  xWrite continues to extends the file as
  necessary so that the size of the file is at least iAmt+iOfst bytes 
  at the conclusion of the xWrite call.  The xWrite method returns
  SQLITE_OK on success.  If the write cannot complete because the
  underlying storage medium is full, then SQLITE_FULL is returned.
  SQLITE_IOERR_WRITE should be returned for any other error.
}

PARAGRAPH {
  The xTruncate method truncates a file to be nByte bytes in length.
  If the file is already nByte bytes or less in length then this
  method is a no-op.  The xTruncate method returns SQLITE_OK on
  success and SQLITE_IOERR_TRUNCATE if anything goes wrong.
}

PARAGRAPH {
  The xSync method is used to force previously written data out of
  operating system cache and into non-volatile memory.  The second
  parameter is usually SQLITE_SYNC_NORMAL.  If the second parameter
  is SQLITE_SYNC_FULL then the xSync method should make sure that
  data has also been flushed through the disk controllers cache.
  The SQLITE_SYNC_FULL parameter is the equivalent of the F_FULLSYNC
  ioctl() on Mac OS X.  The SQLITE_SYNC_BARRIER is currently unused.
  In the future this value might request that the xSync call serve
  as an I/O barrier operation.  All write requests that occur before
  the xSync must complete before any write request that occurs
  afterwards, but the barrier does not require that all writes 
  complete prior to the return of xSync.  The xSync method returns
  SQLITE_OK on success and SQLITE_IOERR_FSYNC if anything goes wrong.
}

PARAGRAPH {
  The xFileSize() method determines the current size of the file
  in bytes and writes that value into *pSize.  It returns SQLITE_OK
  on success and SQLITE_IOERR_FSTAT if something goes wrong.
}

PARAGRAPH {
  The xLock and xUnlock methods are used to set and clear file locks.
  SQLite supports five levels of file locks, in order:
  <ul>
  <li> [SQLITE_LOCK_NONE]
  <li> [SQLITE_LOCK_SHARED]
  <li> [SQLITE_LOCK_RESERVED]
  <li> [SQLITE_LOCK_PENDING]
  <li> [SQLITE_LOCK_EXCLUSIVE]
  </ul>
  The underlying implementation can support some subset of these locking
  levels as long as it meets the other requirements of this paragraph.
  The locking level is specified as the second argument to both xLock
  and xUnlock.  The xLock method increases the locking level to the
  specified locking level or higher.  The xUnlock method decreases the
  locking level to no lower than the level specified.  
  SQLITE_LOCK_NONE means that the file is unlocked.  SQLITE_LOCK_SHARED
  gives permission to read the file.  Multiple database connections can
  hold SQLITE_LOCK_SHARED at the same time.
  SQLITE_LOCK_RESERVED is like SQLITE_LOCK_SHARED in that its is permission
  to read the file.  But only a single connection can hold a reserved lock
  at any point in time.  The SQLITE_LOCK_PENDING is also permission to
  read the file.  Other connections can continue to read the file as well,
  but no other connection is allowed to escalate a lock from none to shared.
  SQLITE_LOCK_EXCLUSIVE is permission to write on the file.  Only a single
  connection can hold an exclusive lock and no other connection can hold
  any lock (other than "none") while one connection is hold an exclusive
  lock.  The xLock returns SQLITE_OK on success, SQLITE_BUSY if it
  is unable to obtain the lock, or SQLITE_IOERR_RDLOCK if something else
  goes wrong.  The xUnlock method returns SQLITE_OK on success and
  SQLITE_IOERR_UNLOCK for problems.
}

PARAGRAPH {
  The xCheckReservedLock method checks to see if another connection or
  another process is currently holding a reserved, pending, or exclusive
  lock on the file.  It returns true or false.
}

PARAGRAPH {
  The xLockState method returns one of the [SQLITE_LOCK_NONE] through
  [SQLITE_LOCK_EXCLUSIVE] constants defined above to indicate the current
  state of the lock for the given file handle.  This method is used for
  testing purposes only.











}

PARAGRAPH {
  The xSectorSize returns the "sector size" of the underlying
  non-volatile media.  A "sector" is defined as the smallest unit of
  storage that can be written without disturbing adjacent storage.
  On a disk drive the "sector size" has until recently been 512 bytes,
  though there is a push to increase this value to 4KiB.  SQLite needs
  to know the sector size so that it can write a full sector at a
  time, and thus avoid corrupting adjacent storage space if a power
  lose occurs in the middle of a write.
}

PARAGRAPH {
  The xDeviceCharacteristics method returns an integer bit vector that
  defines any special properties that the underlying storage medium might
  have that SQLite can use to increase performance.  The allowed return
  is the bit-wise OR of the following values:
  <ul>
  <li> SQLITE_IOCAP_ATOMIC
  <li> SQLITE_IOCAP_ATOMIC512
  <li> SQLITE_IOCAP_ATOMIC1K
  <li> SQLITE_IOCAP_ATOMIC2K
  <li> SQLITE_IOCAP_ATOMIC4K
  <li> SQLITE_IOCAP_ATOMIC8K
  <li> SQLITE_IOCAP_ATOMIC16K
  <li> SQLITE_IOCAP_ATOMIC32K
  <li> SQLITE_IOCAP_ATOMIC64K
  <li> SQLITE_IOCAP_SAFE_APPEND
  <li> SQLITE_IOCAP_SEQUENTIAL
  </ul>
  The SQLITE_IOCAP_ATOMIC bit means that all writes to this device are
  atomic in the sense that either the entire write occurs or none of it
  occurs.  The other SQLITE_IOCAP_ATOMIC<i>nnn</i> values indicate that

  writes of aligned blocks of the indicated size are atomic.
  SQLITE_IOCAP_SAFE_APPEND means that when extending a file with new
  data, the new data is written first and then the file size is updated.
  So if a power failure occurs, there is no chance that the file might have
  been extended with randomness.  The SQLITE_IOCAP_SEQUENTIAL bit means
  that all writes occur in the order that they are issued and are not
  reordered by the underlying file system.
}

HEADING 3 {Checklist For Constructing A New VFS}

PARAGRAPH {
  The preceding paragraphs contain a lot of information.
  To ease the task of constructing
  a new VFS for SQLite we offer the following implementation checklist:
}

PARAGRAPH {
  <ol>
  <li> Define an appropriate subclass of the [sqlite3_file] object.
  <li> Implement the methods required by the [sqlite_io_methods] object.
  <li> Create a static and 
       constant [sqlite3_io_methods] object containing pointers
       to the methods from the previous step.
  <li> Implement the xOpen method that opens a file and populates an
       [sqlite3_file] object, including setting pMethods to
       point to the [sqlite3_io_methods] object from the previous step.
  <li> Implement the other methods required by [sqlite3_vfs].







|
|
|











|
|
|





|
|





|
|

|
<
<
<
<
<
|
|




|
|


















|

|
|

|


|


|
|
|
|









|
|
|
|
>
>
>
>
>
>
>
>
>
>
>



















|
|
|
|
|
|
|
|
|
|
|

|

|
>

|


|















|







578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617





618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
  contains pointers to other allocated memory or resources, those
  allocations should be released by the xClose method.
}

PARAGRAPH {
  The xRead method reads iAmt bytes from the file beginning at a byte
  offset to iOfst.  The data read is stored in the pointer of the
  second parameter.  xRead returns the [SQLITE_OK] on success,
  [SQLITE_IOERR_SHORT_READ] if it was not able to read the full number
  of bytes because it reached end-of-file, or [SQLITE_IOERR_READ] for
  any other error.
}

PARAGRAPH {
  The xWrite method writes iAmt bytes of data from the second parameter
  into the file beginning at an offset of iOfst bytes.  If the size of
  the file is less than iOfst bytes prior to the write, then xWrite should
  ensure that the file is extended with zeros up to iOfst bytes prior
  to beginning its write.  xWrite continues to extends the file as
  necessary so that the size of the file is at least iAmt+iOfst bytes 
  at the conclusion of the xWrite call.  The xWrite method returns
  [SQLITE_OK] on success.  If the write cannot complete because the
  underlying storage medium is full, then [SQLITE_FULL] is returned.
  [SQLITE_IOERR_WRITE] should be returned for any other error.
}

PARAGRAPH {
  The xTruncate method truncates a file to be nByte bytes in length.
  If the file is already nByte bytes or less in length then this
  method is a no-op.  The xTruncate method returns [SQLITE_OK] on
  success and [SQLITE_IOERR_TRUNCATE] if anything goes wrong.
}

PARAGRAPH {
  The xSync method is used to force previously written data out of
  operating system cache and into non-volatile memory.  The second
  parameter is usually [SQLITE_SYNC_NORMAL].  If the second parameter
  is [SQLITE_SYNC_FULL] then the xSync method should make sure that
  data has also been flushed through the disk controllers cache.
  The [SQLITE_SYNC_FULL] parameter is the equivalent of the F_FULLSYNC





  ioctl() on Mac OS X. The xSync method returns
  [SQLITE_OK] on success and [SQLITE_IOERR_FSYNC] if anything goes wrong.
}

PARAGRAPH {
  The xFileSize() method determines the current size of the file
  in bytes and writes that value into *pSize.  It returns [SQLITE_OK]
  on success and [SQLITE_IOERR_FSTAT] if something goes wrong.
}

PARAGRAPH {
  The xLock and xUnlock methods are used to set and clear file locks.
  SQLite supports five levels of file locks, in order:
  <ul>
  <li> [SQLITE_LOCK_NONE]
  <li> [SQLITE_LOCK_SHARED]
  <li> [SQLITE_LOCK_RESERVED]
  <li> [SQLITE_LOCK_PENDING]
  <li> [SQLITE_LOCK_EXCLUSIVE]
  </ul>
  The underlying implementation can support some subset of these locking
  levels as long as it meets the other requirements of this paragraph.
  The locking level is specified as the second argument to both xLock
  and xUnlock.  The xLock method increases the locking level to the
  specified locking level or higher.  The xUnlock method decreases the
  locking level to no lower than the level specified.  
  [SQLITE_LOCK_NONE] means that the file is unlocked.  [SQLITE_LOCK_SHARED]
  gives permission to read the file.  Multiple database connections can
  hold [SQLITE_LOCK_SHARED] at the same time.
  [SQLITE_LOCK_RESERVED] is like [SQLITE_LOCK_SHARED] in that its is permission
  to read the file.  But only a single connection can hold a reserved lock
  at any point in time.  The [SQLITE_LOCK_PENDING] is also permission to
  read the file.  Other connections can continue to read the file as well,
  but no other connection is allowed to escalate a lock from none to shared.
  [SQLITE_LOCK_EXCLUSIVE] is permission to write on the file.  Only a single
  connection can hold an exclusive lock and no other connection can hold
  any lock (other than "none") while one connection is hold an exclusive
  lock.  The xLock returns [SQLITE_OK] on success, [SQLITE_BUSY] if it
  is unable to obtain the lock, or [SQLITE_IOERR_RDLOCK] if something else
  goes wrong.  The xUnlock method returns [SQLITE_OK] on success and
  [SQLITE_IOERR_UNLOCK] for problems.
}

PARAGRAPH {
  The xCheckReservedLock method checks to see if another connection or
  another process is currently holding a reserved, pending, or exclusive
  lock on the file.  It returns true or false.
}

PARAGRAPH {
  The xFileControl() method is a generic interface that allows custom
  VFS implementations to directly control an open file using the
  (new and experimental)
  [sqlite3_file_control()] interface.  The second "op" argument
  is 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.  The SQLite
  core reserves opcodes less than 100 for its own use. 
  A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
  Applications that define a custom xFileControl method should use opcodes 
  greater than 100 to avoid conflicts.
}

PARAGRAPH {
  The xSectorSize returns the "sector size" of the underlying
  non-volatile media.  A "sector" is defined as the smallest unit of
  storage that can be written without disturbing adjacent storage.
  On a disk drive the "sector size" has until recently been 512 bytes,
  though there is a push to increase this value to 4KiB.  SQLite needs
  to know the sector size so that it can write a full sector at a
  time, and thus avoid corrupting adjacent storage space if a power
  lose occurs in the middle of a write.
}

PARAGRAPH {
  The xDeviceCharacteristics method returns an integer bit vector that
  defines any special properties that the underlying storage medium might
  have that SQLite can use to increase performance.  The allowed return
  is the bit-wise OR of the following values:
  <ul>
  <li> [SQLITE_IOCAP_ATOMIC]
  <li> [SQLITE_IOCAP_ATOMIC512]
  <li> [SQLITE_IOCAP_ATOMIC1K]
  <li> [SQLITE_IOCAP_ATOMIC2K]
  <li> [SQLITE_IOCAP_ATOMIC4K]
  <li> [SQLITE_IOCAP_ATOMIC8K]
  <li> [SQLITE_IOCAP_ATOMIC16K]
  <li> [SQLITE_IOCAP_ATOMIC32K]
  <li> [SQLITE_IOCAP_ATOMIC64K]
  <li> [SQLITE_IOCAP_SAFE_APPEND]
  <li> [SQLITE_IOCAP_SEQUENTIAL]
  </ul>
  The [SQLITE_IOCAP_ATOMIC] bit means that all writes to this device are
  atomic in the sense that either the entire write occurs or none of it
  occurs.  The other 
  [SQLITE_IOCAP_ATOMIC | SQLITE_IOCAP_ATOMIC<i>nnn</i>] values indicate that
  writes of aligned blocks of the indicated size are atomic.
  [SQLITE_IOCAP_SAFE_APPEND] means that when extending a file with new
  data, the new data is written first and then the file size is updated.
  So if a power failure occurs, there is no chance that the file might have
  been extended with randomness.  The [SQLITE_IOCAP_SEQUENTIAL] bit means
  that all writes occur in the order that they are issued and are not
  reordered by the underlying file system.
}

HEADING 3 {Checklist For Constructing A New VFS}

PARAGRAPH {
  The preceding paragraphs contain a lot of information.
  To ease the task of constructing
  a new VFS for SQLite we offer the following implementation checklist:
}

PARAGRAPH {
  <ol>
  <li> Define an appropriate subclass of the [sqlite3_file] object.
  <li> Implement the methods required by the [sqlite3_io_methods] object.
  <li> Create a static and 
       constant [sqlite3_io_methods] object containing pointers
       to the methods from the previous step.
  <li> Implement the xOpen method that opens a file and populates an
       [sqlite3_file] object, including setting pMethods to
       point to the [sqlite3_io_methods] object from the previous step.
  <li> Implement the other methods required by [sqlite3_vfs].
864
865
866
867
868
869
870
871
872
873
874

875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
  The argument to [sqlite3_mutex_alloc()] should be 
  [SQLITE_MUTEX_FAST] or [SQLITE_MUTEX_RECURSIVE] for non-recursive
  and recursive mutexes, respectively.  If the underlying system does
  not provide non-recursive mutexes, then a recursive mutex can be
  substituted in that case.  The argument to [sqlite3_mutex_alloc()]
  can also be a constant designating one of several static mutexes:
  <ul>
  <li>  SQLITE_MUTEX_STATIC_MASTER
  <li>  SQLITE_MUTEX_STATIC_MEM
  <li>  SQLITE_MUTEX_STATIC_MEM2
  <li>  SQLITE_MUTEX_STATIC_PRNG

  </ul>
  These static mutexes are reserved for use internally by SQLite
  and should not be used by the application.  The static mutexes
  are all non-recursive.
}

PARAGRAPH {
  The [sqlite3_mutex_free()] routine should be used to deallocate
  a non-static mutex.  If a static mutex is passed to this routine
  then the behavior is undefined.
}

PARAGRAPH {
  The [sqlite3_mutex_enter()] attempts to enter the mutex and blocks
  if another threads is already there.  [sqlite3_mutex_try()] attempts
  to enter and returns SQLITE_OK on success or SQLITE_BUSY if another
  thread is already there.  [sqlite3_mutex_leave()] exits a mutex.
  The mutex is held until the number of exits matches the number of
  entrances.  If [sqlite3_mutex_leave()] is called on a mutex that 
  the thread is not currently holding, then the behavior is undefined.
  If any routine is called for a deallocated mutex, then the behavior
  is undefined.
}







|
|
|
|
>















|







897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
  The argument to [sqlite3_mutex_alloc()] should be 
  [SQLITE_MUTEX_FAST] or [SQLITE_MUTEX_RECURSIVE] for non-recursive
  and recursive mutexes, respectively.  If the underlying system does
  not provide non-recursive mutexes, then a recursive mutex can be
  substituted in that case.  The argument to [sqlite3_mutex_alloc()]
  can also be a constant designating one of several static mutexes:
  <ul>
  <li>  [SQLITE_MUTEX_STATIC_MASTER]
  <li>  [SQLITE_MUTEX_STATIC_MEM]
  <li>  [SQLITE_MUTEX_STATIC_MEM2]
  <li>  [SQLITE_MUTEX_STATIC_PRNG]
  <li>  [SQLITE_MUTEX_STATIC_LRU]
  </ul>
  These static mutexes are reserved for use internally by SQLite
  and should not be used by the application.  The static mutexes
  are all non-recursive.
}

PARAGRAPH {
  The [sqlite3_mutex_free()] routine should be used to deallocate
  a non-static mutex.  If a static mutex is passed to this routine
  then the behavior is undefined.
}

PARAGRAPH {
  The [sqlite3_mutex_enter()] attempts to enter the mutex and blocks
  if another threads is already there.  [sqlite3_mutex_try()] attempts
  to enter and returns [SQLITE_OK] on success or [SQLITE_BUSY] if another
  thread is already there.  [sqlite3_mutex_leave()] exits a mutex.
  The mutex is held until the number of exits matches the number of
  entrances.  If [sqlite3_mutex_leave()] is called on a mutex that 
  the thread is not currently holding, then the behavior is undefined.
  If any routine is called for a deallocated mutex, then the behavior
  is undefined.
}
Changes to www/changes.tcl.
23
24
25
26
27
28
29


























30
31
32
33
34
35
36
  }
  puts "<DT><B>$date</B></DT>"
  regsub -all {[Tt]icket #(\d+)} $desc \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} desc
  puts "<DD><P><UL>$desc</UL></P>"
  puts "</DD>"
}



























chng {2007 August 13 (3.4.2)} {
<li>Fix a database corruption bug that might occur if a ROLLBACK command
is executed in <a href="pragma.html#pragma_auto_vacuum">auto-vacuum mode</a>
and a very small <a href="capi3ref.html#sqlite3_soft_heap_limit">
soft_heap_limit</a> is set. 
<a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">Ticket #2565</a>.







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
  }
  puts "<DT><B>$date</B></DT>"
  regsub -all {[Tt]icket #(\d+)} $desc \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} desc
  puts "<DD><P><UL>$desc</UL></P>"
  puts "</DD>"
}


chng {2007 Sep 3 (3.5.0 beta)} {
<li>Redesign the OS interface layer.  See
    <a href="34to35.html">34to35.html</a> for details.
    <font color="red">*** Potentially incompatible change ***</font>
<li>The <a href="capi3ref.html#sqlite3_release_memory">
    sqlite3_release_memory()</a>,
    <a href="capi3ref.html#sqlite3_soft_heap_limit">
    sqlite3_soft_heap_limit()</a>,
    and <a href="capi3ref.html#sqlite3_enable_shared_cache">
    sqlite3_enable_shared_cache()</a> interfaces now work cross all
    threads in the process, not just the single thread in which they
    are invoked.
    <font color="red">*** Potentially incompatible change ***</font>
<li>Added the 
    <a href="capi3ref.html#sqlite3_open_v2">sqlite3_open_v2()</a>
    interface.  
<li>Reimplemented the memory allocation subsystem and made it 
    replacable at compile-time.
<li>Created a new mutex subsystem and made it replacable at
    compile-time.
<li>The same database connection may now be used simultaneously by
    separate threads.
}


chng {2007 August 13 (3.4.2)} {
<li>Fix a database corruption bug that might occur if a ROLLBACK command
is executed in <a href="pragma.html#pragma_auto_vacuum">auto-vacuum mode</a>
and a very small <a href="capi3ref.html#sqlite3_soft_heap_limit">
soft_heap_limit</a> is set. 
<a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">Ticket #2565</a>.
Changes to www/formatchng.tcl.
1
2
3
4
5
6
7
8
9
10
11
#
# Run this Tcl script to generate the formatchng.html file.
#
set rcsid {$Id: formatchng.tcl,v 1.19 2006/08/12 14:38:47 drh Exp $ }
source common.tcl
header {File Format Changes in SQLite}
puts {
<h2>File Format Changes in SQLite</h2>

<p>
Every effort is made to keep SQLite fully backwards compatible from



|







1
2
3
4
5
6
7
8
9
10
11
#
# Run this Tcl script to generate the formatchng.html file.
#
set rcsid {$Id: formatchng.tcl,v 1.20 2007/09/03 20:32:45 drh Exp $ }
source common.tcl
header {File Format Changes in SQLite}
puts {
<h2>File Format Changes in SQLite</h2>

<p>
Every effort is made to keep SQLite fully backwards compatible from
248
249
250
251
252
253
254













255
256
257
258
259
260
261
  is used by default instead of the new.  This might change
  again in some future release - we may go back to generating
  the new file format by default - but probably not until
  all users have upgraded to a version of SQLite that will
  understand the new file format.  That might take several
  years.</p></td>
</tr>













</table>
</blockquote>

<p>
To perform a database reload, have ready versions of the
<b>sqlite</b> command-line utility for both the old and new
version of SQLite.  Call these two executables "<b>sqlite-old</b>"







>
>
>
>
>
>
>
>
>
>
>
>
>







248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
  is used by default instead of the new.  This might change
  again in some future release - we may go back to generating
  the new file format by default - but probably not until
  all users have upgraded to a version of SQLite that will
  understand the new file format.  That might take several
  years.</p></td>
</tr>
<tr>
  <td valign="top">3.4.2 to 3.5.0</td>
  <td valign="top">2007-Sep-3</td>
  <td><p>The design of the OS interface layer was changed for
  release 3.5.0.  Applications that implemented a custom OS
  interface will need to be modified in order to upgrade.
  There are also some subtly different semantics a few obscure
  APIs.  An <a href="34to35.html">article</a> is avilable which
  describing the changes in detail.</p>

  <p>The on-disk file format is unchanged.</p>
  </td>
</tr>
</table>
</blockquote>

<p>
To perform a database reload, have ready versions of the
<b>sqlite</b> command-line utility for both the old and new
version of SQLite.  Call these two executables "<b>sqlite-old</b>"
Changes to www/index.tcl.
66
67
68
69
70
71
72














73
74
75
76
77
78
79

proc newsitem {date title text} {
  puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  puts "<p>$txt</p>"
  puts "<hr width=\"50%\">"
}















newsitem {2007-Aug-13} {Version 3.4.2} {
  While stress-testing the 
  <a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>
  feature, a bug that could lead to
  <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">database
  corruption</a> was <a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">







>
>
>
>
>
>
>
>
>
>
>
>
>
>







66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

proc newsitem {date title text} {
  puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  puts "<p>$txt</p>"
  puts "<hr width=\"50%\">"
}

newsitem {2007-Sep-3} {Version 3.5.0 beta} {
  The OS interface layer and the memory allocation subsystems in
  SQLite have been reimplemented.  The published API is largely unchanged
  but the (unpublished) OS interface has been modified extensively.  
  Application that implement their own OS interface will require
  modification.  See
  <a href="34to35.html">34to35.html</a> for details.<p>

  This is a large change approximately 1 line of count of out 10 was
  modified.  We are calling this first release "beta" in order to give
  the user community time to test and evaluate the changes before we
  freeze the new design.
}

newsitem {2007-Aug-13} {Version 3.4.2} {
  While stress-testing the 
  <a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>
  feature, a bug that could lead to
  <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">database
  corruption</a> was <a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">
121
122
123
124
125
126
127
128
  for additional information.
}

puts {
<p align="right"><a href="oldnews.html">Old news...</a></p>
</td></tr></table>
}
footer {$Id: index.tcl,v 1.159 2007/08/13 16:15:29 drh Exp $}







|
135
136
137
138
139
140
141
142
  for additional information.
}

puts {
<p align="right"><a href="oldnews.html">Old news...</a></p>
</td></tr></table>
}
footer {$Id: index.tcl,v 1.160 2007/09/03 20:32:46 drh Exp $}