Documentation Source Text

Check-in [e63c0ce4fb]
Login

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

Overview
Comment:Edits to the VFS documentation. Better cross-referencing to VFS.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: e63c0ce4fb1d824ffcac9360ecc6f24cc854c341
User & Date: drh 2011-05-23 19:04:56
Context
2011-05-24
00:44
Restrict website search text to omit non-alphanumeric characters. check-in: 2528553d5a user: drh tags: trunk
2011-05-23
19:04
Edits to the VFS documentation. Better cross-referencing to VFS. check-in: e63c0ce4fb user: drh tags: trunk
2011-05-20
23:21
Further tightening of the validity rules for valid HTTP requests in althttpd.c. check-in: 73bc374298 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/atomiccommit.in.

    83     83   never start writing a sector in the middle and work towards the
    84     84   ends.  We do not know if this assumption is always true but it
    85     85   seems reasonable.</p>
    86     86   
    87     87   <p>The previous paragraph states that SQLite does not assume that
    88     88   sector writes are atomic.  This is true by default.  But as of
    89     89   SQLite version 3.5.0, there is a new interface called the
    90         -Virtual File System (VFS) interface.  The VFS is the only means
           90  +Virtual File System ([VFS]) interface.  The [VFS] is the only means
    91     91   by which SQLite communicates to the underlying filesystem.  The
    92     92   code comes with default VFS implementations for Unix and Windows
    93     93   and there is a mechanism for creating new custom VFS implementations
    94     94   at runtime.  In this new VFS interface there is a method called
    95     95   xDeviceCharacteristics.  This method interrogates the underlying
    96     96   filesystem to discover various properties and behaviors that the
    97     97   filesystem may or may not exhibit.  The xDeviceCharacteristics
................................................................................
   122    122   file space originally contains garbage and then later is filled in
   123    123   with the data actually written.  In other words, SQLite assumes that
   124    124   the file size is updated before the file content.  This is a 
   125    125   pessimistic assumption and SQLite has to do some extra work to make
   126    126   sure that it does not cause database corruption if power is lost
   127    127   between the time when the file size is increased and when the
   128    128   new content is written.  The xDeviceCharacteristics method of
   129         -the VFS might indicate that the filesystem will always write the
          129  +the [VFS] might indicate that the filesystem will always write the
   130    130   data before updating the file size.  (This is the 
   131    131   SQLITE_IOCAP_SAFE_APPEND property for those readers who are looking
   132    132   at the code.)  When the xDeviceCharacteristics method indicates
   133    133   that files content is written before the file size is increased,
   134    134   SQLite can forego some of its pedantic database protection steps
   135    135   and thereby decrease the amount of disk I/O needed to perform a
   136    136   commit.  The current implementation, however, makes no such assumptions

Changes to pages/compile.in.

   371    371   
   372    372       <li> No locking style. If none of the above can be supported, this 
   373    373            locking style is used. No database locking mechanism is used. When
   374    374            this system is used it is not safe for a single database to be
   375    375            accessed by multiple clients.
   376    376     </ul>
   377    377   
   378         -  Additionally, five extra VFS implementations are provided as well as the
          378  +  Additionally, five extra [VFS] implementations are provided as well as the
   379    379     default. By specifying one of the extra VFS implementations 
   380    380     when calling [sqlite3_open_v2()], an application may bypass the file-system
   381    381     detection logic and explicitly select one of the above locking styles. The
   382         -  five extra VFS implementations are called "unix-posix", "unix-afp",
          382  +  five extra [VFS] implementations are called "unix-posix", "unix-afp",
   383    383     "unix-flock", "unix-dotfile" and "unix-none".
   384    384   }
   385    385   
   386    386   COMPILE_OPTION {SQLITE_ENABLE_MEMORY_MANAGEMENT} {
   387    387     This option adds extra logic to SQLite that allows it to release unused
   388    388     memory upon request.  This option must be enabled in order for the
   389    389     [sqlite3_release_memory()] interface to work.  If this compile-time

Changes to pages/fileformat2.in.

   360    360   that contains the bytes at offsets between 1073741824 and 1073742335,
   361    361   inclusive.  A database file that is less than or equal to 1073741824 bytes 
   362    362   in size contains no lock-byte page.  A database file larger than
   363    363   1073741824 contains exactly one lock-byte page.
   364    364   </p>
   365    365   
   366    366   <p>The lock-byte page is set aside for use by the operating-system specific
   367         -VFS implementation in implementing the database file locking primitives.
          367  +[VFS] implementation in implementing the database file locking primitives.
   368    368   ^SQLite does not use the lock-byte page.  ^The SQLite core 
   369         -will never read or write, though operating-system specific VFS 
          369  +will never read or write, though operating-system specific [VFS] 
   370    370   implementations may choose to read or write bytes on the lock-byte 
   371    371   page according to the 
   372    372   needs and proclivities of the underlying system.  The unix and win32
   373         -VFS implementations that come built into SQLite do not write to the
          373  +[VFS] implementations that come built into SQLite do not write to the
   374    374   lock-byte page, but third-party VFS implementations for
   375    375   other operating systems might.</p>
   376    376   
   377    377   <tcl>hd_fragment {freelist} {freelist} {free-page list}</tcl>
   378    378   <h3>1.4 The Freelist</h3>
   379    379   
   380    380   <p>A database file might contain one or more pages that are not in

Changes to pages/pragma.in.

   743    743       <p>^(<b>PRAGMA synchronous;
   744    744          <br>PRAGMA synchronous = </b>
   745    745             <i>0 | OFF | 1 | NORMAL | 2 | FULL</i><b>;</b></p>
   746    746   
   747    747       <p>Query or change the setting of the "synchronous" flag.)^
   748    748       ^The first (query) form will return the synchronous setting as an 
   749    749       integer.  ^When synchronous is FULL (2), the SQLite database engine will
   750         -    use the xSync method of the VFS to ensure that all content is safely
          750  +    use the xSync method of the [VFS] to ensure that all content is safely
   751    751       written to the disk surface prior to continuing.
   752    752       This ensures that an operating system crash or power failure will
   753    753       not corrupt the database.
   754    754       FULL synchronous is very safe, but it is also slower. 
   755    755       ^When synchronous is NORMAL (1), the SQLite database
   756    756       engine will still sync at the most critical moments, but less often
   757    757       than in FULL mode.  There is a very small (though non-zero) chance that

Changes to pages/selfcontained.in.

    33     33   The date and time SQL functions provided by SQLite require
    34     34   some additional C library support, but those functions can
    35     35   be also be omitted from the build using compile-time options.
    36     36   </p>
    37     37   
    38     38   <p>
    39     39   Communications between SQLite and the operating system and disk are
    40         -mediated through an interchangeable 
    41         -[sqlite3_vfs | Virtual File System (VFS)] layer.
           40  +mediated through an interchangeable [VFS] layer.
    42     41   VFS modules for Unix (Linux and Mac OS X), OS/2, and Windows (Win32 and WinCE)
    43     42   are provided in the source tree.  It is a simple matter to devise an
    44     43   alternative VFS for embedded devices.
    45     44   </p>
    46     45   
    47     46   <p>
    48     47   For safe operation in multi-threaded environments, SQLite requires

Changes to pages/testing.in.

   296    296   course, and so crash testing is done in simulation.  An alternative
   297    297   [sqlite3_vfs | Virtual File System] is inserted that allows the test
   298    298   harness to simulate the state of the database file following a crash.</p>
   299    299   
   300    300   <p>In the TCL test harness, the crash simulation is done in a separate
   301    301   process.  The main testing process spawns a child process which runs
   302    302   some SQLite operation and randomly crashes somewhere in the middle of
   303         -a write operation.  A special VFS randomly reorders and corrupts
          303  +a write operation.  A special [VFS] randomly reorders and corrupts
   304    304   the unsynchronized
   305    305   write operations to simulate the effect of buffered filesystems.  After
   306    306   the child dies, the original test process opens and reads the test
   307    307   database and verifies that the changes attempted by the child either
   308    308   completed successfully or else were completely rolled back.  The
   309    309   [integrity_check] [PRAGMA] is used to make sure no database corruption
   310    310   occurs.</p>
   311    311   
   312    312   <p>The TH3 test harness needs to run on embedded systems that do not
   313    313   necessarily have the ability to spawn child processes, so it uses
   314         -an in-memory VFS to simulate crashes.  The in-memory VFS can be rigged
          314  +an in-memory [VFS] to simulate crashes.  The in-memory [VFS] can be rigged
   315    315   to make a snapshot of the entire filesystem after a set number of I/O
   316    316   operations.  Crash tests run in a loop.  On each iteration of the loop,
   317    317   the point at which a snapshot is made is advanced until the SQLite
   318    318   operations being tested run to completion without ever hitting a
   319    319   snapshot.  Within the loop, after the SQLite operation under test has
   320    320   completed, the filesystem is reverted to the snapshot and random file
   321    321   damage is introduced that is characteristic of the kinds of damage
................................................................................
   420    420   
   421    421   <p>The SQLite core has 100% branch test coverage under [TH3] as of
   422    422   2009-07-25, in its default configuration as measured by
   423    423   [http://gcc.gnu.org/onlinedocs/gcc/Gcov.html | gcov]
   424    424   utility on SuSE Linux 10.1 on x86 hardware with the GCC 4.0.1 compiler.</p>
   425    425   
   426    426   <p>The "SQLite core" in the previous paragraph excludes the
   427         -operating-system dependent [sqlite3_vfs | VFS] backends, since it is
          427  +operating-system dependent [VFS] backends, since it is
   428    428   not possible to write cross-platform tests for those modules.  Extensions
   429    429   such as FTS3 and RTree are also excluded from the analysis.</p>
   430    430   
   431    431   <tcl>hd_fragment stmtvbr</tcl>
   432    432   <h3>7.1 Statement versus branch coverage</h3>
   433    433   
   434    434   <p>There are many ways to measure test coverage.  The most popular
................................................................................
   708    708   <tcl>hd_fragment journaltest</tcl>
   709    709   <h3>8.5 Journal Tests</h3>
   710    710   
   711    711   <p>One of the things that SQLite does to ensure that transactions
   712    712   are atomic across system crashes and power failures is to write
   713    713   all changes into the rollback journal file prior to changing the
   714    714   database.  The TCL test harness contains an alternative
   715         -[sqlite3_vfs | Virtual File System ] implementation that helps to
          715  +[OS backend] implementation that helps to
   716    716   verify this is occurring correctly.  The "journal-test VFS" monitors
   717    717   all disk I/O traffic between the database file and rollback journal,
   718    718   checking to make sure that nothing is written into the database
   719    719   file which has not first been written and synced to the rollback journal.
   720    720   If any discrepancies are found, an assertion fault is raised.</p>
   721    721   
   722    722   <p>The journal tests are an additional double-check over and above

Changes to pages/th3.in.

    23     23        errors, and power loss during transaction commit. </p></li>
    24     24   
    25     25   <li><p> TH3 exercises SQLite in a variety of run-time configurations
    26     26        (UTF8 vs UTF16, different pages sizes, varying journal modes, etc.)
    27     27        </p></li>
    28     28   
    29     29   <li><p> TH3 achieves 100% branch test coverage over SQLite core.
    30         -    (Test coverage of the operating-system specific VFSes and extensions
           30  +    (Test coverage of the operating-system specific [VFSes] and extensions
    31     31       such as FTS and RTREE is less than 100%). </p></li>
    32     32   </ul>
    33     33   
    34     34   <p>TH3 was originally written for validation testing only, but has
    35     35   subsequently been used for development testing and debugging
    36     36   as well, and has proven very helpful in those roles.  A full-coverage
    37     37   test run for TH3 takes less than 10 minutes on a workstation and hence

Changes to pages/vfs.in.

     3      3   
     4      4   <h1 align="center">
     5      5   The SQLite OS Interface or "VFS"
     6      6   </h1>
     7      7   
     8      8   <p>
     9      9   This article describes the SQLite OS portability layer or "VFS" - the
    10         -thin module that is at the bottom of the SQLite implementation stack
    11         -and which provides portability across operating systems.
           10  +module at the bottom of the SQLite implementation stack
           11  +that provides portability across operating systems.
    12     12   </p>
    13     13   
    14     14   <img src="images/vfs1.gif" align="right" hspace="10">
    15     15   <h2>1.0 The VFS In Relation To The Rest Of SQLite</h2>
    16     16   
    17     17   <p>
    18         -The internal organization of the SQLite library can be viewed as a
    19         -stack of modules such as shown to the right.
           18  +The internal organization of the SQLite library can be viewed as the
           19  +stack of modules shown to the right.
    20     20   The Tokenizer, Parser, and Code Generator components are used to
    21     21   process SQL statements and convert them into executable programs 
    22     22   in a virtual machine language or byte code.
    23     23   Roughly speaking, these top three layers implement
    24     24   [sqlite3_prepare_v2()].  The byte code generated by the top three
    25     25   layers is a [prepared statement].
    26     26   The Virtual Machine module is responsible for running the SQL statement 
................................................................................
    38     38   
    39     39   <p>
    40     40   This article is about the bottom layer.
    41     41   </p>
    42     42   
    43     43   <p>The OS Interface - also called the "VFS" - is what makes SQLite 
    44     44   portable across operating systems.  Whenever any of the other modules
    45         -in SQLite needs to communicate with the filesystem, or the operating
    46         -system, they invoke methods in the VFS to communicate with the 
    47         -operating system on their behalf.  Hence, porting SQLite to a new
           45  +in SQLite needs to communicate with the operating
           46  +system, they invoke methods in the VFS.  The VFS then invokes the
           47  +operating-specific code needed to satisfy the request.
           48  +Hence, porting SQLite to a new
    48     49   operating system is simply a matter of writing a new OS interface layer
    49     50   or "VFS".</p>
    50     51   
    51     52   <h2>2.0 Multiple VFSes</h2>
    52     53   
    53     54   <p>
    54     55   The standard SQLite source tree contains built-in VFSes for os/2, unix,
................................................................................
    59     60   
    60     61   <p>
    61     62   Multiple VFSes can be registered at the same time.
    62     63   Each VFS has a unique names.
    63     64   Separate [database connections] within the same process can be using
    64     65   different VFSes at the same time.   For that matter, if a single
    65     66   database connection has multiple database files open using
    66         -the [ATTACH] command, then each database might be using a
           67  +the [ATTACH] command, then each attached database might be using a
    67     68   different VFS.
    68     69   </p>
    69     70   
    70     71   <p>
    71     72   Unix builds come with multiple VFSes built-in.  The default VFS
    72         -for unix is called "unix" and is what is used in an overwhelming
           73  +for unix is called "unix" and is the VFS used in an overwhelming
    73     74   majority of applications.  Other VFSes that can be found in unix
    74     75   may include:
    75     76   </p>
    76     77   
    77     78   <ol>
    78     79   <li><p><b>unix-dotfile</b> - uses dot-file locking rather than
    79     80             POSIX advisory locks.
................................................................................
    84     85   <li><p><b>unix-none</b> - all file locking operations are no-ops.
    85     86   <li><p><b>unix-namedsem</b> - uses named semaphores for file locking.
    86     87          VXWorks only.
    87     88   </ol>
    88     89   
    89     90   <p>
    90     91   The various unix VFSes differ only in the way they handle file locking -
    91         -they share most of the implementation in common with one another and
    92         -are all located in the same SQLite source file:  "<tt>os_unix.c</tt>".
    93         -Note that because they do use different locking strategies, they are
    94         -subtle imcompatible with one another.  If two processes are accessing
    95         -the same SQLite database using different unix VFSes, they will probably
           92  +they share most of their implementation in common with one another and
           93  +are all located in the same SQLite source file:  
           94  +[http://www.sqlite.org/src/doc/trunk/src/os_unix.c | os_unix.c].
           95  +Note that except for "unix" and "unix-excl", the various unix VFSes all
           96  +use incompatible locking implementations.  If two processes are accessing
           97  +the same SQLite database using different unix VFSes, they may
    96     98   not see each others locks and may end up interfering with one another,
    97     99   resulting in database corruption.  The "unix-none" VFS in particular
    98    100   does no locking at all and will easily result in database corruption if
    99         -used to access a database by two or more database connections at a time.
          101  +used by two or more database connections at the same time.
          102  +Programmers are encouraged to use only "unix" or "unix-excl" unless
          103  +there is a compelling reason to do otherwise.
   100    104   </p>
   101    105   
   102    106   <h2>2.1 Specifying Which VFS To Use</h2>
   103    107   
   104    108   <p>
   105    109   There is always one VFS which is the default VFS.  On unix systems,
   106    110   the "unix" VFS comes up as the default and on windows it is "win32".
................................................................................
   107    111   If no other actions are taken, new database connections will make use
   108    112   of the default VFS.
   109    113   </p>
   110    114   
   111    115   <p>
   112    116   The default VFS can be changed by registering or re-registering the
   113    117   VFS using the [sqlite3_vfs_register()] interface with a second parameter
   114         -of 1.  Hence, of a (unix) process to make the "unix-nolock" VFS the
   115         -default in place of "unix", the following code would work:
          118  +of 1.  Hence, if a (unix) process to always use the "unix-nolock" VFS 
          119  +in place of "unix", the following code would work:
   116    120   </p>
   117    121   
   118    122   <blockquote><pre>
   119    123   sqlite3_vfs_register(sqlite3_vfs_find("unix-nolock"), 1);
   120    124   </pre></blockquote>
   121    125   
   122    126   <p>
................................................................................
   145    149   a VFS specified as the fourth argument to [sqlite3_open_v2()].  The
   146    150   default VFS is used if no VFS is specified otherwise.
   147    151   </p>
   148    152   
   149    153   <h2>2.2 VFS Shims</h2>
   150    154   
   151    155   <p>
   152         -From the point of view of the uppers layers of the SQLite stack, there
   153         -is only one VFS in use at a time.  But in practice, a particular VFS might
   154         -just be a thin wrapper around another VFS does the real work.
          156  +From the point of view of the uppers layers of the SQLite stack, each
          157  +open database file uses exactly one VFS.
          158  +But in practice, a particular VFS might
          159  +just be a thin wrapper around another VFS that does the real work.
   155    160   We call a wrapper VFS a "shim".
   156    161   </p>
   157    162   
   158    163   <p>
   159    164   A simple example of a shim is the "vfstrace" VFS.  This is a VFS
   160         -(imnplemented in the 
   161         -[http://www.sqlite.org/src/finfo?name=src/test_vfstrace.c | test_vfstrace.c]
          165  +(implemented in the 
          166  +[http://www.sqlite.org/src/doc/trunk/src/test_vfstrace.c | test_vfstrace.c]
   162    167   source file) that writes a message associated with each VFS method call
   163    168   into a log file, then passes control off to another VFS to do the actual
   164    169   work.
   165    170   </p>
   166    171   
   167    172   <h2>2.3 Other Example VFSes</h2>
   168    173   
................................................................................
   169    174   <p>
   170    175   The following are other VFS implementations available in the public
   171    176   SQLite source tree:
   172    177   </p>
   173    178   
   174    179   <ul>
   175    180   <li><p>
   176         -<b>test_demovfs.c</b> -
          181  +[http://www.sqlite.org/src/doc/trunk/src/test_demovfs.c | test_demovfs.c] - 
   177    182   This file implements a very simple VFS named "demo" that uss POSIX 
   178    183   functions such as
   179    184   open(), read(), write(), fsync(), close(), fsync(), sleep(), time(),
   180    185   and so forth.  This VFS only works on unix systems.  But it is not
   181    186   intended as a replacement for the standard "unix" VFS used by default
   182    187   on unix platforms.  The "demo" VFS is deliberately kept very simple
   183    188   so that it can be used as a learning aid or as template for building
   184    189   other VFSes or for porting SQLite to new operating systems.
   185    190   
   186    191   <li><p>
   187         -<b>test_quota.c</b> -
          192  +[http://www.sqlite.org/src/doc/trunk/src/test_quota.c | test_quota.c] - 
   188    193   This file implements a shim called "quota" that enforces cumulative
   189    194   file size limits on a collection of database files.  An auxiliary
   190    195   interface is used to define "quote groups".  A quota group is a
   191    196   set of files (database files, journals, and temporary files) whose
   192    197   names all match a [GLOB] pattern.  The sum of the sizes of all files
   193    198   in each quota group is tracked, and if that sum exceeds a threshold
   194    199   defined for the quota group, a callback function is invoked.  That
   195    200   callback can either increase the threshold or cause the operation
   196    201   that would have exceeded the quota to fail with an 
   197    202   [SQLITE_FULL] error.  One of the uses of this shim is used to enforce 
   198    203   resource limits on application databases in Firefox.
   199    204   
   200    205   <li><p>
   201         -<b>test_multiplex.c</b> -
          206  +[http://www.sqlite.org/src/doc/trunk/src/test_multiplex.c | test_multiplex.c] - 
   202    207   This file implements a shim that allows database files to exceed the
   203    208   maximum file size of the underlying filesystem.  This shim presents
   204    209   an interface to the upper six layers of SQLite that makes it look like
   205    210   very large files are being used, when in reality each such large file
   206    211   is split up into many smaller files on the underlying system.
   207    212   This shim has been used, for example, to allow databases to grow
   208    213   larger than 2 gibibytes on FAT16 filesystems.
   209    214   
   210    215   <li><p>
   211         -<b>test_onefile.c</b> -
          216  +[http://www.sqlite.org/src/doc/trunk/src/test_onefile.c | test_onefile.c] - 
   212    217   This file implements a demonstration VFS named "fs" that shows how SQLite 
   213    218   can be used on an embedded device that lacks a filesystem.  Content is
   214    219   written directly to the underlying media.  A VFS derived from this
   215    220   demonstration code could be used by a gadget with a limited amount of
   216    221   flash memory to make SQLite behave as the filesystem for the flash memory
   217    222   on the device.
   218    223   
   219    224   <li><p>
   220         -<b>test_journal.c</b> -
          225  +[http://www.sqlite.org/src/doc/trunk/src/test_journal.c | test_journal.c] - 
   221    226   This file implements a shim used during SQLite testing that verifies that
   222    227   the database and rollback journal are written in the correct order and
   223    228   are "synced" at appropriate times in order to guarantee that the database
   224    229   can recover from a power lose are hard reset at any time.  The shim
   225    230   checks several invariants on the operation of databases and rollback
   226    231   journals and raises exceptions if any of those invariants are violated.
   227    232   These invariants, in turn, assure that the database is always recoverable.
   228    233   Running a large suite of test cases using this shim provides added
   229    234   assurance that SQLite databases will not be damaged by unexpected
   230    235   power failures or device resets.
   231    236   
   232    237   <li><p>
   233         -<b>test_vfs.c</b> -
          238  +[http://www.sqlite.org/src/doc/trunk/src/test_vfs.c | test_vfs.c] - 
   234    239   This file implements a shim that can be used to simulate filesystem faults.
   235    240   This shim is used during testing to verify that SQLite responses sanely
   236    241   to hardware malfunctions or to other error conditions such as running out
   237    242   of filesystem space that are difficult to test on a real system.
   238    243   </ul>
   239    244   
   240    245   <p>

Changes to pages/wal.in.

    20     20   <li>WAL uses many fewer fsync() operations and is thus less vulnerable to
    21     21       problems on systems where the fsync() system call is broken.
    22     22   </ol>
    23     23   
    24     24   <p>But there are also disadvantages:</p>
    25     25   
    26     26   <ol>
    27         -<li>WAL normally requires that the [sqlite3_vfs | VFS] 
    28         -    supports shared-memory primitives.
           27  +<li>WAL normally requires that the [VFS] 
           28  +    support shared-memory primitives.
    29     29       (Exception: [WAL without shared memory])
    30     30       The built-in unix and windows VFSes
    31     31       support this but third-party extension VFSes for custom operating
    32     32       systems might not.
    33     33   <li>All processes using a database must be on the same host computer;
    34     34       WAL does not work over a network filesystem.
    35     35   <li>Transactions that involve changes against multiple [ATTACH | ATTACHed]
................................................................................
   243    243   
   244    244   <blockquote><pre>
   245    245   PRAGMA journal_mode=WAL;
   246    246   </pre></blockquote>
   247    247   
   248    248   <p>The journal_mode pragma returns a string which is the new journal mode.
   249    249   On success, the pragma will return the string "<tt>wal</tt>".  If 
   250         -the conversion to WAL could not be completed (for example, if the VFS
          250  +the conversion to WAL could not be completed (for example, if the [VFS]
   251    251   does not support the necessary shared-memory primitives) then the
   252    252   journaling mode will be unchanged and the string returned from the
   253    253   primitive will be the prior journaling mode (for example "<tt>delete</tt>").
   254    254   
   255    255   <a name="how_to_checkpoint"></a>
   256    256   <h3>Automatic Checkpoint</h3>
   257    257   
................................................................................
   309    309   operations.</p>
   310    310   
   311    311   <p>An efficient implementation of the [WAL read algorithm] requires that
   312    312   there exist a hash table in shared memory over the content of the WAL file.
   313    313   This hash table is called the [wal-index].
   314    314   The wal-index is in shared memory, and so technically it does not have 
   315    315   to have a name in the host computer filesystem.  Custom
   316         -[sqlite3_vfs | VFS] implementations are free to implement shared 
          316  +[VFS] implementations are free to implement shared 
   317    317   memory in any way they see fit, but the default unix and windows 
   318    318   drivers that come built-in with SQLite implement shared memory
   319    319   using <a href="http://en.wikipedia.org/wiki/Mmap">mmapped files</a>
   320    320   named using the suffix "<tt>-shm</tt>" and
   321    321   located in the same directory as the database file.  The wal-index must
   322    322   be rebuilt upon first access, even by readers, and so in order to open
   323    323   the WAL database, write access is required on the "<tt>-shm</tt>" shared
................................................................................
   361    361   think this is a major concern since the wal-index rarely exceeds
   362    362   32 KiB in size and is never synced.  Furthermore, the wal-index 
   363    363   backing file is deleted when the last database connection disconnects,
   364    364   which often prevents any real disk I/O from ever happening.</p>
   365    365   
   366    366   <p>Specialized applications for which the default implementation of
   367    367   shared memory is unacceptable can devise alternative methods via a
   368         -custom [sqlite3_vfs | VFS].  
          368  +custom [VFS].  
   369    369   For example, if it is known that a particular database
   370    370   will only be accessed by threads within a single process, the wal-index
   371    371   can be implemented using heap memory instead of true shared memory.</p>
   372    372   
   373    373   <tcl>hd_fragment noshm {WAL without shared memory}</tcl>
   374    374   <h2>Use of WAL Without Shared-Memory</h2>
   375    375   
................................................................................
   376    376   <p>Beginning in SQLite version 3.7.4, ^WAL databases can be created, read, and
   377    377   written even if shared memory is unavailable as long as the
   378    378   [locking_mode] is set to EXCLUSIVE before the first attempted access.
   379    379   In other words, a process can interact with
   380    380   a WAL database without using shared memory if that
   381    381   process is guaranteed to be the only process accessing the database.
   382    382   ^This feature allows WAL databases to be created, read, and written
   383         -by legacy [sqlite3_vfs | VFSes] that lack the "version 2" shared-memory
          383  +by legacy [VFSes] that lack the "version 2" shared-memory
   384    384   methods xShmMap, xShmLock, xShmBarrier, and xShmUnmap on the
   385    385   [sqlite3_io_methods] object.</p>
   386    386   
   387    387   <p>^(If EXCLUSIVE locking mode is set prior to the first WAL-mode 
   388    388   database access, then SQLite never attempts to call any of the
   389    389   shared-memory methods and hence no shared-memory
   390    390   wal-index is ever created.)^