Documentation Source Text

Check-in [6c382d50b9]
Login

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

Overview
Comment:Merge changes from branch-3.20. Updated the makefile so that it works with recent changes to the core SQLite. The makefile now expects the BLD variable to be set to point to the directory in which has been run "./configure; make sqlite3.c" for the core source code.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 6c382d50b9c3926a39ab8e45b619baa57d7b74f083320c3f853fabae9e9854d6
User & Date: drh 2017-08-25 17:22:00.405
Context
2017-08-25
17:26
Update the prototype Makefile. (check-in: 44c52e864a user: drh tags: trunk)
17:22
Merge changes from branch-3.20. Updated the makefile so that it works with recent changes to the core SQLite. The makefile now expects the BLD variable to be set to point to the directory in which has been run "./configure; make sqlite3.c" for the core source code. (check-in: 6c382d50b9 user: drh tags: trunk)
16:28
Update the speed and size graph. (check-in: a56a3b4391 user: drh tags: trunk)
2017-08-24
16:48
Fix incorrect SHA3 hash on the 3.20.1 sqlite3.c file. (check-in: 4252537c27 user: drh tags: branch-3.20)
Changes
Unified Diff Ignore Whitespace Patch
Changes to main.mk. 
1
2
3
4
5
6
7
8

9
10
11
12
13
14
15
16

###############################################################################
# The following macros should be defined before this script is
# invoked:
#
# DOC              The toplevel directory of the documentation source tree.
#
# SRC              The toplevel directory of the source code source tree.
#

# TCLSQLITE3C      Name of the amalgamation source file
#
# TH3              The toplevel directory for TH3.  May be an empty string.
#
# SLT              The toplevel directory for SQLLogicTest.  May be an
#                  empty string
#
# TCLFLAGS         Extra C-compiler options needed to link against TCL









>
|








1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

###############################################################################
# The following macros should be defined before this script is
# invoked:
#
# DOC              The toplevel directory of the documentation source tree.
#
# SRC              The toplevel directory of the source code source tree.
#
# BLD              The directory in which the current source code has been
#                  built using "make sqlite3.c"
#
# TH3              The toplevel directory for TH3.  May be an empty string.
#
# SLT              The toplevel directory for SQLLogicTest.  May be an
#                  empty string
#
# TCLFLAGS         Extra C-compiler options needed to link against TCL
︙︙
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


all:	base evidence format_evidence matrix doc

private:	base evidence private_evidence matrix doc

fast:	base doc

sqlite3.h: $(TCLSH) $(SRC)/src/sqlite.h.in $(SRC)/manifest.uuid $(SRC)/VERSION
	./$(TCLSH) $(SRC)/tool/mksqlite3h.tcl $(SRC) | \
	sed 's/^SQLITE_API //' >sqlite3.h

# Generate the directory into which generated documentation files will
# be written.
#
docdir:
	mkdir -p doc doc/c3ref doc/matrix doc/matrix/c3ref doc/matrix/syntax









|
|
|








41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


all:	base evidence format_evidence matrix doc

private:	base evidence private_evidence matrix doc

fast:	base doc

sqlite3.h: $(BLD)/sqlite3.h
	cp $(BLD)/sqlite3.h orig-sqlite3.h
	sed 's/^SQLITE_API //' orig-sqlite3.h >sqlite3.h

# Generate the directory into which generated documentation files will
# be written.
#
docdir:
	mkdir -p doc doc/c3ref doc/matrix doc/matrix/c3ref doc/matrix/syntax
︙︙
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

#-------------------------------------------------------------------------

# Source files for the [tclsqlite3.search] executable. 
#
SSRC = $(DOC)/search/searchc.c \
	    $(DOC)/search/parsehtml.c \
	    $(DOC)/search/fts5ext.c \
	    $(TCLSQLITE3C)

# Flags to build [tclsqlite3.search] with.
#
SFLAGS = $(TCLINC) -DSQLITE_THREADSAFE=0 -DSQLITE_ENABLE_FTS5 -DSQLITE_TCLMD5 -DTCLSH -Dmain=xmain

$(TCLSH): $(SSRC)
	$(CC) -O2 -o $@ -I. $(SFLAGS) $(SSRC) $(TCLFLAGS)








|








143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

#-------------------------------------------------------------------------

# Source files for the [tclsqlite3.search] executable. 
#
SSRC = $(DOC)/search/searchc.c \
	    $(DOC)/search/parsehtml.c \
	    $(DOC)/search/fts5ext.c \
	    $(BLD)/tclsqlite3.c

# Flags to build [tclsqlite3.search] with.
#
SFLAGS = $(TCLINC) -DSQLITE_THREADSAFE=0 -DSQLITE_ENABLE_FTS5 -DSQLITE_TCLMD5 -DTCLSH -Dmain=xmain

$(TCLSH): $(SSRC)
	$(CC) -O2 -o $@ -I. $(SFLAGS) $(SSRC) $(TCLFLAGS)
︙︙
Changes to pages/capi3ref.in.
︙︙
474
475
476
477
478
479
480



481
482
483
484
485
486
487

      set uri [convert_keyword_to_uri $kw]
      incr funccnts($s)
      dbtoc eval {INSERT INTO toc(name,type,status,title,uri)
                   VALUES($kw,'function',$s,$title,$uri)}
    }
  }
}



hd_open_aux c3ref/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords *capi3ref_funclist {C-API function list}
hd_enable_main 0
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>








>
>
>








474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490

      set uri [convert_keyword_to_uri $kw]
      incr funccnts($s)
      dbtoc eval {INSERT INTO toc(name,type,status,title,uri)
                   VALUES($kw,'function',$s,$title,$uri)}
    }
  }
}
#puts "content=[list $content]"
#puts "supported=[list [array get supported]]"
#puts "funccnts=[list [array get funccnts]]
hd_open_aux c3ref/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords *capi3ref_funclist {C-API function list}
hd_enable_main 0
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
︙︙
Changes to pages/changes.in.
︙︙
29
30
31
32
33
34
35
36
37
38
39
40
41
42









43
44
45
46
47
48
49

<li> Allow [ATTACH] and [DETACH] commands to work inside of a transaction.
<li> Allow [WITHOUT ROWID virtual tables] to be writable if the PRIMARY KEY
     contains exactly one column.
<li> Query planner enhancements:
<ol type="a">
<li> Enhanced the [LIKE optimization] so that it works with an ESCAPE clause.
</ol>
<li> Miscellaneous [microoptimizations] reduce CPU usage by about 0.4%.
<li> Bug fixes:
<ol type="a">
<li> Fix a faulty assert() statement discovered by OSSFuzz.
     Ticket [https://sqlite.org/src/info/cb91bf4290c211d|cb91bf4290c211d]
</ol>
}










chng {2017-08-01 (3.20.0)} {
<li> Update the text of error messages returned by [sqlite3_errmsg()] for some
     error codes.
<li> Add new [pointer passing interfaces].
<li> Backwards-incompatible changes to some extensions in order to take 
     advantage of the improved security offered by the new 








|






>
>
>
>
>
>
>
>
>








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

<li> Allow [ATTACH] and [DETACH] commands to work inside of a transaction.
<li> Allow [WITHOUT ROWID virtual tables] to be writable if the PRIMARY KEY
     contains exactly one column.
<li> Query planner enhancements:
<ol type="a">
<li> Enhanced the [LIKE optimization] so that it works with an ESCAPE clause.
</ol>
<li> Miscellaneous [microoptimizations] reduce CPU usage by about 1.6%.
<li> Bug fixes:
<ol type="a">
<li> Fix a faulty assert() statement discovered by OSSFuzz.
     Ticket [https://sqlite.org/src/info/cb91bf4290c211d|cb91bf4290c211d]
</ol>
}

chng {2017-08-24 (3.20.1)} {
<li> Fix a potential memory leak in the new [sqlite3_result_pointer()] interface.
     Ticket [https://sqlite.org/src/info/7486aa54b968e9b5|7486aa54b968e9b5].
<p><b>Hashes:</b>
<li>SQLITE_SOURCE_ID: "2017-08-24 16:21:36 8d3a7ea6c5690d6b7c3767558f4f01b511c55463e3f9e64506801fe9b74dce34"
<li>SHA3-256 for sqlite3.c: 93b1a6d69b48dc39697d1d3a1e4c30b55da0bdd2cad0c054462f91081832954a
} {patchagainst 1}


chng {2017-08-01 (3.20.0)} {
<li> Update the text of error messages returned by [sqlite3_errmsg()] for some
     error codes.
<li> Add new [pointer passing interfaces].
<li> Backwards-incompatible changes to some extensions in order to take 
     advantage of the improved security offered by the new
︙︙
Changes to pages/chronology.in.
︙︙
25
26
27
28
29
30
31

32
33
34
35
36
37
38

#
# A small amount of manual editing and de-duplication followed.
#
# Manually edit the list for each subsequent release.
#      
foreach line [split {
xxxxxxxxxx|pending|Version 3.21.0

9501e22dfe|2017-08-01|Version 3.20.0
036ebf729e|2017-06-17|Version 3.18.2
77bb46233d|2017-06-16|Version 3.18.1
0ee482a1e0|2017-06-08|Version 3.19.3
edb4e819b0|2017-05-25|Version 3.19.2
f6d7b988f4|2017-05-24|Version 3.19.1
28a94eb282|2017-05-22|Version 3.19.0








>








25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

#
# A small amount of manual editing and de-duplication followed.
#
# Manually edit the list for each subsequent release.
#      
foreach line [split {
xxxxxxxxxx|pending|Version 3.21.0
8d3a7ea6c5|2017-08-24|Version 3.20.1
9501e22dfe|2017-08-01|Version 3.20.0
036ebf729e|2017-06-17|Version 3.18.2
77bb46233d|2017-06-16|Version 3.18.1
0ee482a1e0|2017-06-08|Version 3.19.3
edb4e819b0|2017-05-25|Version 3.19.2
f6d7b988f4|2017-05-24|Version 3.19.1
28a94eb282|2017-05-22|Version 3.19.0
︙︙
Changes to pages/csv.in.
︙︙
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

large amounts of comma-separated value content.
The CSV virtual table is also useful as a template source file for
implementing other virtual tables.
</p>


<p>
The CVS virtual table is not built into the SQLite amalgamation.
It is available as a
[https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/csv.c|separate source file]
that can be compiled into a [loadable extension].
Typical usage of the CSV virtual table from the
[command-line shell] would be something like this:

<codeblock>








|








16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

large amounts of comma-separated value content.
The CSV virtual table is also useful as a template source file for
implementing other virtual tables.
</p>


<p>
The CSV virtual table is not built into the SQLite amalgamation.
It is available as a
[https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/csv.c|separate source file]
that can be compiled into a [loadable extension].
Typical usage of the CSV virtual table from the
[command-line shell] would be something like this:

<codeblock>
︙︙
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99


<li><p><b>data=</b><i>TEXT</i>
<p>The <b>data=</b> argument specifies that <i>TEXT</i> is the literal
content of the CSV file.

<li><p><b>schema=</b><i>SCHEMA</i>
<p> The <b>schema=</b> argument specifies a [CREATE TABLE] statement that
the CVS virtual table passes to the [sqlite3_declare_vtab()] interface in
order to define the number and names of the columns in the virtual table.
If both the <b>schema=</b> and the <b>columns=</b> arguments are omitted,
then the CVS virtual table reads the first row of the input content in order
to determine the number of columns and names the columns <b>cNNN</b> where
<b>NNN</b> values are consecutive integers.  It is not allowed to have
both <b>schema=</b> and <b>columns=</b> arguments.

<li><p><b>columns=</b><i>N</i>
<p>The <b>columns=</b><i>N</i> argument causes the virtual table to have
exactly <i>N</i> columns.  If the input data contains more columns than this,
then the excess columns are ignored.  If the input data contains fewer columns,
then extra columns are filled with NULL.
</u>








|


|











79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99


<li><p><b>data=</b><i>TEXT</i>
<p>The <b>data=</b> argument specifies that <i>TEXT</i> is the literal
content of the CSV file.

<li><p><b>schema=</b><i>SCHEMA</i>
<p> The <b>schema=</b> argument specifies a [CREATE TABLE] statement that
the CSV virtual table passes to the [sqlite3_declare_vtab()] interface in
order to define the number and names of the columns in the virtual table.
If both the <b>schema=</b> and the <b>columns=</b> arguments are omitted,
then the CSV virtual table reads the first row of the input content in order
to determine the number of columns and names the columns <b>cNNN</b> where
<b>NNN</b> values are consecutive integers.  It is not allowed to have
both <b>schema=</b> and <b>columns=</b> arguments.

<li><p><b>columns=</b><i>N</i>
<p>The <b>columns=</b><i>N</i> argument causes the virtual table to have
exactly <i>N</i> columns.  If the input data contains more columns than this,
then the excess columns are ignored.  If the input data contains fewer columns,
then extra columns are filled with NULL.
</u>
Changes to pages/download.in.
︙︙
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

Note that a recent version of <a href="http://www.tcl-lang.org/">Tcl</a>
is required in order to build from the repository sources. 
The [amalgamation] source code files
(the "sqlite3.c" and "sqlite3.h" files) build products and are
not contained in raw source code tree.</p>

<blockquote>
<a href="http://www.sqlite.org/cgi/src">http://www.sqlite.org/cgi/src</a> (Dallas)<br>
<a href="http://www2.sqlite.org/cgi/src">http://www2.sqlite.org/cgi/src</a> (Newark)<br>
<a href="http://www3.sqlite.org/cgi/src">http://www3.sqlite.org/cgi/src</a> (Fremont)<br>
</blockquote>

<p>The documentation is maintained in separate
[http://www.fossil-scm.org/ | Fossil] repositories located
at:</p>

<blockquote>
<a href="http://www.sqlite.org/cgi/docsrc">http://www.sqlite.org/cgi/docsrc</a> (Dallas)<br>
<a href="http://www2.sqlite.org/cgi/docsrc">http://www2.sqlite.org/cgi/docsrc</a> (Newark)<br>
<a href="http://www3.sqlite.org/cgi/docsrc">http://www3.sqlite.org/cgi/docsrc</a> (Fremont)<br>
</blockquote>
<tcl>
proc set_download_hyperlinks {} {
  set script "<script type='text/JavaScript'>\n"
  append script "/* <!\[CDATA\[ */\n"
  append script "function adce4d016d6cd()\173\n"
  append script "function d391(a,b){document.getElementById(a).href=b;}\n"








|
|
|







|
|
|








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

Note that a recent version of <a href="http://www.tcl-lang.org/">Tcl</a>
is required in order to build from the repository sources. 
The [amalgamation] source code files
(the "sqlite3.c" and "sqlite3.h" files) build products and are
not contained in raw source code tree.</p>

<blockquote>
<a href="https://www.sqlite.org/cgi/src">https://www.sqlite.org/cgi/src</a> (Dallas)<br>
<a href="https://www2.sqlite.org/cgi/src">https://www2.sqlite.org/cgi/src</a> (Newark)<br>
<a href="https://www3.sqlite.org/cgi/src">https://www3.sqlite.org/cgi/src</a> (San Francisco)<br>
</blockquote>

<p>The documentation is maintained in separate
[http://www.fossil-scm.org/ | Fossil] repositories located
at:</p>

<blockquote>
<a href="https://www.sqlite.org/cgi/docsrc">https://www.sqlite.org/cgi/docsrc</a> (Dallas)<br>
<a href="https://www2.sqlite.org/cgi/docsrc">https://www2.sqlite.org/cgi/docsrc</a> (Newark)<br>
<a href="https://www3.sqlite.org/cgi/docsrc">https://www3.sqlite.org/cgi/docsrc</a> (San Francisco)<br>
</blockquote>
<tcl>
proc set_download_hyperlinks {} {
  set script "<script type='text/JavaScript'>\n"
  append script "/* <!\[CDATA\[ */\n"
  append script "function adce4d016d6cd()\173\n"
  append script "function d391(a,b){document.getElementById(a).href=b;}\n"
︙︙
Changes to pages/fts5.in.
︙︙
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427

  ** handle (accessible using sqlite3_errcode()/errmsg()).
  */</i>
  fts5_api *fts5_api_from_db(sqlite3 *db){
    fts5_api *pRet = 0;
    sqlite3_stmt *pStmt = 0;

    if( SQLITE_OK==sqlite3_prepare(db, "SELECT fts5(?1)", -1, &pStmt, 0) ){
      sqlite3_bind_pointer(pStmt, (void*)&pRet, "fts5_api_ptr");
      sqlite3_step(pStmt);
    }
    sqlite3_finalize(pStmt);
    return pRet;
  }
</codeblock>









|








1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427

  ** handle (accessible using sqlite3_errcode()/errmsg()).
  */</i>
  fts5_api *fts5_api_from_db(sqlite3 *db){
    fts5_api *pRet = 0;
    sqlite3_stmt *pStmt = 0;

    if( SQLITE_OK==sqlite3_prepare(db, "SELECT fts5(?1)", -1, &pStmt, 0) ){
      sqlite3_bind_pointer(pStmt, (void*)&pRet, "fts5_api_ptr", NULL);
      sqlite3_step(pStmt);
    }
    sqlite3_finalize(pStmt);
    return pRet;
  }
</codeblock>
︙︙
Changes to pages/getthecode.in.
︙︙
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

either downloading a tarball or ZIP archive for a specific version, or
by cloning the entire project history.

<p>SQLite sources are maintained on three geographically dispersed
servers:

<blockquote>
[http://www.sqlite.org/cgi/src] (Dallas)<br>
[http://www2.sqlite.org/cgi/src] (Newark)<br>
[http://www3.sqlite.org/cgi/src] (Fremont)<br>
</blockquote>

<p>The documentation is maintained in separate source repositories on
those same servers:

<blockquote>
[http://www.sqlite.org/cgi/docsrc] (Dallas)<br>
[http://www2.sqlite.org/cgi/docsrc] (Newark)<br>
[http://www3.sqlite.org/cgi/docsrc] (Fremont)<br>
</blockquote>

<p>To download a specific historical version, first locate the specific
version desired by visiting the timeline page on one of these servers
(for example: [http://www.sqlite.org/cgi/src/timeline]).  If
you know the approximate date of the version you want to download, you
can add a query parameter like "c=YYYY-MM-DD" to the "timeline" URL to








|
|
|






|
|
|








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

either downloading a tarball or ZIP archive for a specific version, or
by cloning the entire project history.

<p>SQLite sources are maintained on three geographically dispersed
servers:

<blockquote>
[https://www.sqlite.org/cgi/src] (Dallas)<br>
[https://www2.sqlite.org/cgi/src] (Newark)<br>
[https://www3.sqlite.org/cgi/src] (San Francisco)<br>
</blockquote>

<p>The documentation is maintained in separate source repositories on
those same servers:

<blockquote>
[https://www.sqlite.org/cgi/docsrc] (Dallas)<br>
[https://www2.sqlite.org/cgi/docsrc] (Newark)<br>
[https://www3.sqlite.org/cgi/docsrc] (San Francisco)<br>
</blockquote>

<p>To download a specific historical version, first locate the specific
version desired by visiting the timeline page on one of these servers
(for example: [http://www.sqlite.org/cgi/src/timeline]).  If
you know the approximate date of the version you want to download, you
can add a query parameter like "c=YYYY-MM-DD" to the "timeline" URL to
︙︙
Changes to pages/news.in.
︙︙
14
15
16
17
18
19
20






21
22
23
24
25
26
27

  hd_puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  regsub -all {[Tt]icket #(\d+)} $txt \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} txt
  hd_resolve "<blockquote>$txt</blockquote>"
  hd_puts "<hr width=\"50%\">"
}







newsitem {2017-08-01} {Release 3.20.0} {
SQLite [version 3.20.0] is a regularly secheduled maintenance release
of SQLite.
<p>
This release contains many minor enhancements, including:
<ul>








>
>
>
>
>
>








14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

  hd_puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  regsub -all {[Tt]icket #(\d+)} $txt \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} txt
  hd_resolve "<blockquote>$txt</blockquote>"
  hd_puts "<hr width=\"50%\">"
}

newsitem {2017-08-24} {Release 3.20.1} {
The [version 3.20.1] patch release changes two lines of code in
the [sqlite3_result_pointer()] interface in order to fix a rare
memory leak.  There are no other changes relative to [version 3.20.0].
}

newsitem {2017-08-01} {Release 3.20.0} {
SQLite [version 3.20.0] is a regularly secheduled maintenance release
of SQLite.
<p>
This release contains many minor enhancements, including:
<ul>
︙︙