Documentation Source Text

  regsub {^sqlite3_} $oldname {} name
  return $name.html
}

# Output HTML that displays the list $lx in $N columns
#
proc output_list {N lx} {
  hd_puts {<table width="100%" cellpadding="5"><tr>}
  set len [llength $lx]
  set n [expr {($len + $N - 1)/$N}]
  for {set i 0} {$i<$N} {incr i} {
    set start [expr {$i*$n}]
    set end [expr {($i+1)*$n}]
    hd_puts {<td valign="top"><ul>}
    for {set j $start} {$j<$end} {incr j} {
................................................................................
          hd_resolve "\[experimental | <small><i>(exp)</i></small>\]</li>"
        } elseif {$s==2} {
          hd_resolve "<li>\[$link|$label\]&nbsp;&nbsp;"
          hd_resolve "\[deprecated | <small><i>(obs)</i></small>\]</li>"
        } else {
          hd_resolve "<li>\[$link|$label\]</li>"
        }

      }
    }
    hd_puts {</ul></td>}
  }
  hd_puts {</tr></table>}
}

hd_open_aux c3ref/intro.html
hd_header Introduction
hd_enable_main 0
hd_keywords {capi3ref}
</tcl>
................................................................................
      lappend objlist [list $k $kw $s]
    }
  }
}
hd_open_aux c3ref/objlist.html
hd_header {List Of SQLite Objects}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>Objects:</h2>
<p>Note: Objects marked with "[experimental | <small><i>exp</i></small>]"
are [experimental] and objects marked with
"[deprecated | <small><i>(obs)</i></small>]" are [deprecated].</p>
<tcl>
output_list 3 [lsort $objlist]
hd_enable_main 0
hd_puts {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="funclist.html">Functions</a>.}
hd_close_aux
hd_enable_main 1
hd_puts {<hr>}

# Do a table of contents for constants
#
set clist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="constant"} continue
................................................................................
      lappend clist [list $k $kw $s]
    }
  }
}
hd_open_aux c3ref/constlist.html
hd_header {List Of SQLite Constants}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>Constants:</h2>
<p>Note: Constants marked with "[experimental | <small><i>(exp)</i></small>]"
are [experimental] and constants marked with
"[deprecated | <small><i>(obs)</i></small>]" are [deprecated]</p>
<tcl>
set clist [lsort -index 1 $clist]
output_list 2 $clist
hd_enable_main 0
hd_puts {<p>Other lists:
<a href="objlist.html">Objects</a> and
<a href="funclist.html">Functions</a>.</p>}
hd_enable_main 1
hd_close_aux
hd_puts {<hr>}


# Do a table of contents for functions
#
set funclist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
................................................................................
    }
  }
}
hd_open_aux c3ref/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords {capi3ref_funclist}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>Functions:</h2>
<p>Note: Functions marked with "[experimental | <small><i>(exp)</i></small>]"
are [experimental] and functions marked with
[deprecated | <small><i>(obs)</i></small>] are [deprecated].</p>
<tcl>
set funclist [lsort -index 1 $funclist]
output_list 3 $funclist
hd_enable_main 0
hd_puts {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="objlist.html">Objects</a>.</p>}
hd_enable_main 1
hd_close_aux
hd_puts {<hr>}


# Output all the records
#
foreach c [lsort $content] {
  foreach {key title type keywords body code} $c break
  set kw [preferred_keyword [lsort $keywords]]

  regsub {^sqlite3_} $oldname {} name
  return $name.html
}

# Output HTML that displays the list $lx in $N columns
#
proc output_list {N lx} {
  hd_putsnl {<table width="100%" cellpadding="5"><tr>}
  set len [llength $lx]
  set n [expr {($len + $N - 1)/$N}]
  for {set i 0} {$i<$N} {incr i} {
    set start [expr {$i*$n}]
    set end [expr {($i+1)*$n}]
    hd_puts {<td valign="top"><ul>}
    for {set j $start} {$j<$end} {incr j} {
................................................................................
          hd_resolve "\[experimental | <small><i>(exp)</i></small>\]</li>"
        } elseif {$s==2} {
          hd_resolve "<li>\[$link|$label\]&nbsp;&nbsp;"
          hd_resolve "\[deprecated | <small><i>(obs)</i></small>\]</li>"
        } else {
          hd_resolve "<li>\[$link|$label\]</li>"
        }
        hd_puts \n
      }
    }
    hd_putsnl {</ul></td>}
  }
  hd_putsnl {</tr></table>}
}

hd_open_aux c3ref/intro.html
hd_header Introduction
hd_enable_main 0
hd_keywords {capi3ref}
</tcl>
................................................................................
      lappend objlist [list $k $kw $s]
    }
  }
}
hd_open_aux c3ref/objlist.html
hd_header {List Of SQLite Objects}
hd_enable_main 0
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>Objects:</h2>
<p>Note: Objects marked with "[experimental | <small><i>exp</i></small>]"
are [experimental] and objects marked with
"[deprecated | <small><i>(obs)</i></small>]" are [deprecated].</p>
<tcl>
output_list 3 [lsort $objlist]
hd_enable_main 0
hd_putsnl {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="funclist.html">Functions</a>.}
hd_close_aux
hd_enable_main 1
hd_putsnl {<hr>}

# Do a table of contents for constants
#
set clist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="constant"} continue
................................................................................
      lappend clist [list $k $kw $s]
    }
  }
}
hd_open_aux c3ref/constlist.html
hd_header {List Of SQLite Constants}
hd_enable_main 0
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>Constants:</h2>
<p>Note: Constants marked with "[experimental | <small><i>(exp)</i></small>]"
are [experimental] and constants marked with
"[deprecated | <small><i>(obs)</i></small>]" are [deprecated]</p>
<tcl>
set clist [lsort -index 1 $clist]
output_list 2 $clist
hd_enable_main 0
hd_putsnl {<p>Other lists:
<a href="objlist.html">Objects</a> and
<a href="funclist.html">Functions</a>.</p>}
hd_enable_main 1
hd_close_aux
hd_putsnl {<hr>}


# Do a table of contents for functions
#
set funclist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
................................................................................
    }
  }
}
hd_open_aux c3ref/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords {capi3ref_funclist}
hd_enable_main 0
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>Functions:</h2>
<p>Note: Functions marked with "[experimental | <small><i>(exp)</i></small>]"
are [experimental] and functions marked with
[deprecated | <small><i>(obs)</i></small>] are [deprecated].</p>
<tcl>
set funclist [lsort -index 1 $funclist]
output_list 3 $funclist
hd_enable_main 0
hd_putsnl {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="objlist.html">Objects</a>.</p>}
hd_enable_main 1
hd_close_aux
hd_putsnl {<hr>}


# Output all the records
#
foreach c [lsort $content] {
  foreach {key title type keywords body code} $c break
  set kw [preferred_keyword [lsort $keywords]]

<title>SQLite Documentation</title>

<h2>Available Documentation</h2>
<table width="100%" cellpadding="5">

<tcl>
proc doc {name url desc} {
  hd_puts {<tr><td valign="top" align="right">}
  regsub -all { +} $name {\&nbsp;} name
  hd_puts "<a href=\"$url\">$name</a></td>"
................................................................................
  hd_puts {<td width="10"></td>}
  hd_puts {<td valign="top" align="left">}
  hd_resolve $desc
  hd_puts {</td></tr>}
}

proc heading {text {caption {}}} {
  hd_puts {<tr><td colspan=3 style="padding: 3ex 0 0 0">}
  hd_puts "<b>$text</b>"
  if {$caption ne ""} {
    hd_puts {<tr><td colspan=3 style="padding: 0 10ex">}
    hd_puts $caption
  }
}



doc {Appropriate Uses For SQLite} {whentouse.html} {
  This document describes situations where SQLite is an appropriate
  database engine to use versus situations where a client/server
  database engine might be a better choice.
}
doc {Distinctive Features} {different.html} {
................................................................................
}
doc {Sharing Cache Mode} {sharedcache.html} {
  Version 3.3.0 and later supports the ability for two or more
  database connections to share the same page and schema cache.
  This feature is useful for certain specialized applications.
}
doc {Unlock Notify} {unlock_notify.html} {
  The "unlock notify" feature can be used in conjunction with shared
  cache mode to more efficiently manage resource conflict (database
  table locks).
}
doc {Asynchronous IO Mode} {asyncvfs.html} {
  This page describes the asynchronous IO extension developed alongside
  SQLite. Using asynchronous IO can cause SQLite to appear more responsive
  by delegating database writes to a background thread.
}
................................................................................
doc {Release History} {changes.html} {
  A chronology of SQLite releases going back to version 1.0.0
}
doc {Backwards Compatibility} {formatchng.html} {
  This document details all of the incompatible changes to the SQLite
  file format that have occurred since version 1.0.0.
}







heading {SQLite Technical/Design Documentation}

doc {Temporary Files Used By SQLite} {tempfiles.html} {
  SQLite can potentially use many different temporary files when
  processing certain SQL statements.  This document describes the
  many kinds of temporary files that SQLite uses and offers suggestions
................................................................................
}

doc {How SQLite Implements Atomic Commit} {atomiccommit.html} {
  A description of the logic within SQLite that implements
  transactions with atomic commit, even in the face of power
  failures.
}








doc {Locking And Concurrency<br>In SQLite Version 3} {lockingv3.html} {
  A description of how the new locking code in version 3 increases
  concurrency and decreases the problem of writer starvation.
}

doc {Overview Of The Optimizer} {optoverview.html} {
................................................................................

doc {Compilation Options} {compile.html} {
  This document describes the compile time options that may be set to 
  modify the default behavior of the library or omit optional features
  in order to reduce binary size.
}










heading {Old Documents} {
  These documents either pertain to SQLite version 2 or were written
  during the transition period between versions 2 and 3. They are no longer
  strictly applicable to recent versions of SQLite, but the information

<title>SQLite Documentation</title>

<h2 align="center">Available Documentation</h2>
<table width="100%" cellpadding="5">

<tcl>
proc doc {name url desc} {
  hd_puts {<tr><td valign="top" align="right">}
  regsub -all { +} $name {\&nbsp;} name
  hd_puts "<a href=\"$url\">$name</a></td>"
................................................................................
  hd_puts {<td width="10"></td>}
  hd_puts {<td valign="top" align="left">}
  hd_resolve $desc
  hd_puts {</td></tr>}
}

proc heading {text {caption {}}} {
  hd_puts {<tr><td colspan=3 style="padding: 3ex 0 2ex 0">}
  hd_puts "<b>$text</b>"
  if {$caption ne ""} {
    hd_puts {<br />}
    hd_puts "$caption"
  }
}

heading {Overview Documents}

doc {Appropriate Uses For SQLite} {whentouse.html} {
  This document describes situations where SQLite is an appropriate
  database engine to use versus situations where a client/server
  database engine might be a better choice.
}
doc {Distinctive Features} {different.html} {
................................................................................
}
doc {Sharing Cache Mode} {sharedcache.html} {
  Version 3.3.0 and later supports the ability for two or more
  database connections to share the same page and schema cache.
  This feature is useful for certain specialized applications.
}
doc {Unlock Notify} {unlock_notify.html} {
  The "unlock notify" feature can be used in conjunction with
  [shared cache mode] to more efficiently manage resource conflict (database
  table locks).
}
doc {Asynchronous IO Mode} {asyncvfs.html} {
  This page describes the asynchronous IO extension developed alongside
  SQLite. Using asynchronous IO can cause SQLite to appear more responsive
  by delegating database writes to a background thread.
}
................................................................................
doc {Release History} {changes.html} {
  A chronology of SQLite releases going back to version 1.0.0
}
doc {Backwards Compatibility} {formatchng.html} {
  This document details all of the incompatible changes to the SQLite
  file format that have occurred since version 1.0.0.
}

doc {Private Branches} {privatebranch.html} {
  This document suggests procedures for maintaining a private branch
  or fork of SQLite and keeping that branch or fork in sync with the
  public SQLite source tree.
}

heading {SQLite Technical/Design Documentation}

doc {Temporary Files Used By SQLite} {tempfiles.html} {
  SQLite can potentially use many different temporary files when
  processing certain SQL statements.  This document describes the
  many kinds of temporary files that SQLite uses and offers suggestions
................................................................................
}

doc {How SQLite Implements Atomic Commit} {atomiccommit.html} {
  A description of the logic within SQLite that implements
  transactions with atomic commit, even in the face of power
  failures.
}

doc {Dynamic Memory Allocation in SQLite} {malloc.html} {
  SQLite has a sophisticated memory allocation subsystem that can be
  configured and customized to meet memory usage requirements of the
  application and that is robust against out-of-memory conditions and
  leak-free.  This document provides the details.
}

doc {Locking And Concurrency<br>In SQLite Version 3} {lockingv3.html} {
  A description of how the new locking code in version 3 increases
  concurrency and decreases the problem of writer starvation.
}

doc {Overview Of The Optimizer} {optoverview.html} {
................................................................................

doc {Compilation Options} {compile.html} {
  This document describes the compile time options that may be set to 
  modify the default behavior of the library or omit optional features
  in order to reduce binary size.
}

doc {Limits In SQLite} {limits.html} {
  This document describes limitations of SQLite (the maximum length of a
  string or blob, the maximum size of a database, the maximum number of
  tables in a database, etc.) and how these limits can be altered at
  compile-time and run-time.
}



heading {Old Documents} {
  These documents either pertain to SQLite version 2 or were written
  during the transition period between versions 2 and 3. They are no longer
  strictly applicable to recent versions of SQLite, but the information

use of SQLite for peak performance in demanding environments.
Nothing in this document is required knowledge for using SQLite.  The
default settings and configuration for SQLite will work well in most
applications.  However, the information contained in this document may
be useful to engineers who are tuning SQLite to comply with special
requirements or to run under unusual circumstances.</p>

<p><i>This report is a work in progress...</i></p>

<a name="features"></a>
<h2>1.0 Features</h2>

<p>The SQLite core and its memory allocation subsystem provides the 
following capabilities:</p>

<ul>
................................................................................
if malloc() or realloc() ever return NULL)
then SQLite will recover gracefully.   SQLite will first attempt
to free memory from unpinned cache pages then retry the allocation
request.  
Failing that, SQLite will either stop what
it is doing and return the
[SQLITE_NOMEM] error code back up to the application or it will
make due without the requested memory.
</p></li>

<li><p>
<b>No memory leaks.</b>
The application is responsible for destroying any objects it allocates.
(For example, the application must use [sqlite3_finalize()] on 
every [prepared statement] and [sqlite3_close()] on every 
................................................................................

</ul>

<a name="testing"></a>
<h2>2.0 Testing</h2>

<p>Over
75% of the code in the SQLite source tree is devoted purely to testing
and verification.  Reliability is important to SQLite.
Among the tasks of the test infrastructure is to insure that
SQLite does not misuse dynamically allocated memory, that SQLite
does not leak memory, and that SQLite responds
correctly to a dynamic memory allocation failure.</p>

<p>The test infrastructure verifies that SQLite does not misuse
dynamically allocated memory by using a specially instrumented
................................................................................
Note also that the OOM overlay can work with any underlying memory
allocator, including the instrumented memory allocator that checks
for memory allocation misuse.  In this way it is verified that 
OOM errors do not induce other kinds of memory usage errors.</p>

<p>Finally, we observe that the instrumented memory allocator and the
memory leak detector both work over the entire SQLite test suite and
the test suite provides over 99% statement test coverage.  This is


strong evidence that dynamic memory allocation is used correctly
everywhere within SQLite.</p>

<a name="config"></a>
<h2>3.0 Configuration</h2>

<p>The default memory allocation settings in SQLite are appropriate

use of SQLite for peak performance in demanding environments.
Nothing in this document is required knowledge for using SQLite.  The
default settings and configuration for SQLite will work well in most
applications.  However, the information contained in this document may
be useful to engineers who are tuning SQLite to comply with special
requirements or to run under unusual circumstances.</p>



<a name="features"></a>
<h2>1.0 Features</h2>

<p>The SQLite core and its memory allocation subsystem provides the 
following capabilities:</p>

<ul>
................................................................................
if malloc() or realloc() ever return NULL)
then SQLite will recover gracefully.   SQLite will first attempt
to free memory from unpinned cache pages then retry the allocation
request.  
Failing that, SQLite will either stop what
it is doing and return the
[SQLITE_NOMEM] error code back up to the application or it will
make do without the requested memory.
</p></li>

<li><p>
<b>No memory leaks.</b>
The application is responsible for destroying any objects it allocates.
(For example, the application must use [sqlite3_finalize()] on 
every [prepared statement] and [sqlite3_close()] on every 
................................................................................

</ul>

<a name="testing"></a>
<h2>2.0 Testing</h2>

<p>Over
75% of the code in the SQLite source tree is devoted purely to 
[testing | testing and verification].  Reliability is important to SQLite.
Among the tasks of the test infrastructure is to insure that
SQLite does not misuse dynamically allocated memory, that SQLite
does not leak memory, and that SQLite responds
correctly to a dynamic memory allocation failure.</p>

<p>The test infrastructure verifies that SQLite does not misuse
dynamically allocated memory by using a specially instrumented
................................................................................
Note also that the OOM overlay can work with any underlying memory
allocator, including the instrumented memory allocator that checks
for memory allocation misuse.  In this way it is verified that 
OOM errors do not induce other kinds of memory usage errors.</p>

<p>Finally, we observe that the instrumented memory allocator and the
memory leak detector both work over the entire SQLite test suite and
the [TCL test suite] provides over 99% statement test coverage and that
the [TH3] test harness provides [test coverage | 100% branch test coverage]
with no leak leaks. This is
strong evidence that dynamic memory allocation is used correctly
everywhere within SQLite.</p>

<a name="config"></a>
<h2>3.0 Configuration</h2>

<p>The default memory allocation settings in SQLite are appropriate

core SQLite library.
Each test harness is designed, maintained, and managed separately
from the others.
</p>

<ol>
<li><p>

The <b>TCL Tests</b> are the oldest set of tests for SQLite.  
The TCL tests are contained in the same source tree as the
SQLite core and like the SQLite core are in the public domain.  The
TCL tests are the primary tests used during development.
The TCL tests are written using the 
<a href="http://www.tcl.tk/">TCL scripting language</a>.
The TCL test harness itself consists of <tcl>KB {$stat(tclcSLOC)}</tcl> KSLOC 

core SQLite library.
Each test harness is designed, maintained, and managed separately
from the others.
</p>

<ol>
<li><p>
<tcl>hd_fragment tcl {TCL test suite}</tcl>
The <b>TCL Tests</b> are the oldest set of tests for SQLite.  
The TCL tests are contained in the same source tree as the
SQLite core and like the SQLite core are in the public domain.  The
TCL tests are the primary tests used during development.
The TCL tests are written using the 
<a href="http://www.tcl.tk/">TCL scripting language</a>.
The TCL test harness itself consists of <tcl>KB {$stat(tclcSLOC)}</tcl> KSLOC 

    if {[regexp {^http} $ref4]} continue
    if {$ref4==""} continue
    if {[regexp {\.html$} $ref4]} {
      lappend pagelink($ref4) $fn
    }
  }
}




# Enable or disable the main output file.
#
proc hd_enable_main {boolean} {
  global hd
  set hd(enable-main) $boolean
}
................................................................................
    hd_puts "<a href=\"$ref\">$ref</a> "
    set prev $ref
  }
  hd_puts "</li>"
}
hd_puts "</ul>"
hd_close_main

    if {[regexp {^http} $ref4]} continue
    if {$ref4==""} continue
    if {[regexp {\.html$} $ref4]} {
      lappend pagelink($ref4) $fn
    }
  }
}
proc hd_putsnl {text} {
  hd_puts $text\n
}

# Enable or disable the main output file.
#
proc hd_enable_main {boolean} {
  global hd
  set hd(enable-main) $boolean
}
................................................................................
    hd_puts "<a href=\"$ref\">$ref</a> "
    set prev $ref
  }
  hd_puts "</li>"
}
hd_puts "</ul>"
hd_close_main