Documentation Source Text

docdir:
	mkdir -p doc 

doc:	sqlite3.h docdir always
	rm -rf doc/images
	cp -r $(DOC)/images doc
	cp $(SRC)/art/*.gif doc/images
	cp $(DOC)/rawpages/* doc
	tclsh $(DOC)/wrap.tcl $(DOC) $(SRC) doc $(DOC)/pages/*.in

always:	


clean:	

</p>

<h3>Features:</h3>

<p><ul>
<li><a href="transactional.html">Transactions</a>
    are atomic, consistent, isolated, and durable (ACID)
    even after system crashes and power failures.</li>
<li><a href="zeroconf.html">Zero-configuration</a>
     - no setup or administration needed.</li>
<li>Implements most of SQL92.
    (<a href="omitted.html">Features not supported</a>)</li>
<li>A complete database is stored in a single disk file.</li>
<li>Database files can be freely shared between machines with
    different byte orders.</li>
<li>Supports terabyte-sized databases and gigabyte-sized strings
    and blobs.  (See <a href="limits.html">limits.html</a>.)
<li>Small code footprint: 
    <a href="http://www.sqlite.org/cvstrac/wiki?p=SizeOfSqlite">
    less than 250KiB</a> fully configured or less
    than 150KiB with optional features omitted.</li>
<li><a href="speed.html">Faster</a> than popular client/server database
    engines for most common operations.</li>
<li>Simple, easy to use <a href="c3ref/intro.html">API</a>.</li>
<li><a href="tclsqlite.html">TCL bindings</a> included.
    Bindings for many other languages 
    <a href="http://www.sqlite.org/cvstrac/wiki?p=SqliteWrappers">
    available separately.</a></li>
<li>Well-commented source code with over 98% test coverage.</li>
<li>Available as a 
    <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation">

<title>Well-Known Users Of SQLite</title>

<h2>Well-Known Users of SQLite:</h2>

<p>
List below are a few of the better-known users of SQLite.
There is no complete list of projects and companies
that use SQLite.
SQLite is in the public domain and so many people use it
in their projects without ever telling us.
</p>

<table border="0" cellpadding="15">

<tr><td valign="top">
<a href="http://www.adobe.com/">
<img src="foreignlogos/adobe.gif" border="0"></a>
</td><td valign="top">
<a href="http://www.adobe.com/">Adobe</a> uses SQLite as the 
<a href="whentouse.html#appfileformat">application 
file format</a> for their 
<a href="http://www.adobe.com/products/photoshoplightroom/">
Photoshop Lightroom</a> product.
This is publically acknowledged on the Lightroom/About_Lightroom menu popup.
Adobe has also announced that their 
<a href="http://labs.adobe.com/technologies/air/">AIR project</a>
will include SQLite.   It
is reported that 
<a href="http://www.adobe.com/products/acrobat/readstep2.html">Acrobat 
Reader</a> also uses SQLite.
</td></tr>

<tr><td valign="top">
<a href="http://www.apple.com/">
<img src="foreignlogos/apple.gif" border="0">
</a></td>
<td valign="top">
<a href="http://www.apple.com/">Apple</a> uses SQLite for many functions 
within Mac OS-X, including 
<a href="http://www.apple.com/macosx/features/mail.html">Apple Mail</a>, 
<a href="http://www.apple.com/macosx/features/safari.html">Safari</a>, 
and in <a href="http://www.apple.com/aperature/">Aperture</a>.
There are reports on the internet that Apple also uses SQLite in
the <a href="http://www.apple.com/iphone/">iPhone</a> and in the
<a href="http://www.apple.com/ipodtouch/">iPod touch</a>.
</td></tr>

<tr><td valign="top">
<a href="http://www.mozilla.com/">
<img src="foreignlogos/firefox.gif" border="0">
</a>
</td>
<td>
The <a href="http://www.mozilla.com/">Firefox Web Browser</a> from Mozilla 
has been slowly replacing their legacy file format "mork" with SQLite
for about two years.  At this point, SQLite is used to store most of
the persistent metadata in SQLite.
</td></tr>


<tr><td valign="top">
<a href="http://www.ge.com/">
<img src="foreignlogos/ge.gif" border="0"></a>
</td><td>
We believe that <a href="http://www.ge.com/">General Electric</a>
uses SQLite in some product or 
another because they twice wrote the to SQLite developers requesting 
the US Export Control Number for SQLite. So presumably GE is using
SQLite in something that they are exporting. But nobody
(outside of GE) seems to know what that might be.
</td>


<tr><td valign="top">
<a href="http://www.google.com/">
<img src="foreignlogos/google.gif" border="0"></a>
</td>
<td>
It is known that
<a href="http://www.google.com/">Google</a>
uses SQLite in their 
<a href="http://desktop.gooogle.com/mac/legal.html">Desktop for Mac</a>,
in <a href="http://code.google.com/apis/gears/api_database.html">Google 
Gears</a>, and in the
<a href="http://code.google.com/android/">Android</a> cell-phone 
operating system.
People are suspicious that Google uses SQLite for lots of other things
that we do not know about yet.
Engineers at Google have made extensive contributions to the
full-text search subsystem within SQLite.
</td>

<tr><td valign="top">
<a href="http://www.mcafee.com/">
<img src="foreignlogos/mcaffee.gif" border="0"></a></td>
<td>
<a href="http://www.mcafee.com/">McAfee</a> uses SQLite in its antivirus 
programs.  
Mentioned <a href="http://www.mail-archive.com/sqlite-users@sqlite.org/msg16931.html">here</a> and implied 
<a href="http://forums.mcafeehelp.com/viewtopic.php?t=115260">here</a>.
</td>


<tr><td valign="top">
<a href="http://www.microsoft.com/">
<img src="foreignlogos/microsoft.gif" border="0"></a>
</td>
<td>
It can inferred from 
<a href="http://www.mail-archive.com/sqlite-users@sqlite.org/msg19226.html">
traffic on the SQLite mailing list</a> that at least
one group within 
<a href="http://www.microsoft.com/">Microsoft</a>
is using SQLite in the development of a 
game program. No word yet if this game has actually been released or
if they are still using SQLite.
</td>


<tr><td valign="top">
<a href="http://monotone.ca">
<img src="foreignlogos/monotone.gif" border="0"></a>
</td><td>
The 
<a href="http://monotone.ca">Monotone</a>
 configuration management system stores an entire project history in 
an SQLite database. Each file is a separate BLOB.
</td>


<tr><td valign="top">
<a href="http://www.philips.com/">
<img src="foreignlogos/philips.gif" border="0"></a>
</td><td>
It is reported that 
<a href="http://www.consumer.philips.com/portablemp3/">Philips MP3 Players</a>
use SQLite to store metadata about the music they hold.
Apparently, if you plug a Philips MP3 player into your USB port, you
can see the SQLite database file there in plain sight.
</td>


<tr><td valign="top">
<a href="http://www.php.net/">
<img src="foreignlogos/php.gif" border="0"></a>
</td><td>
The popular 
<a href="http://www.php.net/">PHP</a>
programming language comes with both SQLite2 and SQLite3 built in.
</td></t>

<tr><td valign="top">
<a href="http://www.python.org/">
<img src="foreignlogos/python.gif" border="0"></a>
</td><td>
SQLite comes bundled with the 
<a href="http://docs.python.org/lib/module-sqlite3.html">Python</a>
programming langauge since Python 2.5.
</td></tr>

<tr><td valign="top">
<a href="http://www.realbasic.com/">
<img src="foreignlogos/realbasic.gif" border="0"></a>
</td><td>
The <a href="http://www.realbasic.com/">REALbasic</a>
programming environment comes bundled with an enhanced version of 
SQLite that supports AES encryption.
</td></tr>

<tr><td valign="top">
<a href="http://www.skype.com/">
<img src="foreignlogos/skype.gif" border="0"></a>
</td><td>
There are 
<a href="http://www.mail-archive.com/sqlite-users%40sqlite.org/msg27326.html">
multiple</a> 
<a href="http://www.mail-archive.com/sqlite-users%40sqlite.org/msg27332.html">
sightings</a> of SQLite in the Skype client for MacOSX and Windows.
</td></tr>

<tr><td valign="top">
<a href="http://www.sun.com/">
<img src="foreignlogos/sunmicro.gif" border="0"></a>
</td><td>
<a href="http://www.sun.com/software/solaris/">Solaris 10</a>
uses SQLite as the storage format for its Service Management Facility.
Thus, Sun as essentially replaced the traditional unix /etc/inittab
file with an SQLite database.
</td></tr>

<tr><td valign="top">
<a href="http://www.symbian.com/">
<img src="foreignlogos/symbian.gif" border="0"></a>
</td><td>
SQLite is an integral part of 
<a href="http://www.symbian.com/">Symbian's</a> operating system commonly 
found on high-end cellphones.
</td></tr>

<tr><td valign="top">
<a href="http://www.toshiba.com/">
<img src="foreignlogos/toshiba.gif" border="0"></a>
</td><td>
A representative of 
<a href="http://www.toshiba.com/">Toshiba</a> wrote to the SQLite developers 
and requested the US Export Control Number for SQLite. We infer from this 
that Toshiba is exporting something from the US that uses SQLite, but we 
do not know what that something is.
</td></tr>
</table>

<tr><td valign="top">
<b>Quick&nbsp;Links</b>
</td><td valign="top">
<li> More details <a href="about.html">about SQLite</a> - what it is and what
     it is not.</li>
<li> <a href="faq.html">Frequently Asked Questions</a> about SQLite. </li>
<li> <a href="famous.html">Well-known users</a> of SQLite.</li>

<li> <a href="http://www.sqlite.org/cvstrac/timeline">Timeline</a> of recent
     development activity. </li>
</td></tr>
</table>

  puts "<tr><td valign=\"top\"><b><nobr>$name</nobr></b></td>"
  puts "<td width=\"10\">&nbsp;</th>"
  puts "<td valign=\"top\">$desc</td></tr>"
}

feature {FOREIGN KEY constraints} {
  FOREIGN KEY constraints are parsed but are not enforced.
  However, the equivalent constraint enforcement can be achieved
  using triggers.
}

feature {Complete trigger support} {
  There is some support for triggers but it is not complete.  Missing
  subfeatures include FOR EACH STATEMENT triggers (currently all triggers
  must be FOR EACH ROW), INSTEAD OF triggers on tables (currently 
  INSTEAD OF triggers are only allowed on views), and recursive

<title>SQLite Is Self-Contained</title>

<h2>SQLite Is Self-Contained</h2>

<p>
SQLite is largely self-contained.  It requires very minimal
support from external libraries or from the operating system.
This makes it well suited for use in embedded devices that
lack the support infrastructure of a desktop computer.  This
also makes SQLite appropriate for use within applications that
need to run without modification on a wide variety of computers
of varying configurations.
</p>

<p>
SQLite is written in ANSI-C and should be easily compiled by
any standard C compiler.  It makes minimal use of the standard C
library.   The only required C library functions called are:
</p>

<ul>
<li> memset()
<li> memcpy()
<li> memcmp()
<li> strcmp()
<li> malloc(), free(), and realloc()
</ul>

<p>
SQLite can be configured at compile-time to use a static
buffer in place of calling malloc for the memory it needs.
The date and time SQL functions provided by SQLite require
some additional C library support, but those functions can
be also be omitted from the build using compile-time options.
</p>

<p>
Communications between SQLite and the operating system and disk are
mediated through an interchangable Virtual File System (VFS) layer.
VFS modules for Unix (linux and MacOSX), OS/2, Win32, and WinCE are
provided in the source tree.  It is a simple matter to devise an
alternative VFS for embedded devices. 
</p>

<p>
The SQLite source code is available as an
"amalgamation" - a single large C source code file.
Projects that want to include SQLite can do so simply
by dropping this one source file (named "sqlite3.c") and
its corresponding header ("sqlite3.h") into their source
tree and compiling it together with the rest of the
code.  SQLite does not link against any external libraries
(other than the C library, as described above) and does
require any special build support.
</p>

<title>SQLite Is Serverless</title>

<h2>SQLite Is Serverless</h2>

<p>
Most SQL database engines are implemented as a separate server process.
Programs that want to access the database communicate with the server
using some kind of interprocess communcation (typically TCP/IP) to send 
requests to the server and to receive back results. 
SQLite does not work this way. 
With SQLite, the process that wants to access the database reads and 
writes directly from the database files on disk. 
There is no intermediary server process.
</p>

<p>
There are advantages and disadvantages to being serverless.
The main advantage is that there is no separate server process
to install, setup, configure, initialize, manage, and troubleshoot. 
This is one reason why SQLite is a 
"<a href="zeroconf.html">zero-configuration</a>" database engine. 
Programs that use SQLite require no administrative support for 
setting up the database engine before they are run.
Any program that is able to access the disk is able to use an SQLite database.
</p>

<p>
On the other hand, a database engine that uses a server can 
provide better protection from bugs in the client 
application - stray pointers in a client cannot corrupt memory 
on the server. 
And because a server is a single persistent process,
it is able control database access with more precision, 
allowing for finer grain locking and better concurrancy.
</p>

<p>
Most SQL database engines are client/server based. 
Of those that are serverless, SQLite is the only one that 
known to this author that allows multiple applications
to access the same database at the same time. 
</p>

<title>SQLite Is Transactional</title>

<p>A transactional database is one in which all changes and queries
appear to be
Atomic, Consistent, Isolated, and Durable
(<a href="http://en.wikipedia.org/wiki/ACID">ACID</a>).
SQLite implements 
<a href="http://en.wikipedia.org/wiki/Serializability">serializable</a>
transactions that are atomic, consistent, isolated, and durable,
even if the transaction is interrupted by a program crash, an
operating system crash, or a power failure to the computer.
</p>

SQLite is a good choice for devices or services that must work
unattended and without human support.  SQLite is a good fit for
use in cellphones, PDAs, set-top boxes, and/or appliances.  It also
works well as an embedded database in downloadable consumer applications.
</p>
</li>

<a name="appfileformat"></a>
<li><p><b>Application File Format</b></p>

<p>
SQLite has been used with great success as the on-disk file format
for desktop applications such as financial analysis tools, CAD
packages, record keeping programs, and so forth.  The traditional
File/Open operation does an sqlite3_open() and executes a

<title>Zero-Configuration</title>

<h2>SQLite Is A Zero-Configuration Database</h2>

<p>
SQLite does not need to be "installed" before it is used. 
There is no "setup" procedure.  There is no
server process that needs to be started, stopped, or configured.
There is
no need for an administrator to create a new database instance or assign
access permissions to users.
SQLite uses no configuration files.
Nothing needs to be done to tell the system that SQLite is running.
No actions are required to recover after a system crash or power failure.
There is nothing to troubleshoot.
</p>


<p>
SQLite just works.
</p>

<p>
Other database engines may run great once you get them going.
But doing the initial installation and configuration can often
be intimidating.
</p>

#     *  Scripts within <tcl>...</tcl> are evaluated.  Output that
#        is emitted from these scripts by "puts" appears in place of
#        the original script.
#
set DOC [lindex $argv 0]
set SRC [lindex $argv 1]
set DEST [lindex $argv 2]
set HOMEDIR [pwd]            ;# Also remember our home directory.

# We are going to overload the puts command, so remember the
# original puts command using an alternative name.
rename puts real_puts
proc puts {text} {
  real_puts $::OUT $text
  flush $::OUT
}

# putsin4 is like puts except that it removes the first 4 indentation
# characters from each line.  It also does variable substitution in
# the namespace of its calling procedure.
#
proc putsin4 {text} {
  regsub -all "\n    " $text \n text
  real_puts $::OUT [uplevel 1 [list subst -noback -nocom $text]]
  flush $::OUT
}

# A procedure to write the common header found on every HTML file on
# the SQLite website.
#
proc PutsHeader {title {relpath {}}} {
  puts {<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">}
  puts {<html><head>}
  puts "<title>$title</title>"
  putsin4 {<style type="text/css">
    body {
        max-width: 800px; /* not supported in IE 6 */

    </style>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  }
  puts {</head>}
  putsin4 {<body>
    <div><!-- container div to satisfy validator -->
    
    <img class="logo" src="${relpath}images/SQLite.gif" alt="SQLite Logo">
    <div><!-- IE hack to prevent disappearing logo--></div>
    <div class="tagline">The World's Most Widely Used SQL Database.</div>
    
    <div class="toolbar">
      <a href="${relpath}index.html">Home</a>
      <a href="${relpath}about.html">About</a>
      <a href="${relpath}docs.html">Documentation</a>
      <a href="${relpath}download.html">Download</a>
      <a href="${relpath}copyright.html">License</a>
      <a href="${relpath}press.html">Advocacy</a>
      <a href="${relpath}devhome.html">Developers</a>
      <a href="${relpath}news.html">News</a>
      <a href="${relpath}support.html">Support</a>
      <!-- rounded corners -->
      <div class="ne"></div><div class="se"></div><div class="nw">
      </div><div class="sw"></div>
    </div>
  }
}

# A procedure to write the common footer found at the bottom of
# every HTML file.  $srcfile is the name of the file that is the
# source of the HTML content.  The modification time of this file
# is used to add the "last modified on" line at the bottom of the
# file.
#
proc PutsFooter {srcfile} {
  puts {<hr><small><i>}
  set mtime [file mtime $srcfile]
  set date [clock format $mtime -format {%Y/%m/%d %H:%M:%S UTC} -gmt 1]
  puts "This page last modified $date"
  puts {</i></small></div></body></html>}
}

    regsub -all {RP} $body {</font></b>)<b><font color="#2c2cf0">} body
    ## Place the left-hand side of the rule in the 2nd table column.
    puts "<td><b><font color=\"#2c2cf0\">$body</font></b></td></tr>"
  }
  puts {</table>}
}

# Loop over all input files and process them one by one
#
foreach infile [lrange $argv 3 end] {
  cd $HOMEDIR
  real_puts "Processing $infile"
  set fd [open $infile r]
  set in [read $fd]
  close $fd
  set title {No Title}