Documentation Source Text

    }
    if( zAgent==0 || zAgent[0]==0 ) zAgent = "*";
    time(&now);
    pTm = localtime(&now);
    strftime(zDate, sizeof(zDate), "%Y-%m-%d %H:%M:%S", pTm);
    times(&sTms);
    rScale = 1.0/(double)sysconf(_SC_CLK_TCK);
    chdir((zRoot && zRoot[0]) ? zRoot : "/");
    if( (log = fopen(zLogFile,"a"))!=0 ){
      fprintf(log, "%s %s %s://%s%s %s %s %d %d %g %g %g %g %d %d %s %s\n", 
          zDate, zRemoteAddr, zHttp, zHttpHost, zScript, zReferer,
          zReplyStatus, nIn, nOut,
          rScale*sTms.tms_utime,
          rScale*sTms.tms_stime,
          rScale*sTms.tms_cutime,

        foreach k $kx {
          set keyword($k) 1
        }
      } elseif {[regexp {^EXPERIMENTAL} $lx]} {
        set exflag 1
      } elseif {[regexp {^DEPRECATED} $lx]} {
        set obsflag 1
      } elseif {[regexp {^FRAGMENT: +(.*)} $lx all kx]} {
        set fragname [lindex $kx 0]
        append body "<a name=\"$fragname\"></a>\n"
        
      } else {
        append body $lx\n
      }
    } elseif {[string range $line 0 1]=="*/"} {
      # When we reach the end of the block comment that contained the
      # CAPI3REF keyword, that ends the description.  Switch to phase 3
      # in order to begin picking up the interface definition.

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>}

# Convert a fragment text label into a fragment name
#
proc hd_fragname {lbl} {
  regsub -all {[^a-z0-9]} [string tolower $lbl] {} lbl2
  set x [string range $lbl2 0 10]
  if {[string length $lbl2]>10} {
    append x [string length $lbl2]
  }
}


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

  hd_puts "$code"
  hd_puts "</pre></blockquote>"
  if {$supported($kw)==1} {
    hd_resolve {<p><b>Important:</b> This interface is [experimental] }
    hd_resolve {and is subject to change without notice.</p>}
  }
  regsub -all "\n\n+" $body "</p>\n\n<p>" body
  set body <p>$body</p>
  while {[regexp {^(.*?)\[\[([^]]*)\]\](.*)$} $body all fore anchor aft]} {
    hd_resolve $fore
    set anchor [string trim $anchor]
    hd_fragment [hd_fragname $anchor] $anchor
    set body $aft
  }
  hd_resolve $body
  hd_enable_main 0
  hd_puts {<p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>}
  hd_enable_main 1
  hd_close_aux
  hd_puts "<hr>"
}
</tcl>

      <a href="http://www.sqlite.org/src/timeline">
      http://www.sqlite.org/src/timeline</a>.</p>
    }
    hd_close_aux
    hd_enable_main 1
  }
}

chng {2011 June 28 (3.7.7)} {
<li> Add support for [URI filenames]
<li> Add support for [ON CONFLICT] clauses with [virtual tables].
<li> Avoid unnecessary reparsing of the database schema.
<li> Allow [WAL | WAL-mode] databases to be opened read-only as long as
     there is an existing read/write connection.
}

chng {2011 April 17 (3.7.6.2)} {
<li> Fix the function prototype for the open(2) system call to agree with
     POSIX.  Without this fix, pthreads does not work correctly on NetBSD.
<li> SQLITE_SOURCE_ID:
     "2011-04-17 17:25:17 154ddbc17120be2915eb03edc52af1225eb7cb5e"
<li> SHA1 for sqlite3.c: 806577fd524dd5f3bfd8d4d27392ed2752bc9701

  [PRAGMA temp_store] command to override</td></tr>
  <tr><td align="center">3</td><td>Always use memory</td></tr>
  </table>

  The default setting is 1.  
  Additional information can be found in [tempstore | tempfiles.html].
}

COMPILE_OPTION {SQLITE_USE_URI} {
  This option causes the [URI filename] process logic to be enabled by 
  default.  
}

</tcl>

<a name="enablefeatures"></a>
<h2>1.4 Options To Enable Features Normally Turned Off</h2>

<tcl>
COMPILE_OPTION {SQLITE_ENABLE_ATOMIC_WRITE} {

</td>
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_7_7.html">Version 3.7.7</a>
of SQLite is recommended for all new development.
Upgrading from version 3.7.5 or 3.7.6.2 is optional.
Upgrading from all SQLite versions prior to 3.7.5 is recommended.</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>
<li> <a href="features.html">Features</a> </li>

file to the current [database connection]. 
^The filename for the database to be attached is the value of
the expression that occurs before the AS keyword.
^The filename of the database follows the same semantics as the
filename argument to [sqlite3_open()] and [sqlite3_open_v2()]; the
special name "[:memory:]" results in an in-memory database and an
empty string results in a new temporary database.
^The filename argument can be a [URI filename] if URI filename processing
is enable on the database connection.
The name that occurs after the AS keyword is the name of the database
used internally by SQLite.
^The database-names 'main' and 
'temp' refer to the main database and the database used for 
temporary tables.  ^The main and temp databases cannot be attached or
detached.</p>

    the middle of a transaction when the MEMORY journaling mode is set,
    then the database file will very likely go corrupt.</p>

    <p>^The WAL journaling mode uses a [write-ahead log] instead of a
    rollback journal to implement transactions.  ^The WAL journaling mode
    is persistent; after being set it stays in effect
    across multiple database connections and after closing and
    reopening the database.  A database in WAL journaling mode
    can only be accessed by SQLite version 3.7.0 or later.</p>

    <p>^The OFF journaling mode disables the rollback journal completely.
    ^No rollback journal is ever created and hence there is never a rollback
    journal to delete.  The OFF journaling mode disables the atomic
    commit and rollback capabilities of SQLite. The [ROLLBACK] command
    no longer works; it behaves in an undefined way.  Applications must
    avoid using the [ROLLBACK] command when the journal mode is OFF.
    ^If the application crashes
    in the middle of a transaction when the OFF journaling mode is
    set, then the database file will very likely go corrupt.</p>

}


Pragma legacy_file_format {
   <p>^(<b>PRAGMA legacy_file_format;
       <br>PRAGMA legacy_file_format = <i>boolean</i></b></p>
    <p>This pragma sets or queries the value of the legacy_file_format
    flag.)^  ^(When this flag is on, new SQLite databases are created in
    a file format that is readable and writable by all versions of
    SQLite going back to 3.0.0.)^  ^(When the flag is off, new databases
    are created using the latest file format which might not be
    readable or writable by versions of SQLite prior to 3.3.0.)^</p>

    <p>^When the legacy_file_format pragma is issued with no argument,
    it returns the setting of the flag.  ^This pragma does <u>not</u> tell
    which file format the current database is using; it tells what format
    will be used by any newly created databases.</p>

    <p>^The legacy_file_format pragma is initialized to OFF when an existing
    database in the newer file format is first opened.</p>

    <p>^The default file format is set by the
    [SQLITE_DEFAULT_FILE_FORMAT] compile-time option.</p>
}

Pragma locking_mode {
    <p>^(<b>PRAGMA locking_mode;

   EXCLUSIVE and back again at any time and without needing to exit
   WAL journal mode.</p>
}

Pragma page_size {
   <p>^(<b>PRAGMA page_size;
       <br>PRAGMA page_size = </b><i>bytes</i><b>;</b></p>
    <p>Query or set the page size of the database.)^ ^The page

    size must be a power of two between 512 and 65536 inclusive.

    </p>

    <p>^When a new database is created, SQLite assigned a default page size
    based on information received from the xSectorSize and 
    xDeviceCharacteristics methods of the [sqlite3_io_methods] object
    of the newly created database file.  ^The page_size pragma will only
    cause an immediate change in the
    page size if it is issued while the database is still empty, prior 
    to the first CREATE TABLE statement.  ^(If the page_size pragma is
    used to specify a new page size just prior to
    running the [VACUUM] command and if the database is not in
    [WAL | WAL journal mode] then [VACUUM] will change the page
    size to the new value.)^</p>

    <p>^If SQLite is compiled with the SQLITE_ENABLE_ATOMIC_WRITE option,
    then the default page size is chosen to be the largest page size
    less than or equal to SQLITE_MAX_DEFAULT_PAGE_SIZE for which atomic
    write is enabled according to the
    xDeviceCharacteristics method of the [sqlite3_io_methods] object for
    the database file.  ^If the SQLITE_ENABLE_ATOMIC_WRITE option is
    disabled or if xDeviceCharacteristics reports no suitable atomic
    write page sizes, then the default page size is the larger of 
    SQLITE_DEFAULT_PAGE_SIZE
    and the sector size as reported by the xSectorSize method of the
    [sqlite3_io_methods] object, but not more than 
    SQLITE_MAX_DEFAULT_PAGE_SIZE.  ^The normal configuration for SQLite
    running on workstations is for atomic write to be
    disabled, for the maximum page size to be set to 65536, for
    SQLITE_DEFAULT_PAGE_SIZE to be 1024, and for the
    maximum default page size to be set to 8192.  The default xSectorSize

DebugPragma parser_trace {
    <p><b>PRAGMA parser_trace = </b><i>boolean</i><b>; </b></p>

    DISCLAIMER

    <p>If SQLite has been compiled with the [SQLITE_DEBUG] compile-time
    option, then the parser_trace pragma can be used to turn on tracing
    for the SQL parser used internally by SQLite.
    This feature is used for debugging SQLite itself.</p>
}

DebugPragma vdbe_trace {
    <p><b>PRAGMA vdbe_trace = </b><i>boolean</i><b>;</b></p>

    DISCLAIMER

<title>Uniform Resource Identifiers</title>
<tcl>
hd_keywords {URI} {Uniform Resource Identifier} {URI filename} {URI filenames}
</tcl>

<h1>1.0 URI Filenames In SQLite</h1>

<p>
Beginning with [version 3.7.7], the SQLite database file argument to the
[sqlite3_open()], [sqlite3_open16()], and [sqlite3_open_v2()] interfaces
and to the [ATTACH] command can be specified
either as an ordinary filename or as a Uniform Resource Identifier or URI.
The advantage of using a URI filename is that query parameters on the URI can
be used to control details of the newly created database connection.
For example, an alternative [VFS] can be specified using "vfs=" query parameter.
Or the database can be opened read-only by using "mode=ro" as a query
parameter.
</p>

<h1>2.0 Backwards Compatibility</h1>

<p>
In order to maintain full backwards compatibility for legacy applications,
the URI filename capability is disabled by default.  
^(In order for URI filenames
to work, one or more of the following must be true:
</p>

<ol>
<li><p>The SQLite library is compiled with the [SQLITE_USE_URI] 
       compile-time option.</p></li>
<li><p>The [sqlite3_config]([SQLITE_CONFIG_URI], 1); configuration option
       is set at application start-time.</p></li>
<li><p>The [SQLITE_OPEN_URI] bit is OR-ed in with the set bits passed in
       as the 3rd parameter to the [sqlite3_open_v2()] interface.</p></li>
</ol>)^

<p>
^If URI filenames are recognized when the database connection is originally
opened, then URI filenames will also be recognized on [ATTACH] statemenets.
^Similarly, if URI filenames are not recognized when the database connection
is first opened, they will not be recognized by [ATTACH].
</p>

<p>
Since SQLite always interprets any filename that does not begin 
with "<tt>file:</tt>" is interpreted
as an ordinary filename regardless of the URI setting, and because it is
very unusual to have an actual file that beings with "<tt>file:</tt>", for
most applications it is safe to enable URI processing even if URI filenames
are not currently being used.
</p>

<h1>3.0 URI Format</h1>

<p>
According to [http://tools.ietf.org/html/rfc3986 | RFC 3986], a URI consists
of a scheme, an authority, a path, a query string, and a fragment.  The
scheme is always required.  One of either the authority or the path is also
always required.  The query string and fragment are optional.
</p>

<p>
SQLite uses the "<tt>file:</tt>" URI syntax to identify database files.
SQLite strives to interpret file: URIs in exactly the same way as
popular web-browsers such as 
[http://www.mozilla.com/en-US/firefox/new/ | Firefox], 
[http://www.google.com/chrome/ | Chrome], 
[http://www.apple.com/safari/ | Safari], 
[http://windows.microsoft.com/en-US/internet-explorer/products/ie/home | Internet Explorer], and
[http://www.opera.com/ | Opera],
and command-line programs such as 
[http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/start.mspx | Windows "start"] and the
[http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/open.1.html | "open"] command on Mac OS-X.
A succinct summary of the URI parsing rules follows:
</p>

<ul>
<li> ^(The scheme of the URI must be "<tt>file:</tt>".  Any other scheme
     results in the input being treated as an ordinary filename.)^
<li> ^(The authority may be omitted, may be blank, or may be
      "<tt>localhost</tt>".  Any other authority results in an error.)^
<li> ^The path is optional if the authority is present.  ^If the authority
     is omitted then the path is required. 
<li> ^The query string is optional.  ^If the query string is present, then
      all query parameters are passed through into the xOpen method of
      the underlying [VFS].  
<li> ^(The fragment is optional.  If present, it is ignored.)^
</ul>

<p>^Zero or more escape sequences of the form  "<b>%<i>HH</i></b>" 
(where <b><i>H</i></b> represents any hexadecimal digit) can occur 
in the path, query string, or fragment.</p>

<p>^A filename that is not a well-formed URI is interpreted as an
ordinary filename.</p>

<p>^URIs are processed as UTF8 text.
^The filename argument sqlite3_open16() is converted from UTF16 
native byte order into UTF8 prior to processing.

<h2>3.1 The URI Path</h2>

<p>^The path component of the URI specifies the disk file that is the
SQLite database to be opened.  ^(If the path component is omitted, then
a temporary files is opened as a new database that will be automatically
deleted when the database connection closes.)^  ^If the authority section
is present, then the path is alway an absolute pathname.  ^If the 
authority section is omitted, then the path is an absolute pathname if it
begins with the "/" character (ASCII code 0x2f) and is a relative
pathname otherwise.  ^(On windows, if the absolute path begins with
"<b>/<i>X</i>:/</b>" where <b><i>X</i></b> is any single ASCII alphabetic
character ("a" through "z" or "A" through "Z") then the "<b><i>X:</i></b>"
is understood to be the drive letter of the the volume containing the file,
not the toplevel directory.)^

<p>An ordinary filename can usually be converted into an equivalent URI 
by the step shown below.  The one exception is that a relative windows
pathname with a drive letter cannot be converted directly into a URI; it must
be changed into an absolute pathname first.</p>

<ol>
<li>Convert all "<tt>?</tt>" characters into "<tt>%3f</tt>".
<li>Convert all "<tt>#</tt>" characters into "<tt>%23</tt>".
<li>On windows only, convert all "<tt>\</tt>" characters into "<tt>/</tt>".
<li>Convert all sequences of two or more "<tt>/</tt>" characters into a
    single "<tt>/</tt>" character.
<li>On windows only, if the filename begins with a drive letter, prepend
    a single "<tt>/</tt>" character.
<li>Prepend the "<tt>file:</tt>" scheme.
</ol>

<h2>3.2 Query String</h2>

<p>^A URI filename can optionally be followed by a query string.
^The query string consists of text following the first "<tt>?</tt>"
character but exluding the optional fragment that begins with with
"<tt>#</tt>".  ^The query string is divided into key/value pairs.
We usually refer to these key/value pairs as "query parameters".
^Key/value pairs are separated by a single "<tt>&amp;</tt>" character.
^The key comes first and is separated from the value by a single
"<tt>=</tt>" character.
^Both key and value may contain <b>%HH</b> escape sequences.</p>

<p>
^The text of query parameters is appended to the filename argument to
the xOpen method of the [VFS].
^Any %HH escape sequences in the query parameters are resolved prior to
being appended ot the xOpen filename.
^A single zero-byte separates the xOpen filename argument from the key of
the first query parameters, each key and value, and each subsequent key
from the prior value.
^The list query parameters parameters appended to the xOpen filename
is terminated by a single zero-length key.
Note that the value of a query parameter can be an empty string.
</p>

<tcl>hd_fragment coreqp {query parameters with special meaning to SQLite}</tcl>
<h2>3.3 Recognized Query Parameters</h2>

<p>
Some query parameters are interpreted by the SQLite core and used to 
modify the characteristics of the new connection.  ^All query parameters
are always passed through into the xOpen method of the [VFS] even if
they are previously read and interpreted by the SQLite core.
</p>

<p>
The following query parameters are recognized by SQLite as of version 3.7.7.
Other query parameters might be added to this set in future releases.
</p>

<dl>
<dt><b>vfs=</b><i>NAME</i></dt>
<dd><p>^This query parameter cases the database connection to be opened
using the [VFS] called <i>NAME</i>.
^The open attempt fails if <i>NAME</i> is not the name of a [VFS] that
is built into SQLite or that has been previously registered using
[sqlite3_vfs_register()].</dd>

<dt><b>mode=ro<br>mode=rw<br>mode=rwc</b></dt>
<dd><p>^These query parameters determine if the new database is opened
read-only, read-write, or read-write and created if it does not exist,
respectively.
</dd>

<dt><b>cache=shared<br>cache=private</b></dt>
<dd><p>^These query parameters determine if the new database is opened
using [shared cache mode] or with a private cache, respectively.
</dd>
</dl>

<h1>4.0 See Also</h1>

<ul>
<li> [URI filenames in sqlite3_open()]
<li> [URI filename examples]
</ul>

  }
  if {![regexp {^https?:} $kw]} {
    regsub -all {[^a-zA-Z0-9_.#/ -]} $kw {} kw
  }
  global hd llink glink backlink
  if {$hd(enable-main)} {
    set fn $hd(fn-main)





    if {[regexp {^https?:} $kw]} {
      puts -nonewline $hd(main) \
        "<a href=\"$kw\">$content</a>"
    } elseif {[regexp {^[Tt]icket #(\d+)$} $kw all tktid]} {
      set url http://www.sqlite.org/cvstrac/tktview?tn=$tktid
      puts -nonewline $hd(main) \
        "<a href=\"$url\">$content</a>"
    } elseif {[info exists llink($fn:$kw)]} {
      puts -nonewline $hd(main) \
        "<a href=\"$hd(rootpath-main)$llink($fn:$kw)\">$content</a>"
    } elseif {[info exists glink($kw)]} {
      puts -nonewline $hd(main) \
        "<a href=\"$hd(rootpath-main)$glink($kw)\">$content</a>"
    } elseif {[regexp {\.gif$} $kw]} {
      puts -nonewline $hd(main) \
        "<img src=\"$hd(rootpath-main)images/$kw\">"
    } else {
      puts stderr "ERROR: unknown hyperlink target: $kw"
      puts -nonewline $hd(main) "<font color=\"red\">$content</font>"
    }
    if {$hd(fragment)!=""} {
      lappend backlink($kw) $fn#$hd(fragment)
    } else {
      lappend backlink($kw) $fn
    }
  }
  if {$hd(enable-aux)} {
    if {[regexp {^https?:} $kw]} {
      puts -nonewline $hd(aux) \
        "<a href=\"$kw\">$content</a>"
    } elseif {[regexp {^[Tt]icket #(\d+)$} $kw all tktid]} {
      set url http://www.sqlite.org/cvstrac/tktview?tn=$tktid
      puts -nonewline $hd(aux) \
        "<a href=\"$url\">$content</a>"
    } elseif {[info exists glink($kw)]} {
      puts -nonewline $hd(aux) \
        "<a href=\"$hd(rootpath-aux)$glink($kw)\">$content</a>"
    } elseif {[regexp {\.gif$} $kw]} {
      puts -nonewline $hd(main) \
        "<img src=\"$hd(rootpath-aux)images/$kw\">"
    } else {
      puts stderr "ERROR: unknown hyperlink target: $kw"
      puts -nonewline $hd(aux) "<font color=\"red\">$content</font>"
    }
    if {$hd(aux-fragment)!=""} {
      lappend backlink($kw) $hd(fn-aux)#$hd(aux-fragment)
    } else {
      lappend backlink($kw) $hd(fn-aux)
    }
  }
}



# Record the fact that all keywords given in the argument list should
# cause a jump to the current location in the current file.

    set lurl $hd(fn-main)
  } else {
    set lurl "#$hd(fragment)"
  }
  set fn $hd(fn-main)
  if {[info exists hd(aux)]} {
    set gurl $hd(fn-aux)
    if {$hd(aux-fragment)!=""} {
      append gurl "#$hd(aux-fragment)"
    }
  } else {
    set gurl {}
    if {$hd(fragment)!=""} {
      set lurl $hd(fn-main)#$hd(fragment)
    }
  }
  foreach a $args {
    if {[regexp {^\*} $a]} {
      set visible 0
      set a [string range $a 1 end]
    } else {
      set visible 1
    }
    regsub -all {[^a-zA-Z0-9_.#/ -]} $a {} kw
    if {[info exists glink($kw)]} {
      if {[info exists hd(aux)] && $glink($kw)==$hd(fn-aux)} {
        db eval {DELETE FROM keyword WHERE kw=$kw}
      } else {
        puts stderr "WARNING: duplicate keyword \"$kw\" - $glink($kw) and $lurl"
      }
    }
    if {$gurl==""} {
      set glink($kw) $lurl
      db eval {INSERT INTO keyword(kw,fragment,indexKw) 
                VALUES($a,$lurl,$visible)}
    } else {
      set glink($kw) $gurl
      set llink($fn:$kw) $lurl
      db eval {INSERT INTO keyword(kw,fragment,indexKw) 
                VALUES($a,$gurl,$visible)}
    }
  }
}

# Start a new fragment in the main file.  Give the new fragment the
# indicated name.  Any keywords defined after this point will refer
# to the fragment, not to the beginning of the file.
#



proc hd_fragment {name args} {
  global hd
  set hd(fragment) $name
  puts $hd(main) "<a name=\"$name\"></a>"
  if {$hd(enable-aux)} {
    puts $hd(aux) "<a name=\"$name\"></a>"
    set hd(aux-fragment) $name
  }
  eval hd_keywords $args
}

# Write raw output to both the main file and the auxiliary.  Only write
# to files that are enabled.
#
proc hd_puts {text} {

proc hd_open_main {filename} {
  global hd DEST
  hd_close_main
  set hd(fn-main) $filename
  set hd(rootpath-main) [hd_rootpath $filename]
  set hd(main) [open $DEST/$filename w]
  set hd(enable-main) 1
  set hd(enable-aux) 0
  set hd(fragment) {}
  global pagelink
  lappend pagelink($filename) $filename
}

# If $filename is a path from $::DEST to a file, return a path
# from the directory containing $filename back to the directory $::DEST.

proc hd_open_aux {filename} {
  global hd DEST
  hd_close_aux
  set hd(fn-aux) $filename
  set hd(rootpath-aux) [hd_rootpath $filename]
  set hd(aux) [open $DEST/$filename w]
  set hd(enable-aux) 1
  set hd(aux-fragment) {}
  global pagelink
  lappend pagelink($filename) $filename
}

# Close the auxiliary output file
#
proc hd_close_aux {} {