Documentation updates. (CVS 1946)

FossilOrigin-Name: 799f5383c0c72a74c7b29f9f40fc949f3248a499
2026-01-06 08:01:16 +03:00 · 2004-09-08 13:06:21 +00:00
parent fa6bc0000f
commit 916d68efea
5 changed files with 131 additions and 81 deletions
--- a/16
+++ b/16
@@ -1,5 +1,5 @@
-C Wildcards\swith\sthe\ssame\sname\smap\sinto\sthe\ssame\svariable\snumber.\s\sNew\napi\ssqlite3_bind_parameter_index()\sadded\sto\smap\swildcard\snames\sinto\nwildcard\sindex\snumbers.\s\sSupport\sfor\s"?nnn"\swildcards.\s(CVS\s1945)
-D 2004-09-07T16:19:53
+C Documentation\supdates.\s(CVS\s1946)
+D 2004-09-08T13:06:21
 F Makefile.in 65a7c43fcaf9a710d62f120b11b6e435eeb4a450
 F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457
 F README f1de682fbbd94899d50aca13d387d1b3fd3be2dd
@@ -210,9 +210,9 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F www/arch.fig d5f9752a4dbf242e9cfffffd3f5762b6c63b3bcf
 F www/arch.gif f845a64772062e82d17980a349f95f1f0b4c8054
 F www/arch.png 82ef36db1143828a7abc88b1e308a5f55d4336f4
-F www/arch.tcl b833057e89aeb43335c0bf84a3d5b7f9d11df6fa
+F www/arch.tcl 126611ffd57e0dfac28d71ab04d7a78697ab4b80
 F www/arch2.fig ae2432145c26cfa148fa0116589517ad3cd5fc65
-F www/arch2.gif 49c6bb36160f03ca2b89eaa5bfb1f560c7d68ee7
+F www/arch2.gif 6f2d47c4e0c5842c0d6b5513fd8249393d7c7003
 F www/arch2b.fig d22a2c9642d584b89d4088b1e51e2bb0f7c04bed
 F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0
 F www/c_interface.tcl 83b39203e1ded4c2dab97f42edf31279a308efcb
@@ -233,7 +233,7 @@ F www/faq.tcl 3a1776818d9bd973ab0c3048ec7ad6b1ad091ae5
 F www/fileformat.tcl f71a06a0d533c7df408539c64113b4adeaf29764
 F www/formatchng.tcl d1dfecedfb25e122ab513a1e0948b15cb4f0be46
 F www/index.tcl 618733d540dcf28226cc8eb00816f0baaa03064d
-F www/lang.tcl b2ba401104a76e7842469b33a968f5eda9bd462b
+F www/lang.tcl 604683def6e987db1703faf580d9b2150905fda1
 F www/lockingv3.tcl afcd22f0f063989cff2f4d57bbc38d719b4c6e75
 F www/mingw.tcl d96b451568c5d28545fefe0c80bee3431c73f69c
 F www/nulls.tcl ede975a29def48838c606d4a0c0185d44f90a789
@@ -248,7 +248,7 @@ F www/tclsqlite.tcl 560ecd6a916b320e59f2917317398f3d59b7cc25
 F www/vdbe.tcl 59288db1ac5c0616296b26dce071c36cb611dfe9
 F www/version3.tcl 092a01f5ef430d2c4acc0ae558d74c4bb89638a0
 F www/whentouse.tcl a8335bce47cc2fddb07f19052cb0cb4d9129a8e4
-P f323e4f86a08fe6448cbd4ff7cab459e8039d9f1
-R b14b673cf74913bc0aa77288120014ba
+P 435b3f301fbb6953adc974c7f03589b06e9114c3
+R e9ed3557bbf8633eb729c636ad21e3fd
 U drh
-Z abec07c7d353cf60af4ed426f1ba4bbf
+Z d578a3410535617a4415c71c00fd3edf
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-435b3f301fbb6953adc974c7f03589b06e9114c3
+799f5383c0c72a74c7b29f9f40fc949f3248a499
--- a/www/arch.tcl
+++ b/www/arch.tcl
@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the sqlite.html file.
 #
-set rcsid {$Id: arch.tcl,v 1.14 2004/07/17 21:56:10 drh Exp $}
+set rcsid {$Id: arch.tcl,v 1.15 2004/09/08 13:06:21 drh Exp $}
 source common.tcl
 header {Architecture of SQLite}
 puts {
@@ -24,63 +24,40 @@ and how they interrelate is shown at the right.  The text that
 follows will provide a quick overview of each of these components.
 </p>

-<h3>History</h3>

 <p>
-There are two main C interfaces to the SQLite library:
-<b>sqlite_exec()</b> and <b>sqlite_compile()</b>.  Prior to
-version 2.8.0 (2003-Feb-16) only sqlite_exec() was supported.
-For version 2.8.0, the sqlite_exec and sqlite_compile methods
-existed as peers.  Beginning with version 2.8.13, the sqlite_compile
-method is the primary interface, and sqlite_exec is implemented
-using sqlite_compile.  Externally, this change is an enhancement
-that maintains backwards compatibility.  But internally,
-the plumbing is very different.  The diagram at the right shows
-the structure of SQLite for version 2.8.13 and following.
-</p>
-
-<p>
-This document describes the structure for SQLite version 2.X.
-SQLite version 3.0.0 introduces many new features and capabilities.
-The basic architecture of the library remains the same.  However,
-some of the details described here are different.  For example,
-the code was in the file <b>os.c</b> has now been split out into
-several file, on for each operating system.  And
-the prefix on the names of API routines changed from <b>sqlite_</b>
-to <b>sqlite3_</b>. 
+This document describes SQLite version 3.0.  Version 2.8 and
+earlier are similar but the details differ.
 </p>

 <h3>Interface</h3>

 <p>Much of the public interface to the SQLite library is implemented by
-functions found in the <b>main.c</b> source file though some routines are
+functions found in the <b>main.c</b>, <b>legacy.c</b>, and
+<b>vdbeapi.c</b> source files
+though some routines are
 scattered about in other files where they can have access to data 
 structures with file scope.  The
-<b>sqlite_get_table()</b> routine is implemented in <b>table.c</b>.
-<b>sqlite_step()</b> is found in <b>vdbe.c</b>.  
-<b>sqlite_mprintf()</b> is found in <b>printf.c</b>.
+<b>sqlite3_get_table()</b> routine is implemented in <b>table.c</b>.
+<b>sqlite3_mprintf()</b> is found in <b>printf.c</b>.
+<b>sqlite3_complete()</b> is in <b>tokenize.c</b>.
 The Tcl interface is implemented by <b>tclsqlite.c</b>.  More
 information on the C interface to SQLite is
-<a href="c_interface.html">available separately</a>.<p>
+<a href="capi3ref.html">available separately</a>.<p>

 <p>To avoid name collisions with other software, all external
-symbols in the SQLite library begin with the prefix <b>sqlite</b>.
+symbols in the SQLite library begin with the prefix <b>sqlite3</b>.
 Those symbols that are intended for external use (in other words,
 those symbols which form the API for SQLite) begin
-with <b>sqlite_</b>.</p>
-
-<h3>SQL Command Processor</h3>
-
-<p>
+with <b>sqlite3_</b>.</p>

 <h3>Tokenizer</h3>

 <p>When a string containing SQL statements is to be executed, the
 interface passes that string to the tokenizer.  The job of the tokenizer
 is to break the original string up into tokens and pass those tokens
-one by one to the parser.  The tokenizer is hand-coded in C.
-All of the code for the tokenizer
-is contained in the <b>tokenize.c</b> source file.</p>
+one by one to the parser.  The tokenizer is hand-coded in C in 
+the file <b>tokenize.c</b>.

 <p>Note that in this design, the tokenizer calls the parser.  People
 who are familiar with YACC and BISON may be used to doing things the
@@ -113,20 +90,30 @@ lemon is found in the "doc" subdirectory of the distribution.
 <p>After the parser assembles tokens into complete SQL statements,
 it calls the code generator to produce virtual machine code that
 will do the work that the SQL statements request.  There are many
-files in the code generator:  <b>build.c</b>, <b>copy.c</b>,
+files in the code generator:
+<b>attach.c</b>,
+<b>auth.c</b>,
+<b>build.c</b>,
 <b>delete.c</b>,
-<b>expr.c</b>, <b>insert.c</b>, <b>pragma.c</b>,
-<b>select.c</b>, <b>trigger.c</b>, <b>update.c</b>, <b>vacuum.c</b>
+<b>expr.c</b>,
+<b>insert.c</b>,
+<b>pragma.c</b>,
+<b>select.c</b>,
+<b>trigger.c</b>,
+<b>update.c</b>,
+<b>vacuum.c</b>
 and <b>where.c</b>.
 In these files is where most of the serious magic happens.
 <b>expr.c</b> handles code generation for expressions.
 <b>where.c</b> handles code generation for WHERE clauses on
-SELECT, UPDATE and DELETE statements.  The files <b>copy.c</b>,
+SELECT, UPDATE and DELETE statements.  The files <b>attach.c</b>,
 <b>delete.c</b>, <b>insert.c</b>, <b>select.c</b>, <b>trigger.c</b>
 <b>update.c</b>, and <b>vacuum.c</b> handle the code generation
 for SQL statements with the same names.  (Each of these files calls routines
 in <b>expr.c</b> and <b>where.c</b> as necessary.)  All other
-SQL statements are coded out of <b>build.c</b>.</p>
+SQL statements are coded out of <b>build.c</b>.
+The <b>auth.c</b> file implements the functionality of
+<b>sqlite3_set_authorizer()</b>.</p>

 <h3>Virtual Machine</h3>

@@ -146,14 +133,28 @@ between the virtual machine and the rest of the SQLite library and
 <b>vdbeInt.h</b> which defines structure private the virtual machine.
 The <b>vdbeaux.c</b> file contains utilities used by the virtual
 machine and interface modules used by the rest of the library to
-construct VM programs.</p>
+construct VM programs.  The <b>vdbeapi.c</b> file contains external
+interfaces to the virtual machine such as the 
+<b>sqlite3_bind_...</b> family of functions.  Individual values
+(strings, integer, floating point numbers, and BLOBs) are stored
+in an internal object named "Mem" which is implemented by
+<b>vdbemem.c</b>.</p>
+
+<p>
+SQLite implements SQL functions using callbacks to C-language routines.
+Even the built-in SQL functions are implemented this way.  Most of
+the built-in SQL functions (ex: <b>coalesce()</b>, <b>count()</b>,
+<b>substr()</b>, and so forth) can be found in <b>func.c</b>.
+Date and time conversion functions are found in <b>date.c</b>.
+</p>

 <h3>B-Tree</h3>

 <p>An SQLite database is maintained on disk using a B-tree implementation
 found in the <b>btree.c</b> source file.  A separate B-tree is used for
 each table and index in the database.  All B-trees are stored in the
-same disk file.</p>
+same disk file.  Details of the file format are recorded in a large
+comment at the beginning of <b>btree.c</b>.</p>

 <p>The interface to the B-tree subsystem is defined by the header file
 <b>btree.h</b>.
@@ -161,11 +162,13 @@ same disk file.</p>

 <h3>Page Cache</h3>

-<p>The B-tree module requests information from the disk in 1024 byte
-chunks.  The page cache is reponsible for reading, writing, and
+<p>The B-tree module requests information from the disk in fixed-size
+chunks.  The default chunk size is 1024 bytes but can vary between 512
+and 65536 bytes.
+The page cache is reponsible for reading, writing, and
 caching these chunks.
 The page cache also provides the rollback and atomic commit abstraction
-and takes care of reader/writer locking of the database file.  The
+and takes care of locking of the database file.  The
 B-tree driver requests particular pages from the page cache and notifies
 the page cache when it wants to modify pages or commit or rollback
 changes and the page cache handles all the messy details of making sure
@@ -181,12 +184,38 @@ is defined by the header file <b>pager.h</b>.
 <p>
 In order to provide portability between POSIX and Win32 operating systems,
 SQLite uses an abstraction layer to interface with the operating system.
-The <b>os.c</b> file contains about 20 routines used for opening and
-closing files, deleting files, creating and deleting locks on files,
-flushing the disk cache, and so forth.  Each of these functions contains
-two implementations separated by #ifdefs: one for POSIX and the other
-for Win32.  The interface to the OS abstraction layer is defined by
-the <b>os.h</b> header file.
+The interface to the OS abstraction layer is defined in
+<b>os.h</b>.  Each supported operating system has its own implementation:
+<b>os_unix.c</b> for Unix, <b>os_win.c</b> for windows, and so forth.
+Each of these operating-specific implements typically has its own
+header file: <b>os_unix.h</b>, <b>os_win.h</b>, etc.
 </p>
+
+<h3>Utilities</h3>
+
+<p>
+Memory allocation and caseless string comparison routines are located
+in <b>util.c</b>.
+Symbol tables used by the parser are maintained by hash tables found
+in <b>hash.c</b>.  The <b>utf.c</b> source file contains Unicode
+conversion subroutines.
+SQLite has its own private implementation of <b>printf()</b> (with
+some extensions) in <b>printf.c</b> and its own random number generator
+in <b>random.c</b>.
+</p>
+
+<h3>Test Code</h3>
+
+<p>
+If you count regression test scripts,
+more than half the total code base of SQLite is devoted to testing.
+There are many <b>assert()</b> statements in the main code files.
+In additional, the source files <b>test1.c</b> through <b>test5.c</b>
+together with <b>md5.c</b> implement extensions used for testing
+purposes only.  The <b>os_test.c</b> backend interface is used to
+simulate power failures to verify the crash-recovery mechanism in
+the pager.
+</p>
+
 }
 footer $rcsid
--- a/www/arch2.gif
+++ b/www/arch2.gif
--- a/www/lang.tcl
+++ b/www/lang.tcl
@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the sqlite.html file.
 #
-set rcsid {$Id: lang.tcl,v 1.71 2004/07/18 20:52:32 drh Exp $}
+set rcsid {$Id: lang.tcl,v 1.72 2004/09/08 13:06:21 drh Exp $}
 source common.tcl
 header {Query Language Understood by SQLite}
 puts {
@@ -183,8 +183,7 @@ ROLLBACK [TRANSACTION [<name>]]

 puts {
 <p>Beginning in version 2.0, SQLite supports transactions with
-rollback and atomic commit.  See <a href="#attach">ATTACH</a> for
-an exception when there are attached databases.</p>
+rollback and atomic commit.</p>

 <p>The optional transaction name is ignored. SQLite currently 
 does not allow nested transactions.</p>
@@ -261,6 +260,9 @@ puts {
 <p>The COPY command is available in SQLite version 2.8 and earlier.
 The COPY command has been removed from SQLite version 3.0 due to
 complications in trying to support it in a mixed UTF-8/16 environment.
+In version 3.0, the <a href="sqlite.html">command-line shell</a>
+contains a new command <b>.import</b> that can be used as a substitute
+for COPY.
 </p>

 <p>The COPY command is an extension used to load large amounts of
@@ -389,10 +391,10 @@ for use by the engine.</p>

 <p>Each column definition is the name of the column followed by the
 datatype for that column, then one or more optional column constraints.
-SQLite is <a href="datatypes.html">typeless</a>.
 The datatype for the column does not restrict what data may be put
 in that column.
-All information is stored as null-terminated strings.
+See <a href="datatype3.html">Datatypes In SQLite Version 3</a> for
+additional information.
 The UNIQUE constraint causes an index to be created on the specified
 columns.  This index must contain unique keys.
 The DEFAULT constraint
@@ -448,8 +450,9 @@ work.</p>
 <p>There are no arbitrary limits on the number
 of columns or on the number of constraints in a table.
 The total amount of data in a single row is limited to about
-1 megabytes.  (This limit can be increased to 16MB by changing
-a single #define in the source code and recompiling.)</p>
+1 megabytes in version 2.8.  In version 3.0 there is no arbitrary
+limit on the amount of data in a row.</p>
+

 <p>The CREATE TABLE AS form defines the table to be
 the result set of a query.  The names of the table columns are
@@ -704,7 +707,8 @@ DROP INDEX [<database-name> .] <index-name>
 }

 puts {
-<p>The DROP INDEX statement removes an index added with the <a href="#createindex">
+<p>The DROP INDEX statement removes an index added
+with the <a href="#createindex">
 CREATE INDEX</a> statement.  The index named is completely removed from
 the disk.  The only way to recover the index is to reenter the
 appropriate CREATE INDEX command.  Non-temporary indexes on tables in 
@@ -921,7 +925,7 @@ their result across all rows of the result set.</p>

 <p>The functions shown below are available by default.  Additional
 functions may be written in C and added to the database engine using
-the <a href="c_interface.html#cfunc">sqlite_create_function()</a>
+the <a href="capi3ref.html#cfunc">sqlite3_create_function()</a>
 API.</p>

 <table border=0 cellpadding=10>
@@ -941,8 +945,8 @@ all arguments are NULL then NULL is returned.  There must be at least
 <a name="globFunc"></a>
 <td valign="top" align="right">glob(<i>X</i>,<i>Y</i>)</td>
 <td valign="top">This function is used to implement the
-"<b>Y GLOB X</b>" syntax of SQLite.  The
-<a href="c_interface.html#cfunc">sqlite_create_function()</a> 
+"<b>X GLOB Y</b>" syntax of SQLite.  The
+<a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a> 
 interface can
 be used to override this function and thereby change the operation
 of the <a href="#glob">GLOB</a> operator.</td>
@@ -973,8 +977,8 @@ characters is returned, not the number of bytes.</td>
 <a name="likeFunc"></a>
 <td valign="top" align="right">like(<i>X</i>,<i>Y</i>)</td>
 <td valign="top">This function is used to implement the
-"<b>Y LIKE X</b>" syntax of SQL.  The
-<a href="c_interface.html#cfunc">sqlite_create_function()</a> 
+"<b>X LIKE Y</b>" syntax of SQL.  The
+<a href="capi3ref.html#sqlite3_create_function">sqlite_create_function()</a> 
 interface can
 be used to override this function and thereby change the operation
 of the <a href="#like">LIKE</a> operator.</td>
@@ -1012,6 +1016,17 @@ only a single argument.</td>
 otherwise return NULL.</td>
 </tr>

+<tr>
+<td valign="top" align="right">quote(<i>X</i>)</td>
+<td valign="top">This routine returns a string which is the value of
+its argument suitable for inclusion into another SQL statement.
+Strings are surrounded by single-quotes with escapes on interior quotes
+as needed.  BLOBs are encoded as hexadecimal literals.
+The current implementation of VACUUM uses this function.  The function
+is also useful when writing triggers to implement undo/redo functionality.
+</td>
+</tr>
+
 <tr>
 <td valign="top" align="right">random(*)</td>
 <td valign="top">Return a random integer between -2147483648 and
@@ -1053,8 +1068,9 @@ then characters indices refer to actual UTF-8 characters, not bytes.</td>
 <tr>
 <td valign="top" align="right">typeof(<i>X</i>)</td>
 <td valign="top">Return the type of the expression <i>X</i>.  The only 
-return values are "numeric" and "text".  SQLite's type handling is 
-explained in <a href="datatypes.html">Datatypes in SQLite</a>.</td>
+return values are "null", "integer", "real", "text", and "blob".
+SQLite's type handling is 
+explained in <a href="datatype3.html">Datatypes in SQLite Version 3</a>.</td>
 </tr>

 <tr>
@@ -1069,7 +1085,8 @@ UTF-8 strings.</td>
 <p>
 The following aggregate functions are available by default.  Additional
 aggregate functions written in C may be added using the 
-<a href="c_interface.html#cfunc">sqlite_create_aggregate()</a> API.</p>
+<a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a>
+API.</p>

 <table border=0 cellpadding=10>
 <tr>
@@ -1270,8 +1287,10 @@ is returned it is as an integer.</p>
 <li><p><b>PRAGMA default_cache_size;
       <br>PRAGMA default_cache_size = </b><i>Number-of-pages</i><b>;</b></p>
    <p>Query or change the maximum number of database disk pages that SQLite
-    will hold in memory at once.  Each page uses 1K on disk and about 1.5K in memory.
-    This pragma works like the <a href="#pragma_cache_size"><b>cache_size</b></a> 
+    will hold in memory at once.  Each page uses 1K on disk and about
+    1.5K in memory.
+    This pragma works like the
+    <a href="#pragma_cache_size"><b>cache_size</b></a> 
    pragma with the additional
    feature that it changes the cache size persistently.  With this pragma,
    you can set the cache size once and that setting is retained and reused
@@ -1308,7 +1327,9 @@ is returned it is as an integer.</p>
    <p>This pragma changes the synchronous mode persistently.  Once changed,
    the mode stays as set even if the database is closed and reopened.  The
    <a href="#pragma_synchronous"><b>synchronous</b></a> pragma does the same 
-    thing but only applies the setting to the current session.</p></li>
+    thing but only applies the setting to the current session.
+    
+    </p></li>

 <a name="pragma_default_temp_store"></a>
 <li><p><b>PRAGMA default_temp_store;