sqlite3.h
author Mahlon E. Smith <mahlon@martini.nu>
Mon, 17 Oct 2011 09:12:00 -0700
changeset 11 9aa5114326e8
permissions -rw-r--r--
Carry the amalgamated sqlite3 around with volta, rather than requiring it to be installed on the system -- making volta a zero dependency compile. Add some more Makefile hacks to get things consistently building across OSX, FreeBSD, and Ubuntu. (There may be more later, but I'll deal with those then.)
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
11
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     1
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     2
** 2001 September 15
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     3
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     4
** The author disclaims copyright to this source code.  In place of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     5
** a legal notice, here is a blessing:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     6
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     7
**    May you do good and not evil.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     8
**    May you find forgiveness for yourself and forgive others.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     9
**    May you share freely, never taking more than you give.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    10
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    11
*************************************************************************
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    12
** This header file defines the interface that the SQLite library
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    13
** presents to client programs.  If a C-function, structure, datatype,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    14
** or constant definition does not appear in this file, then it is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    15
** not a published API of SQLite, is subject to change without
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    16
** notice, and should not be referenced by programs that use SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    17
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    18
** Some of the definitions that are in this file are marked as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    19
** "experimental".  Experimental interfaces are normally new
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    20
** features recently added to SQLite.  We do not anticipate changes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    21
** to experimental interfaces but reserve the right to make minor changes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    22
** if experience from use "in the wild" suggest such changes are prudent.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    23
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    24
** The official C-language API documentation for SQLite is derived
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    25
** from comments in this file.  This file is the authoritative source
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    26
** on how SQLite interfaces are suppose to operate.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    27
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    28
** The name of this file under configuration management is "sqlite.h.in".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    29
** The makefile makes some minor changes to this file (such as inserting
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    30
** the version number) and changes its name to "sqlite3.h" as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    31
** part of the build process.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    32
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    33
#ifndef _SQLITE3_H_
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    34
#define _SQLITE3_H_
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    35
#include <stdarg.h>     /* Needed for the definition of va_list */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    36
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    37
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    38
** Make sure we can call this stuff from C++.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    39
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    40
#ifdef __cplusplus
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    41
extern "C" {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    42
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    43
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    44
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    45
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    46
** Add the ability to override 'extern'
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    47
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    48
#ifndef SQLITE_EXTERN
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    49
# define SQLITE_EXTERN extern
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    50
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    51
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    52
#ifndef SQLITE_API
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    53
# define SQLITE_API
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    54
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    55
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    56
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    57
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    58
** These no-op macros are used in front of interfaces to mark those
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    59
** interfaces as either deprecated or experimental.  New applications
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    60
** should not use deprecated interfaces - they are support for backwards
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    61
** compatibility only.  Application writers should be aware that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    62
** experimental interfaces are subject to change in point releases.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    63
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    64
** These macros used to resolve to various kinds of compiler magic that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    65
** would generate warning messages when they were used.  But that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    66
** compiler magic ended up generating such a flurry of bug reports
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    67
** that we have taken it all out and gone back to using simple
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    68
** noop macros.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    69
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    70
#define SQLITE_DEPRECATED
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    71
#define SQLITE_EXPERIMENTAL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    72
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    73
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    74
** Ensure these symbols were not defined by some previous header file.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    75
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    76
#ifdef SQLITE_VERSION
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    77
# undef SQLITE_VERSION
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    78
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    79
#ifdef SQLITE_VERSION_NUMBER
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    80
# undef SQLITE_VERSION_NUMBER
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    81
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    82
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    83
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    84
** CAPI3REF: Compile-Time Library Version Numbers
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    85
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    86
** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    87
** evaluates to a string literal that is the SQLite version in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    88
** format "X.Y.Z" where X is the major version number (always 3 for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    89
** SQLite3) and Y is the minor version number and Z is the release number.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    90
** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    91
** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    92
** numbers used in [SQLITE_VERSION].)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    93
** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    94
** be larger than the release from which it is derived.  Either Y will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    95
** be held constant and Z will be incremented or else Y will be incremented
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    96
** and Z will be reset to zero.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    97
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    98
** Since version 3.6.18, SQLite source code has been stored in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    99
** <a href="http://www.fossil-scm.org/">Fossil configuration management
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   100
** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   101
** a string which identifies a particular check-in of SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   102
** within its configuration management system.  ^The SQLITE_SOURCE_ID
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   103
** string contains the date and time of the check-in (UTC) and an SHA1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   104
** hash of the entire source tree.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   105
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   106
** See also: [sqlite3_libversion()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   107
** [sqlite3_libversion_number()], [sqlite3_sourceid()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   108
** [sqlite_version()] and [sqlite_source_id()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   109
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   110
#define SQLITE_VERSION        "3.7.8"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   111
#define SQLITE_VERSION_NUMBER 3007008
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   112
#define SQLITE_SOURCE_ID      "2011-09-19 14:49:19 3e0da808d2f5b4d12046e05980ca04578f581177"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   113
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   114
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   115
** CAPI3REF: Run-Time Library Version Numbers
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   116
** KEYWORDS: sqlite3_version, sqlite3_sourceid
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   117
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   118
** These interfaces provide the same information as the [SQLITE_VERSION],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   119
** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   120
** but are associated with the library instead of the header file.  ^(Cautious
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   121
** programmers might include assert() statements in their application to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   122
** verify that values returned by these interfaces match the macros in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   123
** the header, and thus insure that the application is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   124
** compiled with matching library and header files.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   125
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   126
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   127
** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   128
** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   129
** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   130
** </pre></blockquote>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   131
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   132
** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   133
** macro.  ^The sqlite3_libversion() function returns a pointer to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   134
** to the sqlite3_version[] string constant.  The sqlite3_libversion()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   135
** function is provided for use in DLLs since DLL users usually do not have
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   136
** direct access to string constants within the DLL.  ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   137
** sqlite3_libversion_number() function returns an integer equal to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   138
** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function returns 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   139
** a pointer to a string constant whose value is the same as the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   140
** [SQLITE_SOURCE_ID] C preprocessor macro.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   141
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   142
** See also: [sqlite_version()] and [sqlite_source_id()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   143
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   144
SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   145
SQLITE_API const char *sqlite3_libversion(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   146
SQLITE_API const char *sqlite3_sourceid(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   147
SQLITE_API int sqlite3_libversion_number(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   148
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   149
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   150
** CAPI3REF: Run-Time Library Compilation Options Diagnostics
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   151
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   152
** ^The sqlite3_compileoption_used() function returns 0 or 1 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   153
** indicating whether the specified option was defined at 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   154
** compile time.  ^The SQLITE_ prefix may be omitted from the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   155
** option name passed to sqlite3_compileoption_used().  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   156
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   157
** ^The sqlite3_compileoption_get() function allows iterating
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   158
** over the list of options that were defined at compile time by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   159
** returning the N-th compile time option string.  ^If N is out of range,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   160
** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_ 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   161
** prefix is omitted from any strings returned by 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   162
** sqlite3_compileoption_get().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   163
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   164
** ^Support for the diagnostic functions sqlite3_compileoption_used()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   165
** and sqlite3_compileoption_get() may be omitted by specifying the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   166
** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   167
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   168
** See also: SQL functions [sqlite_compileoption_used()] and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   169
** [sqlite_compileoption_get()] and the [compile_options pragma].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   170
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   171
#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   172
SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   173
SQLITE_API const char *sqlite3_compileoption_get(int N);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   174
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   175
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   176
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   177
** CAPI3REF: Test To See If The Library Is Threadsafe
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   178
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   179
** ^The sqlite3_threadsafe() function returns zero if and only if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   180
** SQLite was compiled mutexing code omitted due to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   181
** [SQLITE_THREADSAFE] compile-time option being set to 0.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   182
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   183
** SQLite can be compiled with or without mutexes.  When
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   184
** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   185
** are enabled and SQLite is threadsafe.  When the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   186
** [SQLITE_THREADSAFE] macro is 0, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   187
** the mutexes are omitted.  Without the mutexes, it is not safe
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   188
** to use SQLite concurrently from more than one thread.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   189
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   190
** Enabling mutexes incurs a measurable performance penalty.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   191
** So if speed is of utmost importance, it makes sense to disable
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   192
** the mutexes.  But for maximum safety, mutexes should be enabled.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   193
** ^The default behavior is for mutexes to be enabled.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   194
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   195
** This interface can be used by an application to make sure that the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   196
** version of SQLite that it is linking against was compiled with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   197
** the desired setting of the [SQLITE_THREADSAFE] macro.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   198
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   199
** This interface only reports on the compile-time mutex setting
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   200
** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   201
** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   202
** can be fully or partially disabled using a call to [sqlite3_config()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   203
** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   204
** or [SQLITE_CONFIG_MUTEX].  ^(The return value of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   205
** sqlite3_threadsafe() function shows only the compile-time setting of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   206
** thread safety, not any run-time changes to that setting made by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   207
** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   208
** is unchanged by calls to sqlite3_config().)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   209
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   210
** See the [threading mode] documentation for additional information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   211
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   212
SQLITE_API int sqlite3_threadsafe(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   213
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   214
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   215
** CAPI3REF: Database Connection Handle
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   216
** KEYWORDS: {database connection} {database connections}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   217
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   218
** Each open SQLite database is represented by a pointer to an instance of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   219
** the opaque structure named "sqlite3".  It is useful to think of an sqlite3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   220
** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   221
** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   222
** is its destructor.  There are many other interfaces (such as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   223
** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   224
** [sqlite3_busy_timeout()] to name but three) that are methods on an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   225
** sqlite3 object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   226
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   227
typedef struct sqlite3 sqlite3;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   228
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   229
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   230
** CAPI3REF: 64-Bit Integer Types
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   231
** KEYWORDS: sqlite_int64 sqlite_uint64
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   232
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   233
** Because there is no cross-platform way to specify 64-bit integer types
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   234
** SQLite includes typedefs for 64-bit signed and unsigned integers.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   235
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   236
** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   237
** The sqlite_int64 and sqlite_uint64 types are supported for backwards
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   238
** compatibility only.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   239
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   240
** ^The sqlite3_int64 and sqlite_int64 types can store integer values
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   241
** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   242
** sqlite3_uint64 and sqlite_uint64 types can store integer values 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   243
** between 0 and +18446744073709551615 inclusive.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   244
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   245
#ifdef SQLITE_INT64_TYPE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   246
  typedef SQLITE_INT64_TYPE sqlite_int64;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   247
  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   248
#elif defined(_MSC_VER) || defined(__BORLANDC__)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   249
  typedef __int64 sqlite_int64;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   250
  typedef unsigned __int64 sqlite_uint64;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   251
#else
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   252
  typedef long long int sqlite_int64;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   253
  typedef unsigned long long int sqlite_uint64;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   254
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   255
typedef sqlite_int64 sqlite3_int64;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   256
typedef sqlite_uint64 sqlite3_uint64;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   257
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   258
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   259
** If compiling for a processor that lacks floating point support,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   260
** substitute integer for floating-point.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   261
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   262
#ifdef SQLITE_OMIT_FLOATING_POINT
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   263
# define double sqlite3_int64
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   264
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   265
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   266
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   267
** CAPI3REF: Closing A Database Connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   268
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   269
** ^The sqlite3_close() routine is the destructor for the [sqlite3] object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   270
** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   271
** successfully destroyed and all associated resources are deallocated.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   272
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   273
** Applications must [sqlite3_finalize | finalize] all [prepared statements]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   274
** and [sqlite3_blob_close | close] all [BLOB handles] associated with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   275
** the [sqlite3] object prior to attempting to close the object.  ^If
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   276
** sqlite3_close() is called on a [database connection] that still has
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   277
** outstanding [prepared statements] or [BLOB handles], then it returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   278
** SQLITE_BUSY.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   279
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   280
** ^If [sqlite3_close()] is invoked while a transaction is open,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   281
** the transaction is automatically rolled back.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   282
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   283
** The C parameter to [sqlite3_close(C)] must be either a NULL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   284
** pointer or an [sqlite3] object pointer obtained
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   285
** from [sqlite3_open()], [sqlite3_open16()], or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   286
** [sqlite3_open_v2()], and not previously closed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   287
** ^Calling sqlite3_close() with a NULL pointer argument is a 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   288
** harmless no-op.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   289
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   290
SQLITE_API int sqlite3_close(sqlite3 *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   291
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   292
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   293
** The type for a callback function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   294
** This is legacy and deprecated.  It is included for historical
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   295
** compatibility and is not documented.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   296
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   297
typedef int (*sqlite3_callback)(void*,int,char**, char**);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   298
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   299
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   300
** CAPI3REF: One-Step Query Execution Interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   301
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   302
** The sqlite3_exec() interface is a convenience wrapper around
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   303
** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   304
** that allows an application to run multiple statements of SQL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   305
** without having to use a lot of C code. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   306
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   307
** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   308
** semicolon-separate SQL statements passed into its 2nd argument,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   309
** in the context of the [database connection] passed in as its 1st
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   310
** argument.  ^If the callback function of the 3rd argument to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   311
** sqlite3_exec() is not NULL, then it is invoked for each result row
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   312
** coming out of the evaluated SQL statements.  ^The 4th argument to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   313
** sqlite3_exec() is relayed through to the 1st argument of each
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   314
** callback invocation.  ^If the callback pointer to sqlite3_exec()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   315
** is NULL, then no callback is ever invoked and result rows are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   316
** ignored.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   317
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   318
** ^If an error occurs while evaluating the SQL statements passed into
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   319
** sqlite3_exec(), then execution of the current statement stops and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   320
** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   321
** is not NULL then any error message is written into memory obtained
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   322
** from [sqlite3_malloc()] and passed back through the 5th parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   323
** To avoid memory leaks, the application should invoke [sqlite3_free()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   324
** on error message strings returned through the 5th parameter of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   325
** of sqlite3_exec() after the error message string is no longer needed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   326
** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   327
** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   328
** NULL before returning.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   329
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   330
** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   331
** routine returns SQLITE_ABORT without invoking the callback again and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   332
** without running any subsequent SQL statements.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   333
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   334
** ^The 2nd argument to the sqlite3_exec() callback function is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   335
** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   336
** callback is an array of pointers to strings obtained as if from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   337
** [sqlite3_column_text()], one for each column.  ^If an element of a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   338
** result row is NULL then the corresponding string pointer for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   339
** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   340
** sqlite3_exec() callback is an array of pointers to strings where each
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   341
** entry represents the name of corresponding result column as obtained
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   342
** from [sqlite3_column_name()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   343
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   344
** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   345
** to an empty string, or a pointer that contains only whitespace and/or 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   346
** SQL comments, then no SQL statements are evaluated and the database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   347
** is not changed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   348
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   349
** Restrictions:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   350
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   351
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   352
** <li> The application must insure that the 1st parameter to sqlite3_exec()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   353
**      is a valid and open [database connection].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   354
** <li> The application must not close [database connection] specified by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   355
**      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   356
** <li> The application must not modify the SQL statement text passed into
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   357
**      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   358
** </ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   359
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   360
SQLITE_API int sqlite3_exec(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   361
  sqlite3*,                                  /* An open database */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   362
  const char *sql,                           /* SQL to be evaluated */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   363
  int (*callback)(void*,int,char**,char**),  /* Callback function */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   364
  void *,                                    /* 1st argument to callback */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   365
  char **errmsg                              /* Error msg written here */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   366
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   367
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   368
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   369
** CAPI3REF: Result Codes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   370
** KEYWORDS: SQLITE_OK {error code} {error codes}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   371
** KEYWORDS: {result code} {result codes}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   372
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   373
** Many SQLite functions return an integer result code from the set shown
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   374
** here in order to indicates success or failure.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   375
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   376
** New error codes may be added in future versions of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   377
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   378
** See also: [SQLITE_IOERR_READ | extended result codes],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   379
** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   380
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   381
#define SQLITE_OK           0   /* Successful result */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   382
/* beginning-of-error-codes */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   383
#define SQLITE_ERROR        1   /* SQL error or missing database */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   384
#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   385
#define SQLITE_PERM         3   /* Access permission denied */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   386
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   387
#define SQLITE_BUSY         5   /* The database file is locked */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   388
#define SQLITE_LOCKED       6   /* A table in the database is locked */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   389
#define SQLITE_NOMEM        7   /* A malloc() failed */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   390
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   391
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   392
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   393
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   394
#define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   395
#define SQLITE_FULL        13   /* Insertion failed because database is full */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   396
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   397
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   398
#define SQLITE_EMPTY       16   /* Database is empty */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   399
#define SQLITE_SCHEMA      17   /* The database schema changed */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   400
#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   401
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   402
#define SQLITE_MISMATCH    20   /* Data type mismatch */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   403
#define SQLITE_MISUSE      21   /* Library used incorrectly */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   404
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   405
#define SQLITE_AUTH        23   /* Authorization denied */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   406
#define SQLITE_FORMAT      24   /* Auxiliary database format error */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   407
#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   408
#define SQLITE_NOTADB      26   /* File opened that is not a database file */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   409
#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   410
#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   411
/* end-of-error-codes */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   412
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   413
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   414
** CAPI3REF: Extended Result Codes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   415
** KEYWORDS: {extended error code} {extended error codes}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   416
** KEYWORDS: {extended result code} {extended result codes}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   417
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   418
** In its default configuration, SQLite API routines return one of 26 integer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   419
** [SQLITE_OK | result codes].  However, experience has shown that many of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   420
** these result codes are too coarse-grained.  They do not provide as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   421
** much information about problems as programmers might like.  In an effort to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   422
** address this, newer versions of SQLite (version 3.3.8 and later) include
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   423
** support for additional result codes that provide more detailed information
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   424
** about errors. The extended result codes are enabled or disabled
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   425
** on a per database connection basis using the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   426
** [sqlite3_extended_result_codes()] API.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   427
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   428
** Some of the available extended result codes are listed here.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   429
** One may expect the number of extended result codes will be expand
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   430
** over time.  Software that uses extended result codes should expect
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   431
** to see new result codes in future releases of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   432
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   433
** The SQLITE_OK result code will never be extended.  It will always
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   434
** be exactly zero.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   435
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   436
#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   437
#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   438
#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   439
#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   440
#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   441
#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   442
#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   443
#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   444
#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   445
#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   446
#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   447
#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   448
#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   449
#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   450
#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   451
#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   452
#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   453
#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   454
#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   455
#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   456
#define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   457
#define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   458
#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   459
#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   460
#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   461
#define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   462
#define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   463
#define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   464
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   465
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   466
** CAPI3REF: Flags For File Open Operations
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   467
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   468
** These bit values are intended for use in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   469
** 3rd parameter to the [sqlite3_open_v2()] interface and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   470
** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   471
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   472
#define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   473
#define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   474
#define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   475
#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   476
#define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   477
#define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   478
#define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   479
#define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   480
#define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   481
#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   482
#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   483
#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   484
#define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   485
#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   486
#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   487
#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   488
#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   489
#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   490
#define SQLITE_OPEN_WAL              0x00080000  /* VFS only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   491
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   492
/* Reserved:                         0x00F00000 */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   493
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   494
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   495
** CAPI3REF: Device Characteristics
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   496
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   497
** The xDeviceCharacteristics method of the [sqlite3_io_methods]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   498
** object returns an integer which is a vector of the these
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   499
** bit values expressing I/O characteristics of the mass storage
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   500
** device that holds the file that the [sqlite3_io_methods]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   501
** refers to.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   502
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   503
** The SQLITE_IOCAP_ATOMIC property means that all writes of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   504
** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   505
** mean that writes of blocks that are nnn bytes in size and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   506
** are aligned to an address which is an integer multiple of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   507
** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   508
** that when data is appended to a file, the data is appended
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   509
** first then the size of the file is extended, never the other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   510
** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   511
** information is written to disk in the same order as calls
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   512
** to xWrite().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   513
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   514
#define SQLITE_IOCAP_ATOMIC                 0x00000001
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   515
#define SQLITE_IOCAP_ATOMIC512              0x00000002
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   516
#define SQLITE_IOCAP_ATOMIC1K               0x00000004
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   517
#define SQLITE_IOCAP_ATOMIC2K               0x00000008
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   518
#define SQLITE_IOCAP_ATOMIC4K               0x00000010
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   519
#define SQLITE_IOCAP_ATOMIC8K               0x00000020
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   520
#define SQLITE_IOCAP_ATOMIC16K              0x00000040
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   521
#define SQLITE_IOCAP_ATOMIC32K              0x00000080
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   522
#define SQLITE_IOCAP_ATOMIC64K              0x00000100
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   523
#define SQLITE_IOCAP_SAFE_APPEND            0x00000200
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   524
#define SQLITE_IOCAP_SEQUENTIAL             0x00000400
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   525
#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   526
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   527
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   528
** CAPI3REF: File Locking Levels
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   529
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   530
** SQLite uses one of these integer values as the second
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   531
** argument to calls it makes to the xLock() and xUnlock() methods
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   532
** of an [sqlite3_io_methods] object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   533
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   534
#define SQLITE_LOCK_NONE          0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   535
#define SQLITE_LOCK_SHARED        1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   536
#define SQLITE_LOCK_RESERVED      2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   537
#define SQLITE_LOCK_PENDING       3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   538
#define SQLITE_LOCK_EXCLUSIVE     4
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   539
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   540
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   541
** CAPI3REF: Synchronization Type Flags
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   542
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   543
** When SQLite invokes the xSync() method of an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   544
** [sqlite3_io_methods] object it uses a combination of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   545
** these integer values as the second argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   546
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   547
** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   548
** sync operation only needs to flush data to mass storage.  Inode
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   549
** information need not be flushed. If the lower four bits of the flag
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   550
** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   551
** If the lower four bits equal SQLITE_SYNC_FULL, that means
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   552
** to use Mac OS X style fullsync instead of fsync().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   553
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   554
** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   555
** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   556
** settings.  The [synchronous pragma] determines when calls to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   557
** xSync VFS method occur and applies uniformly across all platforms.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   558
** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   559
** energetic or rigorous or forceful the sync operations are and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   560
** only make a difference on Mac OSX for the default SQLite code.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   561
** (Third-party VFS implementations might also make the distinction
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   562
** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   563
** operating systems natively supported by SQLite, only Mac OSX
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   564
** cares about the difference.)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   565
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   566
#define SQLITE_SYNC_NORMAL        0x00002
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   567
#define SQLITE_SYNC_FULL          0x00003
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   568
#define SQLITE_SYNC_DATAONLY      0x00010
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   569
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   570
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   571
** CAPI3REF: OS Interface Open File Handle
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   572
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   573
** An [sqlite3_file] object represents an open file in the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   574
** [sqlite3_vfs | OS interface layer].  Individual OS interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   575
** implementations will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   576
** want to subclass this object by appending additional fields
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   577
** for their own use.  The pMethods entry is a pointer to an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   578
** [sqlite3_io_methods] object that defines methods for performing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   579
** I/O operations on the open file.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   580
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   581
typedef struct sqlite3_file sqlite3_file;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   582
struct sqlite3_file {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   583
  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   584
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   585
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   586
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   587
** CAPI3REF: OS Interface File Virtual Methods Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   588
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   589
** Every file opened by the [sqlite3_vfs.xOpen] method populates an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   590
** [sqlite3_file] object (or, more commonly, a subclass of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   591
** [sqlite3_file] object) with a pointer to an instance of this object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   592
** This object defines the methods used to perform various operations
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   593
** against the open file represented by the [sqlite3_file] object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   594
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   595
** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   596
** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   597
** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   598
** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   599
** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   600
** to NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   601
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   602
** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   603
** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   604
** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   605
** flag may be ORed in to indicate that only the data of the file
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   606
** and not its inode needs to be synced.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   607
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   608
** The integer values to xLock() and xUnlock() are one of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   609
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   610
** <li> [SQLITE_LOCK_NONE],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   611
** <li> [SQLITE_LOCK_SHARED],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   612
** <li> [SQLITE_LOCK_RESERVED],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   613
** <li> [SQLITE_LOCK_PENDING], or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   614
** <li> [SQLITE_LOCK_EXCLUSIVE].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   615
** </ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   616
** xLock() increases the lock. xUnlock() decreases the lock.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   617
** The xCheckReservedLock() method checks whether any database connection,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   618
** either in this process or in some other process, is holding a RESERVED,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   619
** PENDING, or EXCLUSIVE lock on the file.  It returns true
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   620
** if such a lock exists and false otherwise.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   621
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   622
** The xFileControl() method is a generic interface that allows custom
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   623
** VFS implementations to directly control an open file using the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   624
** [sqlite3_file_control()] interface.  The second "op" argument is an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   625
** integer opcode.  The third argument is a generic pointer intended to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   626
** point to a structure that may contain arguments or space in which to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   627
** write return values.  Potential uses for xFileControl() might be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   628
** functions to enable blocking locks with timeouts, to change the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   629
** locking strategy (for example to use dot-file locks), to inquire
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   630
** about the status of a lock, or to break stale locks.  The SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   631
** core reserves all opcodes less than 100 for its own use.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   632
** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   633
** Applications that define a custom xFileControl method should use opcodes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   634
** greater than 100 to avoid conflicts.  VFS implementations should
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   635
** return [SQLITE_NOTFOUND] for file control opcodes that they do not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   636
** recognize.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   637
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   638
** The xSectorSize() method returns the sector size of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   639
** device that underlies the file.  The sector size is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   640
** minimum write that can be performed without disturbing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   641
** other bytes in the file.  The xDeviceCharacteristics()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   642
** method returns a bit vector describing behaviors of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   643
** underlying device:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   644
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   645
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   646
** <li> [SQLITE_IOCAP_ATOMIC]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   647
** <li> [SQLITE_IOCAP_ATOMIC512]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   648
** <li> [SQLITE_IOCAP_ATOMIC1K]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   649
** <li> [SQLITE_IOCAP_ATOMIC2K]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   650
** <li> [SQLITE_IOCAP_ATOMIC4K]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   651
** <li> [SQLITE_IOCAP_ATOMIC8K]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   652
** <li> [SQLITE_IOCAP_ATOMIC16K]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   653
** <li> [SQLITE_IOCAP_ATOMIC32K]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   654
** <li> [SQLITE_IOCAP_ATOMIC64K]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   655
** <li> [SQLITE_IOCAP_SAFE_APPEND]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   656
** <li> [SQLITE_IOCAP_SEQUENTIAL]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   657
** </ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   658
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   659
** The SQLITE_IOCAP_ATOMIC property means that all writes of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   660
** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   661
** mean that writes of blocks that are nnn bytes in size and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   662
** are aligned to an address which is an integer multiple of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   663
** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   664
** that when data is appended to a file, the data is appended
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   665
** first then the size of the file is extended, never the other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   666
** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   667
** information is written to disk in the same order as calls
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   668
** to xWrite().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   669
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   670
** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   671
** in the unread portions of the buffer with zeros.  A VFS that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   672
** fails to zero-fill short reads might seem to work.  However,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   673
** failure to zero-fill short reads will eventually lead to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   674
** database corruption.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   675
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   676
typedef struct sqlite3_io_methods sqlite3_io_methods;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   677
struct sqlite3_io_methods {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   678
  int iVersion;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   679
  int (*xClose)(sqlite3_file*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   680
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   681
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   682
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   683
  int (*xSync)(sqlite3_file*, int flags);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   684
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   685
  int (*xLock)(sqlite3_file*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   686
  int (*xUnlock)(sqlite3_file*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   687
  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   688
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   689
  int (*xSectorSize)(sqlite3_file*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   690
  int (*xDeviceCharacteristics)(sqlite3_file*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   691
  /* Methods above are valid for version 1 */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   692
  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   693
  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   694
  void (*xShmBarrier)(sqlite3_file*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   695
  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   696
  /* Methods above are valid for version 2 */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   697
  /* Additional methods may be added in future releases */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   698
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   699
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   700
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   701
** CAPI3REF: Standard File Control Opcodes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   702
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   703
** These integer constants are opcodes for the xFileControl method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   704
** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   705
** interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   706
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   707
** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   708
** opcode causes the xFileControl method to write the current state of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   709
** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   710
** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   711
** into an integer that the pArg argument points to. This capability
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   712
** is used during testing and only needs to be supported when SQLITE_TEST
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   713
** is defined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   714
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   715
** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   716
** layer a hint of how large the database file will grow to be during the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   717
** current transaction.  This hint is not guaranteed to be accurate but it
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   718
** is often close.  The underlying VFS might choose to preallocate database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   719
** file space based on this hint in order to help writes to the database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   720
** file run faster.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   721
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   722
** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   723
** extends and truncates the database file in chunks of a size specified
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   724
** by the user. The fourth argument to [sqlite3_file_control()] should 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   725
** point to an integer (type int) containing the new chunk-size to use
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   726
** for the nominated database. Allocating database file space in large
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   727
** chunks (say 1MB at a time), may reduce file-system fragmentation and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   728
** improve performance on some systems.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   729
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   730
** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   731
** to the [sqlite3_file] object associated with a particular database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   732
** connection.  See the [sqlite3_file_control()] documentation for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   733
** additional information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   734
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   735
** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   736
** SQLite and sent to all VFSes in place of a call to the xSync method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   737
** when the database connection has [PRAGMA synchronous] set to OFF.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   738
** Some specialized VFSes need this signal in order to operate correctly
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   739
** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   740
** VFSes do not need this signal and should silently ignore this opcode.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   741
** Applications should not call [sqlite3_file_control()] with this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   742
** opcode as doing so may disrupt the operation of the specialized VFSes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   743
** that do require it.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   744
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   745
** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   746
** retry counts and intervals for certain disk I/O operations for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   747
** windows [VFS] in order to work to provide robustness against
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   748
** anti-virus programs.  By default, the windows VFS will retry file read,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   749
** file write, and file delete opertions up to 10 times, with a delay
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   750
** of 25 milliseconds before the first retry and with the delay increasing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   751
** by an additional 25 milliseconds with each subsequent retry.  This
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   752
** opcode allows those to values (10 retries and 25 milliseconds of delay)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   753
** to be adjusted.  The values are changed for all database connections
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   754
** within the same process.  The argument is a pointer to an array of two
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   755
** integers where the first integer i the new retry count and the second
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   756
** integer is the delay.  If either integer is negative, then the setting
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   757
** is not changed but instead the prior value of that setting is written
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   758
** into the array entry, allowing the current retry settings to be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   759
** interrogated.  The zDbName parameter is ignored.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   760
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   761
** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   762
** persistent [WAL | Write AHead Log] setting.  By default, the auxiliary
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   763
** write ahead log and shared memory files used for transaction control
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   764
** are automatically deleted when the latest connection to the database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   765
** closes.  Setting persistent WAL mode causes those files to persist after
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   766
** close.  Persisting the files is useful when other processes that do not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   767
** have write permission on the directory containing the database file want
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   768
** to read the database file, as the WAL and shared memory files must exist
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   769
** in order for the database to be readable.  The fourth parameter to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   770
** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   771
** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   772
** WAL mode.  If the integer is -1, then it is overwritten with the current
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   773
** WAL persistence setting.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   774
** 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   775
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   776
#define SQLITE_FCNTL_LOCKSTATE        1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   777
#define SQLITE_GET_LOCKPROXYFILE      2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   778
#define SQLITE_SET_LOCKPROXYFILE      3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   779
#define SQLITE_LAST_ERRNO             4
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   780
#define SQLITE_FCNTL_SIZE_HINT        5
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   781
#define SQLITE_FCNTL_CHUNK_SIZE       6
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   782
#define SQLITE_FCNTL_FILE_POINTER     7
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   783
#define SQLITE_FCNTL_SYNC_OMITTED     8
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   784
#define SQLITE_FCNTL_WIN32_AV_RETRY   9
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   785
#define SQLITE_FCNTL_PERSIST_WAL     10
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   786
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   787
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   788
** CAPI3REF: Mutex Handle
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   789
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   790
** The mutex module within SQLite defines [sqlite3_mutex] to be an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   791
** abstract type for a mutex object.  The SQLite core never looks
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   792
** at the internal representation of an [sqlite3_mutex].  It only
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   793
** deals with pointers to the [sqlite3_mutex] object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   794
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   795
** Mutexes are created using [sqlite3_mutex_alloc()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   796
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   797
typedef struct sqlite3_mutex sqlite3_mutex;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   798
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   799
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   800
** CAPI3REF: OS Interface Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   801
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   802
** An instance of the sqlite3_vfs object defines the interface between
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   803
** the SQLite core and the underlying operating system.  The "vfs"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   804
** in the name of the object stands for "virtual file system".  See
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   805
** the [VFS | VFS documentation] for further information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   806
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   807
** The value of the iVersion field is initially 1 but may be larger in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   808
** future versions of SQLite.  Additional fields may be appended to this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   809
** object when the iVersion value is increased.  Note that the structure
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   810
** of the sqlite3_vfs object changes in the transaction between
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   811
** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   812
** modified.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   813
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   814
** The szOsFile field is the size of the subclassed [sqlite3_file]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   815
** structure used by this VFS.  mxPathname is the maximum length of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   816
** a pathname in this VFS.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   817
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   818
** Registered sqlite3_vfs objects are kept on a linked list formed by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   819
** the pNext pointer.  The [sqlite3_vfs_register()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   820
** and [sqlite3_vfs_unregister()] interfaces manage this list
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   821
** in a thread-safe way.  The [sqlite3_vfs_find()] interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   822
** searches the list.  Neither the application code nor the VFS
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   823
** implementation should use the pNext pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   824
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   825
** The pNext field is the only field in the sqlite3_vfs
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   826
** structure that SQLite will ever modify.  SQLite will only access
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   827
** or modify this field while holding a particular static mutex.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   828
** The application should never modify anything within the sqlite3_vfs
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   829
** object once the object has been registered.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   830
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   831
** The zName field holds the name of the VFS module.  The name must
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   832
** be unique across all VFS modules.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   833
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   834
** [[sqlite3_vfs.xOpen]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   835
** ^SQLite guarantees that the zFilename parameter to xOpen
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   836
** is either a NULL pointer or string obtained
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   837
** from xFullPathname() with an optional suffix added.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   838
** ^If a suffix is added to the zFilename parameter, it will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   839
** consist of a single "-" character followed by no more than
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   840
** 10 alphanumeric and/or "-" characters.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   841
** ^SQLite further guarantees that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   842
** the string will be valid and unchanged until xClose() is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   843
** called. Because of the previous sentence,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   844
** the [sqlite3_file] can safely store a pointer to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   845
** filename if it needs to remember the filename for some reason.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   846
** If the zFilename parameter to xOpen is a NULL pointer then xOpen
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   847
** must invent its own temporary name for the file.  ^Whenever the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   848
** xFilename parameter is NULL it will also be the case that the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   849
** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   850
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   851
** The flags argument to xOpen() includes all bits set in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   852
** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   853
** or [sqlite3_open16()] is used, then flags includes at least
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   854
** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   855
** If xOpen() opens a file read-only then it sets *pOutFlags to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   856
** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   857
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   858
** ^(SQLite will also add one of the following flags to the xOpen()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   859
** call, depending on the object being opened:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   860
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   861
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   862
** <li>  [SQLITE_OPEN_MAIN_DB]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   863
** <li>  [SQLITE_OPEN_MAIN_JOURNAL]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   864
** <li>  [SQLITE_OPEN_TEMP_DB]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   865
** <li>  [SQLITE_OPEN_TEMP_JOURNAL]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   866
** <li>  [SQLITE_OPEN_TRANSIENT_DB]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   867
** <li>  [SQLITE_OPEN_SUBJOURNAL]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   868
** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   869
** <li>  [SQLITE_OPEN_WAL]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   870
** </ul>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   871
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   872
** The file I/O implementation can use the object type flags to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   873
** change the way it deals with files.  For example, an application
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   874
** that does not care about crash recovery or rollback might make
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   875
** the open of a journal file a no-op.  Writes to this journal would
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   876
** also be no-ops, and any attempt to read the journal would return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   877
** SQLITE_IOERR.  Or the implementation might recognize that a database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   878
** file will be doing page-aligned sector reads and writes in a random
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   879
** order and set up its I/O subsystem accordingly.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   880
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   881
** SQLite might also add one of the following flags to the xOpen method:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   882
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   883
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   884
** <li> [SQLITE_OPEN_DELETEONCLOSE]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   885
** <li> [SQLITE_OPEN_EXCLUSIVE]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   886
** </ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   887
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   888
** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   889
** deleted when it is closed.  ^The [SQLITE_OPEN_DELETEONCLOSE]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   890
** will be set for TEMP databases and their journals, transient
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   891
** databases, and subjournals.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   892
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   893
** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   894
** with the [SQLITE_OPEN_CREATE] flag, which are both directly
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   895
** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   896
** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   897
** SQLITE_OPEN_CREATE, is used to indicate that file should always
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   898
** be created, and that it is an error if it already exists.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   899
** It is <i>not</i> used to indicate the file should be opened 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   900
** for exclusive access.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   901
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   902
** ^At least szOsFile bytes of memory are allocated by SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   903
** to hold the  [sqlite3_file] structure passed as the third
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   904
** argument to xOpen.  The xOpen method does not have to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   905
** allocate the structure; it should just fill it in.  Note that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   906
** the xOpen method must set the sqlite3_file.pMethods to either
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   907
** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   908
** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   909
** element will be valid after xOpen returns regardless of the success
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   910
** or failure of the xOpen call.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   911
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   912
** [[sqlite3_vfs.xAccess]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   913
** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   914
** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   915
** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   916
** to test whether a file is at least readable.   The file can be a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   917
** directory.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   918
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   919
** ^SQLite will always allocate at least mxPathname+1 bytes for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   920
** output buffer xFullPathname.  The exact size of the output buffer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   921
** is also passed as a parameter to both  methods. If the output buffer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   922
** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   923
** handled as a fatal error by SQLite, vfs implementations should endeavor
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   924
** to prevent this by setting mxPathname to a sufficiently large value.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   925
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   926
** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   927
** interfaces are not strictly a part of the filesystem, but they are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   928
** included in the VFS structure for completeness.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   929
** The xRandomness() function attempts to return nBytes bytes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   930
** of good-quality randomness into zOut.  The return value is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   931
** the actual number of bytes of randomness obtained.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   932
** The xSleep() method causes the calling thread to sleep for at
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   933
** least the number of microseconds given.  ^The xCurrentTime()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   934
** method returns a Julian Day Number for the current date and time as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   935
** a floating point value.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   936
** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   937
** Day Number multiplied by 86400000 (the number of milliseconds in 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   938
** a 24-hour day).  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   939
** ^SQLite will use the xCurrentTimeInt64() method to get the current
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   940
** date and time if that method is available (if iVersion is 2 or 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   941
** greater and the function pointer is not NULL) and will fall back
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   942
** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   943
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   944
** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   945
** are not used by the SQLite core.  These optional interfaces are provided
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   946
** by some VFSes to facilitate testing of the VFS code. By overriding 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   947
** system calls with functions under its control, a test program can
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   948
** simulate faults and error conditions that would otherwise be difficult
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   949
** or impossible to induce.  The set of system calls that can be overridden
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   950
** varies from one VFS to another, and from one version of the same VFS to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   951
** next.  Applications that use these interfaces must be prepared for any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   952
** or all of these interfaces to be NULL or for their behavior to change
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   953
** from one release to the next.  Applications must not attempt to access
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   954
** any of these methods if the iVersion of the VFS is less than 3.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   955
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   956
typedef struct sqlite3_vfs sqlite3_vfs;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   957
typedef void (*sqlite3_syscall_ptr)(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   958
struct sqlite3_vfs {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   959
  int iVersion;            /* Structure version number (currently 3) */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   960
  int szOsFile;            /* Size of subclassed sqlite3_file */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   961
  int mxPathname;          /* Maximum file pathname length */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   962
  sqlite3_vfs *pNext;      /* Next registered VFS */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   963
  const char *zName;       /* Name of this virtual file system */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   964
  void *pAppData;          /* Pointer to application-specific data */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   965
  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   966
               int flags, int *pOutFlags);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   967
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   968
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   969
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   970
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   971
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   972
  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   973
  void (*xDlClose)(sqlite3_vfs*, void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   974
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   975
  int (*xSleep)(sqlite3_vfs*, int microseconds);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   976
  int (*xCurrentTime)(sqlite3_vfs*, double*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   977
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   978
  /*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   979
  ** The methods above are in version 1 of the sqlite_vfs object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   980
  ** definition.  Those that follow are added in version 2 or later
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   981
  */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   982
  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   983
  /*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   984
  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   985
  ** Those below are for version 3 and greater.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   986
  */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   987
  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   988
  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   989
  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   990
  /*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   991
  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   992
  ** New fields may be appended in figure versions.  The iVersion
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   993
  ** value will increment whenever this happens. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   994
  */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   995
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   996
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   997
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   998
** CAPI3REF: Flags for the xAccess VFS method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   999
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1000
** These integer constants can be used as the third parameter to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1001
** the xAccess method of an [sqlite3_vfs] object.  They determine
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1002
** what kind of permissions the xAccess method is looking for.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1003
** With SQLITE_ACCESS_EXISTS, the xAccess method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1004
** simply checks whether the file exists.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1005
** With SQLITE_ACCESS_READWRITE, the xAccess method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1006
** checks whether the named directory is both readable and writable
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1007
** (in other words, if files can be added, removed, and renamed within
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1008
** the directory).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1009
** The SQLITE_ACCESS_READWRITE constant is currently used only by the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1010
** [temp_store_directory pragma], though this could change in a future
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1011
** release of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1012
** With SQLITE_ACCESS_READ, the xAccess method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1013
** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1014
** currently unused, though it might be used in a future release of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1015
** SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1016
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1017
#define SQLITE_ACCESS_EXISTS    0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1018
#define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1019
#define SQLITE_ACCESS_READ      2   /* Unused */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1020
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1021
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1022
** CAPI3REF: Flags for the xShmLock VFS method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1023
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1024
** These integer constants define the various locking operations
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1025
** allowed by the xShmLock method of [sqlite3_io_methods].  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1026
** following are the only legal combinations of flags to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1027
** xShmLock method:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1028
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1029
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1030
** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1031
** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1032
** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1033
** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1034
** </ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1035
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1036
** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1037
** was given no the corresponding lock.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1038
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1039
** The xShmLock method can transition between unlocked and SHARED or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1040
** between unlocked and EXCLUSIVE.  It cannot transition between SHARED
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1041
** and EXCLUSIVE.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1042
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1043
#define SQLITE_SHM_UNLOCK       1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1044
#define SQLITE_SHM_LOCK         2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1045
#define SQLITE_SHM_SHARED       4
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1046
#define SQLITE_SHM_EXCLUSIVE    8
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1047
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1048
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1049
** CAPI3REF: Maximum xShmLock index
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1050
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1051
** The xShmLock method on [sqlite3_io_methods] may use values
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1052
** between 0 and this upper bound as its "offset" argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1053
** The SQLite core will never attempt to acquire or release a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1054
** lock outside of this range
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1055
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1056
#define SQLITE_SHM_NLOCK        8
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1057
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1058
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1059
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1060
** CAPI3REF: Initialize The SQLite Library
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1061
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1062
** ^The sqlite3_initialize() routine initializes the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1063
** SQLite library.  ^The sqlite3_shutdown() routine
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1064
** deallocates any resources that were allocated by sqlite3_initialize().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1065
** These routines are designed to aid in process initialization and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1066
** shutdown on embedded systems.  Workstation applications using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1067
** SQLite normally do not need to invoke either of these routines.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1068
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1069
** A call to sqlite3_initialize() is an "effective" call if it is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1070
** the first time sqlite3_initialize() is invoked during the lifetime of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1071
** the process, or if it is the first time sqlite3_initialize() is invoked
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1072
** following a call to sqlite3_shutdown().  ^(Only an effective call
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1073
** of sqlite3_initialize() does any initialization.  All other calls
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1074
** are harmless no-ops.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1075
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1076
** A call to sqlite3_shutdown() is an "effective" call if it is the first
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1077
** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1078
** an effective call to sqlite3_shutdown() does any deinitialization.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1079
** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1080
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1081
** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1082
** is not.  The sqlite3_shutdown() interface must only be called from a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1083
** single thread.  All open [database connections] must be closed and all
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1084
** other SQLite resources must be deallocated prior to invoking
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1085
** sqlite3_shutdown().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1086
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1087
** Among other things, ^sqlite3_initialize() will invoke
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1088
** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1089
** will invoke sqlite3_os_end().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1090
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1091
** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1092
** ^If for some reason, sqlite3_initialize() is unable to initialize
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1093
** the library (perhaps it is unable to allocate a needed resource such
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1094
** as a mutex) it returns an [error code] other than [SQLITE_OK].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1095
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1096
** ^The sqlite3_initialize() routine is called internally by many other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1097
** SQLite interfaces so that an application usually does not need to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1098
** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1099
** calls sqlite3_initialize() so the SQLite library will be automatically
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1100
** initialized when [sqlite3_open()] is called if it has not be initialized
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1101
** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1102
** compile-time option, then the automatic calls to sqlite3_initialize()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1103
** are omitted and the application must call sqlite3_initialize() directly
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1104
** prior to using any other SQLite interface.  For maximum portability,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1105
** it is recommended that applications always invoke sqlite3_initialize()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1106
** directly prior to using any other SQLite interface.  Future releases
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1107
** of SQLite may require this.  In other words, the behavior exhibited
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1108
** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1109
** default behavior in some future release of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1110
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1111
** The sqlite3_os_init() routine does operating-system specific
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1112
** initialization of the SQLite library.  The sqlite3_os_end()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1113
** routine undoes the effect of sqlite3_os_init().  Typical tasks
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1114
** performed by these routines include allocation or deallocation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1115
** of static resources, initialization of global variables,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1116
** setting up a default [sqlite3_vfs] module, or setting up
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1117
** a default configuration using [sqlite3_config()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1118
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1119
** The application should never invoke either sqlite3_os_init()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1120
** or sqlite3_os_end() directly.  The application should only invoke
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1121
** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1122
** interface is called automatically by sqlite3_initialize() and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1123
** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1124
** implementations for sqlite3_os_init() and sqlite3_os_end()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1125
** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1126
** When [custom builds | built for other platforms]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1127
** (using the [SQLITE_OS_OTHER=1] compile-time
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1128
** option) the application must supply a suitable implementation for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1129
** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1130
** implementation of sqlite3_os_init() or sqlite3_os_end()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1131
** must return [SQLITE_OK] on success and some other [error code] upon
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1132
** failure.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1133
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1134
SQLITE_API int sqlite3_initialize(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1135
SQLITE_API int sqlite3_shutdown(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1136
SQLITE_API int sqlite3_os_init(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1137
SQLITE_API int sqlite3_os_end(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1138
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1139
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1140
** CAPI3REF: Configuring The SQLite Library
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1141
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1142
** The sqlite3_config() interface is used to make global configuration
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1143
** changes to SQLite in order to tune SQLite to the specific needs of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1144
** the application.  The default configuration is recommended for most
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1145
** applications and so this routine is usually not necessary.  It is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1146
** provided to support rare applications with unusual needs.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1147
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1148
** The sqlite3_config() interface is not threadsafe.  The application
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1149
** must insure that no other SQLite interfaces are invoked by other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1150
** threads while sqlite3_config() is running.  Furthermore, sqlite3_config()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1151
** may only be invoked prior to library initialization using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1152
** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1153
** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1154
** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1155
** Note, however, that ^sqlite3_config() can be called as part of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1156
** implementation of an application-defined [sqlite3_os_init()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1157
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1158
** The first argument to sqlite3_config() is an integer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1159
** [configuration option] that determines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1160
** what property of SQLite is to be configured.  Subsequent arguments
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1161
** vary depending on the [configuration option]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1162
** in the first argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1163
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1164
** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1165
** ^If the option is unknown or SQLite is unable to set the option
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1166
** then this routine returns a non-zero [error code].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1167
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1168
SQLITE_API int sqlite3_config(int, ...);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1169
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1170
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1171
** CAPI3REF: Configure database connections
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1172
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1173
** The sqlite3_db_config() interface is used to make configuration
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1174
** changes to a [database connection].  The interface is similar to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1175
** [sqlite3_config()] except that the changes apply to a single
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1176
** [database connection] (specified in the first argument).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1177
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1178
** The second argument to sqlite3_db_config(D,V,...)  is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1179
** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1180
** that indicates what aspect of the [database connection] is being configured.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1181
** Subsequent arguments vary depending on the configuration verb.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1182
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1183
** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1184
** the call is considered successful.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1185
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1186
SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1187
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1188
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1189
** CAPI3REF: Memory Allocation Routines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1190
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1191
** An instance of this object defines the interface between SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1192
** and low-level memory allocation routines.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1193
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1194
** This object is used in only one place in the SQLite interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1195
** A pointer to an instance of this object is the argument to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1196
** [sqlite3_config()] when the configuration option is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1197
** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1198
** By creating an instance of this object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1199
** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1200
** during configuration, an application can specify an alternative
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1201
** memory allocation subsystem for SQLite to use for all of its
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1202
** dynamic memory needs.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1203
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1204
** Note that SQLite comes with several [built-in memory allocators]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1205
** that are perfectly adequate for the overwhelming majority of applications
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1206
** and that this object is only useful to a tiny minority of applications
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1207
** with specialized memory allocation requirements.  This object is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1208
** also used during testing of SQLite in order to specify an alternative
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1209
** memory allocator that simulates memory out-of-memory conditions in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1210
** order to verify that SQLite recovers gracefully from such
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1211
** conditions.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1212
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1213
** The xMalloc, xRealloc, and xFree methods must work like the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1214
** malloc(), realloc() and free() functions from the standard C library.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1215
** ^SQLite guarantees that the second argument to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1216
** xRealloc is always a value returned by a prior call to xRoundup.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1217
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1218
** xSize should return the allocated size of a memory allocation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1219
** previously obtained from xMalloc or xRealloc.  The allocated size
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1220
** is always at least as big as the requested size but may be larger.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1221
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1222
** The xRoundup method returns what would be the allocated size of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1223
** a memory allocation given a particular requested size.  Most memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1224
** allocators round up memory allocations at least to the next multiple
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1225
** of 8.  Some allocators round up to a larger multiple or to a power of 2.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1226
** Every memory allocation request coming in through [sqlite3_malloc()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1227
** or [sqlite3_realloc()] first calls xRoundup.  If xRoundup returns 0, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1228
** that causes the corresponding memory allocation to fail.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1229
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1230
** The xInit method initializes the memory allocator.  (For example,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1231
** it might allocate any require mutexes or initialize internal data
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1232
** structures.  The xShutdown method is invoked (indirectly) by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1233
** [sqlite3_shutdown()] and should deallocate any resources acquired
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1234
** by xInit.  The pAppData pointer is used as the only parameter to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1235
** xInit and xShutdown.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1236
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1237
** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1238
** the xInit method, so the xInit method need not be threadsafe.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1239
** xShutdown method is only called from [sqlite3_shutdown()] so it does
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1240
** not need to be threadsafe either.  For all other methods, SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1241
** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1242
** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1243
** it is by default) and so the methods are automatically serialized.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1244
** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1245
** methods must be threadsafe or else make their own arrangements for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1246
** serialization.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1247
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1248
** SQLite will never invoke xInit() more than once without an intervening
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1249
** call to xShutdown().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1250
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1251
typedef struct sqlite3_mem_methods sqlite3_mem_methods;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1252
struct sqlite3_mem_methods {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1253
  void *(*xMalloc)(int);         /* Memory allocation function */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1254
  void (*xFree)(void*);          /* Free a prior allocation */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1255
  void *(*xRealloc)(void*,int);  /* Resize an allocation */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1256
  int (*xSize)(void*);           /* Return the size of an allocation */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1257
  int (*xRoundup)(int);          /* Round up request size to allocation size */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1258
  int (*xInit)(void*);           /* Initialize the memory allocator */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1259
  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1260
  void *pAppData;                /* Argument to xInit() and xShutdown() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1261
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1262
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1263
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1264
** CAPI3REF: Configuration Options
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1265
** KEYWORDS: {configuration option}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1266
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1267
** These constants are the available integer configuration options that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1268
** can be passed as the first argument to the [sqlite3_config()] interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1269
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1270
** New configuration options may be added in future releases of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1271
** Existing configuration options might be discontinued.  Applications
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1272
** should check the return code from [sqlite3_config()] to make sure that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1273
** the call worked.  The [sqlite3_config()] interface will return a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1274
** non-zero [error code] if a discontinued or unsupported configuration option
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1275
** is invoked.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1276
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1277
** <dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1278
** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1279
** <dd>There are no arguments to this option.  ^This option sets the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1280
** [threading mode] to Single-thread.  In other words, it disables
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1281
** all mutexing and puts SQLite into a mode where it can only be used
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1282
** by a single thread.   ^If SQLite is compiled with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1283
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1284
** it is not possible to change the [threading mode] from its default
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1285
** value of Single-thread and so [sqlite3_config()] will return 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1286
** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1287
** configuration option.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1288
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1289
** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1290
** <dd>There are no arguments to this option.  ^This option sets the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1291
** [threading mode] to Multi-thread.  In other words, it disables
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1292
** mutexing on [database connection] and [prepared statement] objects.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1293
** The application is responsible for serializing access to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1294
** [database connections] and [prepared statements].  But other mutexes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1295
** are enabled so that SQLite will be safe to use in a multi-threaded
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1296
** environment as long as no two threads attempt to use the same
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1297
** [database connection] at the same time.  ^If SQLite is compiled with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1298
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1299
** it is not possible to set the Multi-thread [threading mode] and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1300
** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1301
** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1302
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1303
** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1304
** <dd>There are no arguments to this option.  ^This option sets the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1305
** [threading mode] to Serialized. In other words, this option enables
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1306
** all mutexes including the recursive
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1307
** mutexes on [database connection] and [prepared statement] objects.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1308
** In this mode (which is the default when SQLite is compiled with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1309
** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1310
** to [database connections] and [prepared statements] so that the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1311
** application is free to use the same [database connection] or the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1312
** same [prepared statement] in different threads at the same time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1313
** ^If SQLite is compiled with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1314
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1315
** it is not possible to set the Serialized [threading mode] and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1316
** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1317
** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1318
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1319
** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1320
** <dd> ^(This option takes a single argument which is a pointer to an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1321
** instance of the [sqlite3_mem_methods] structure.  The argument specifies
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1322
** alternative low-level memory allocation routines to be used in place of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1323
** the memory allocation routines built into SQLite.)^ ^SQLite makes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1324
** its own private copy of the content of the [sqlite3_mem_methods] structure
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1325
** before the [sqlite3_config()] call returns.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1326
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1327
** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1328
** <dd> ^(This option takes a single argument which is a pointer to an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1329
** instance of the [sqlite3_mem_methods] structure.  The [sqlite3_mem_methods]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1330
** structure is filled with the currently defined memory allocation routines.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1331
** This option can be used to overload the default memory allocation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1332
** routines with a wrapper that simulations memory allocation failure or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1333
** tracks memory usage, for example. </dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1334
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1335
** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1336
** <dd> ^This option takes single argument of type int, interpreted as a 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1337
** boolean, which enables or disables the collection of memory allocation 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1338
** statistics. ^(When memory allocation statistics are disabled, the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1339
** following SQLite interfaces become non-operational:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1340
**   <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1341
**   <li> [sqlite3_memory_used()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1342
**   <li> [sqlite3_memory_highwater()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1343
**   <li> [sqlite3_soft_heap_limit64()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1344
**   <li> [sqlite3_status()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1345
**   </ul>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1346
** ^Memory allocation statistics are enabled by default unless SQLite is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1347
** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1348
** allocation statistics are disabled by default.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1349
** </dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1350
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1351
** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1352
** <dd> ^This option specifies a static memory buffer that SQLite can use for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1353
** scratch memory.  There are three arguments:  A pointer an 8-byte
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1354
** aligned memory buffer from which the scratch allocations will be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1355
** drawn, the size of each scratch allocation (sz),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1356
** and the maximum number of scratch allocations (N).  The sz
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1357
** argument must be a multiple of 16.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1358
** The first argument must be a pointer to an 8-byte aligned buffer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1359
** of at least sz*N bytes of memory.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1360
** ^SQLite will use no more than two scratch buffers per thread.  So
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1361
** N should be set to twice the expected maximum number of threads.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1362
** ^SQLite will never require a scratch buffer that is more than 6
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1363
** times the database page size. ^If SQLite needs needs additional
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1364
** scratch memory beyond what is provided by this configuration option, then 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1365
** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1366
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1367
** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1368
** <dd> ^This option specifies a static memory buffer that SQLite can use for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1369
** the database page cache with the default page cache implementation.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1370
** This configuration should not be used if an application-define page
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1371
** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1372
** There are three arguments to this option: A pointer to 8-byte aligned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1373
** memory, the size of each page buffer (sz), and the number of pages (N).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1374
** The sz argument should be the size of the largest database page
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1375
** (a power of two between 512 and 32768) plus a little extra for each
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1376
** page header.  ^The page header size is 20 to 40 bytes depending on
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1377
** the host architecture.  ^It is harmless, apart from the wasted memory,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1378
** to make sz a little too large.  The first
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1379
** argument should point to an allocation of at least sz*N bytes of memory.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1380
** ^SQLite will use the memory provided by the first argument to satisfy its
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1381
** memory needs for the first N pages that it adds to cache.  ^If additional
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1382
** page cache memory is needed beyond what is provided by this option, then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1383
** SQLite goes to [sqlite3_malloc()] for the additional storage space.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1384
** The pointer in the first argument must
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1385
** be aligned to an 8-byte boundary or subsequent behavior of SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1386
** will be undefined.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1387
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1388
** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1389
** <dd> ^This option specifies a static memory buffer that SQLite will use
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1390
** for all of its dynamic memory allocation needs beyond those provided
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1391
** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1392
** There are three arguments: An 8-byte aligned pointer to the memory,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1393
** the number of bytes in the memory buffer, and the minimum allocation size.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1394
** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1395
** to using its default memory allocator (the system malloc() implementation),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1396
** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  ^If the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1397
** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1398
** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1399
** allocator is engaged to handle all of SQLites memory allocation needs.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1400
** The first pointer (the memory pointer) must be aligned to an 8-byte
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1401
** boundary or subsequent behavior of SQLite will be undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1402
** The minimum allocation size is capped at 2^12. Reasonable values
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1403
** for the minimum allocation size are 2^5 through 2^8.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1404
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1405
** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1406
** <dd> ^(This option takes a single argument which is a pointer to an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1407
** instance of the [sqlite3_mutex_methods] structure.  The argument specifies
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1408
** alternative low-level mutex routines to be used in place
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1409
** the mutex routines built into SQLite.)^  ^SQLite makes a copy of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1410
** content of the [sqlite3_mutex_methods] structure before the call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1411
** [sqlite3_config()] returns. ^If SQLite is compiled with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1412
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1413
** the entire mutexing subsystem is omitted from the build and hence calls to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1414
** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1415
** return [SQLITE_ERROR].</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1416
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1417
** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1418
** <dd> ^(This option takes a single argument which is a pointer to an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1419
** instance of the [sqlite3_mutex_methods] structure.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1420
** [sqlite3_mutex_methods]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1421
** structure is filled with the currently defined mutex routines.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1422
** This option can be used to overload the default mutex allocation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1423
** routines with a wrapper used to track mutex usage for performance
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1424
** profiling or testing, for example.   ^If SQLite is compiled with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1425
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1426
** the entire mutexing subsystem is omitted from the build and hence calls to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1427
** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1428
** return [SQLITE_ERROR].</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1429
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1430
** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1431
** <dd> ^(This option takes two arguments that determine the default
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1432
** memory allocation for the lookaside memory allocator on each
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1433
** [database connection].  The first argument is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1434
** size of each lookaside buffer slot and the second is the number of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1435
** slots allocated to each database connection.)^  ^(This option sets the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1436
** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1437
** verb to [sqlite3_db_config()] can be used to change the lookaside
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1438
** configuration on individual connections.)^ </dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1439
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1440
** [[SQLITE_CONFIG_PCACHE]] <dt>SQLITE_CONFIG_PCACHE</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1441
** <dd> ^(This option takes a single argument which is a pointer to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1442
** an [sqlite3_pcache_methods] object.  This object specifies the interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1443
** to a custom page cache implementation.)^  ^SQLite makes a copy of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1444
** object and uses it for page cache memory allocations.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1445
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1446
** [[SQLITE_CONFIG_GETPCACHE]] <dt>SQLITE_CONFIG_GETPCACHE</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1447
** <dd> ^(This option takes a single argument which is a pointer to an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1448
** [sqlite3_pcache_methods] object.  SQLite copies of the current
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1449
** page cache implementation into that object.)^ </dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1450
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1451
** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1452
** <dd> ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1453
** function with a call signature of void(*)(void*,int,const char*), 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1454
** and a pointer to void. ^If the function pointer is not NULL, it is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1455
** invoked by [sqlite3_log()] to process each logging event.  ^If the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1456
** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1457
** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1458
** passed through as the first parameter to the application-defined logger
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1459
** function whenever that function is invoked.  ^The second parameter to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1460
** the logger function is a copy of the first parameter to the corresponding
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1461
** [sqlite3_log()] call and is intended to be a [result code] or an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1462
** [extended result code].  ^The third parameter passed to the logger is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1463
** log message after formatting via [sqlite3_snprintf()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1464
** The SQLite logging interface is not reentrant; the logger function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1465
** supplied by the application must not invoke any SQLite interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1466
** In a multi-threaded application, the application-defined logger
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1467
** function must be threadsafe. </dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1468
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1469
** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1470
** <dd> This option takes a single argument of type int. If non-zero, then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1471
** URI handling is globally enabled. If the parameter is zero, then URI handling
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1472
** is globally disabled. If URI handling is globally enabled, all filenames
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1473
** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1474
** specified as part of [ATTACH] commands are interpreted as URIs, regardless
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1475
** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1476
** connection is opened. If it is globally disabled, filenames are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1477
** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1478
** database connection is opened. By default, URI handling is globally
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1479
** disabled. The default value may be changed by compiling with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1480
** [SQLITE_USE_URI] symbol defined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1481
** </dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1482
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1483
#define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1484
#define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1485
#define SQLITE_CONFIG_SERIALIZED    3  /* nil */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1486
#define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1487
#define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1488
#define SQLITE_CONFIG_SCRATCH       6  /* void*, int sz, int N */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1489
#define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1490
#define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1491
#define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1492
#define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1493
#define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1494
/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1495
#define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1496
#define SQLITE_CONFIG_PCACHE       14  /* sqlite3_pcache_methods* */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1497
#define SQLITE_CONFIG_GETPCACHE    15  /* sqlite3_pcache_methods* */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1498
#define SQLITE_CONFIG_LOG          16  /* xFunc, void* */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1499
#define SQLITE_CONFIG_URI          17  /* int */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1500
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1501
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1502
** CAPI3REF: Database Connection Configuration Options
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1503
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1504
** These constants are the available integer configuration options that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1505
** can be passed as the second argument to the [sqlite3_db_config()] interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1506
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1507
** New configuration options may be added in future releases of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1508
** Existing configuration options might be discontinued.  Applications
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1509
** should check the return code from [sqlite3_db_config()] to make sure that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1510
** the call worked.  ^The [sqlite3_db_config()] interface will return a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1511
** non-zero [error code] if a discontinued or unsupported configuration option
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1512
** is invoked.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1513
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1514
** <dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1515
** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1516
** <dd> ^This option takes three additional arguments that determine the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1517
** [lookaside memory allocator] configuration for the [database connection].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1518
** ^The first argument (the third parameter to [sqlite3_db_config()] is a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1519
** pointer to a memory buffer to use for lookaside memory.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1520
** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1521
** may be NULL in which case SQLite will allocate the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1522
** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1523
** size of each lookaside buffer slot.  ^The third argument is the number of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1524
** slots.  The size of the buffer in the first argument must be greater than
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1525
** or equal to the product of the second and third arguments.  The buffer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1526
** must be aligned to an 8-byte boundary.  ^If the second argument to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1527
** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1528
** rounded down to the next smaller multiple of 8.  ^(The lookaside memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1529
** configuration for a database connection can only be changed when that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1530
** connection is not currently using lookaside memory, or in other words
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1531
** when the "current value" returned by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1532
** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1533
** Any attempt to change the lookaside memory configuration when lookaside
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1534
** memory is in use leaves the configuration unchanged and returns 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1535
** [SQLITE_BUSY].)^</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1536
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1537
** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1538
** <dd> ^This option is used to enable or disable the enforcement of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1539
** [foreign key constraints].  There should be two additional arguments.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1540
** The first argument is an integer which is 0 to disable FK enforcement,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1541
** positive to enable FK enforcement or negative to leave FK enforcement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1542
** unchanged.  The second parameter is a pointer to an integer into which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1543
** is written 0 or 1 to indicate whether FK enforcement is off or on
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1544
** following this call.  The second parameter may be a NULL pointer, in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1545
** which case the FK enforcement setting is not reported back. </dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1546
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1547
** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1548
** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1549
** There should be two additional arguments.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1550
** The first argument is an integer which is 0 to disable triggers,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1551
** positive to enable triggers or negative to leave the setting unchanged.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1552
** The second parameter is a pointer to an integer into which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1553
** is written 0 or 1 to indicate whether triggers are disabled or enabled
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1554
** following this call.  The second parameter may be a NULL pointer, in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1555
** which case the trigger setting is not reported back. </dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1556
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1557
** </dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1558
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1559
#define SQLITE_DBCONFIG_LOOKASIDE       1001  /* void* int int */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1560
#define SQLITE_DBCONFIG_ENABLE_FKEY     1002  /* int int* */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1561
#define SQLITE_DBCONFIG_ENABLE_TRIGGER  1003  /* int int* */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1562
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1563
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1564
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1565
** CAPI3REF: Enable Or Disable Extended Result Codes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1566
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1567
** ^The sqlite3_extended_result_codes() routine enables or disables the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1568
** [extended result codes] feature of SQLite. ^The extended result
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1569
** codes are disabled by default for historical compatibility.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1570
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1571
SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1572
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1573
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1574
** CAPI3REF: Last Insert Rowid
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1575
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1576
** ^Each entry in an SQLite table has a unique 64-bit signed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1577
** integer key called the [ROWID | "rowid"]. ^The rowid is always available
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1578
** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1579
** names are not also used by explicitly declared columns. ^If
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1580
** the table has a column of type [INTEGER PRIMARY KEY] then that column
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1581
** is another alias for the rowid.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1582
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1583
** ^This routine returns the [rowid] of the most recent
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1584
** successful [INSERT] into the database from the [database connection]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1585
** in the first argument.  ^As of SQLite version 3.7.7, this routines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1586
** records the last insert rowid of both ordinary tables and [virtual tables].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1587
** ^If no successful [INSERT]s
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1588
** have ever occurred on that database connection, zero is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1589
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1590
** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1591
** method, then this routine will return the [rowid] of the inserted
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1592
** row as long as the trigger or virtual table method is running.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1593
** But once the trigger or virtual table method ends, the value returned 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1594
** by this routine reverts to what it was before the trigger or virtual
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1595
** table method began.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1596
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1597
** ^An [INSERT] that fails due to a constraint violation is not a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1598
** successful [INSERT] and does not change the value returned by this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1599
** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1600
** and INSERT OR ABORT make no changes to the return value of this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1601
** routine when their insertion fails.  ^(When INSERT OR REPLACE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1602
** encounters a constraint violation, it does not fail.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1603
** INSERT continues to completion after deleting rows that caused
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1604
** the constraint problem so INSERT OR REPLACE will always change
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1605
** the return value of this interface.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1606
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1607
** ^For the purposes of this routine, an [INSERT] is considered to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1608
** be successful even if it is subsequently rolled back.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1609
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1610
** This function is accessible to SQL statements via the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1611
** [last_insert_rowid() SQL function].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1612
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1613
** If a separate thread performs a new [INSERT] on the same
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1614
** database connection while the [sqlite3_last_insert_rowid()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1615
** function is running and thus changes the last insert [rowid],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1616
** then the value returned by [sqlite3_last_insert_rowid()] is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1617
** unpredictable and might not equal either the old or the new
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1618
** last insert [rowid].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1619
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1620
SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1621
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1622
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1623
** CAPI3REF: Count The Number Of Rows Modified
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1624
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1625
** ^This function returns the number of database rows that were changed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1626
** or inserted or deleted by the most recently completed SQL statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1627
** on the [database connection] specified by the first parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1628
** ^(Only changes that are directly specified by the [INSERT], [UPDATE],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1629
** or [DELETE] statement are counted.  Auxiliary changes caused by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1630
** triggers or [foreign key actions] are not counted.)^ Use the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1631
** [sqlite3_total_changes()] function to find the total number of changes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1632
** including changes caused by triggers and foreign key actions.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1633
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1634
** ^Changes to a view that are simulated by an [INSTEAD OF trigger]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1635
** are not counted.  Only real table changes are counted.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1636
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1637
** ^(A "row change" is a change to a single row of a single table
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1638
** caused by an INSERT, DELETE, or UPDATE statement.  Rows that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1639
** are changed as side effects of [REPLACE] constraint resolution,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1640
** rollback, ABORT processing, [DROP TABLE], or by any other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1641
** mechanisms do not count as direct row changes.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1642
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1643
** A "trigger context" is a scope of execution that begins and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1644
** ends with the script of a [CREATE TRIGGER | trigger]. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1645
** Most SQL statements are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1646
** evaluated outside of any trigger.  This is the "top level"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1647
** trigger context.  If a trigger fires from the top level, a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1648
** new trigger context is entered for the duration of that one
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1649
** trigger.  Subtriggers create subcontexts for their duration.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1650
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1651
** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1652
** not create a new trigger context.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1653
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1654
** ^This function returns the number of direct row changes in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1655
** most recent INSERT, UPDATE, or DELETE statement within the same
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1656
** trigger context.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1657
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1658
** ^Thus, when called from the top level, this function returns the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1659
** number of changes in the most recent INSERT, UPDATE, or DELETE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1660
** that also occurred at the top level.  ^(Within the body of a trigger,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1661
** the sqlite3_changes() interface can be called to find the number of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1662
** changes in the most recently completed INSERT, UPDATE, or DELETE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1663
** statement within the body of the same trigger.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1664
** However, the number returned does not include changes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1665
** caused by subtriggers since those have their own context.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1666
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1667
** See also the [sqlite3_total_changes()] interface, the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1668
** [count_changes pragma], and the [changes() SQL function].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1669
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1670
** If a separate thread makes changes on the same database connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1671
** while [sqlite3_changes()] is running then the value returned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1672
** is unpredictable and not meaningful.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1673
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1674
SQLITE_API int sqlite3_changes(sqlite3*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1675
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1676
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1677
** CAPI3REF: Total Number Of Rows Modified
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1678
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1679
** ^This function returns the number of row changes caused by [INSERT],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1680
** [UPDATE] or [DELETE] statements since the [database connection] was opened.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1681
** ^(The count returned by sqlite3_total_changes() includes all changes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1682
** from all [CREATE TRIGGER | trigger] contexts and changes made by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1683
** [foreign key actions]. However,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1684
** the count does not include changes used to implement [REPLACE] constraints,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1685
** do rollbacks or ABORT processing, or [DROP TABLE] processing.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1686
** count does not include rows of views that fire an [INSTEAD OF trigger],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1687
** though if the INSTEAD OF trigger makes changes of its own, those changes 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1688
** are counted.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1689
** ^The sqlite3_total_changes() function counts the changes as soon as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1690
** the statement that makes them is completed (when the statement handle
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1691
** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1692
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1693
** See also the [sqlite3_changes()] interface, the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1694
** [count_changes pragma], and the [total_changes() SQL function].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1695
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1696
** If a separate thread makes changes on the same database connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1697
** while [sqlite3_total_changes()] is running then the value
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1698
** returned is unpredictable and not meaningful.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1699
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1700
SQLITE_API int sqlite3_total_changes(sqlite3*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1701
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1702
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1703
** CAPI3REF: Interrupt A Long-Running Query
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1704
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1705
** ^This function causes any pending database operation to abort and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1706
** return at its earliest opportunity. This routine is typically
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1707
** called in response to a user action such as pressing "Cancel"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1708
** or Ctrl-C where the user wants a long query operation to halt
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1709
** immediately.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1710
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1711
** ^It is safe to call this routine from a thread different from the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1712
** thread that is currently running the database operation.  But it
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1713
** is not safe to call this routine with a [database connection] that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1714
** is closed or might close before sqlite3_interrupt() returns.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1715
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1716
** ^If an SQL operation is very nearly finished at the time when
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1717
** sqlite3_interrupt() is called, then it might not have an opportunity
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1718
** to be interrupted and might continue to completion.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1719
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1720
** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1721
** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1722
** that is inside an explicit transaction, then the entire transaction
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1723
** will be rolled back automatically.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1724
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1725
** ^The sqlite3_interrupt(D) call is in effect until all currently running
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1726
** SQL statements on [database connection] D complete.  ^Any new SQL statements
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1727
** that are started after the sqlite3_interrupt() call and before the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1728
** running statements reaches zero are interrupted as if they had been
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1729
** running prior to the sqlite3_interrupt() call.  ^New SQL statements
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1730
** that are started after the running statement count reaches zero are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1731
** not effected by the sqlite3_interrupt().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1732
** ^A call to sqlite3_interrupt(D) that occurs when there are no running
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1733
** SQL statements is a no-op and has no effect on SQL statements
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1734
** that are started after the sqlite3_interrupt() call returns.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1735
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1736
** If the database connection closes while [sqlite3_interrupt()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1737
** is running then bad things will likely happen.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1738
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1739
SQLITE_API void sqlite3_interrupt(sqlite3*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1740
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1741
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1742
** CAPI3REF: Determine If An SQL Statement Is Complete
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1743
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1744
** These routines are useful during command-line input to determine if the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1745
** currently entered text seems to form a complete SQL statement or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1746
** if additional input is needed before sending the text into
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1747
** SQLite for parsing.  ^These routines return 1 if the input string
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1748
** appears to be a complete SQL statement.  ^A statement is judged to be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1749
** complete if it ends with a semicolon token and is not a prefix of a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1750
** well-formed CREATE TRIGGER statement.  ^Semicolons that are embedded within
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1751
** string literals or quoted identifier names or comments are not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1752
** independent tokens (they are part of the token in which they are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1753
** embedded) and thus do not count as a statement terminator.  ^Whitespace
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1754
** and comments that follow the final semicolon are ignored.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1755
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1756
** ^These routines return 0 if the statement is incomplete.  ^If a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1757
** memory allocation fails, then SQLITE_NOMEM is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1758
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1759
** ^These routines do not parse the SQL statements thus
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1760
** will not detect syntactically incorrect SQL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1761
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1762
** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1763
** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1764
** automatically by sqlite3_complete16().  If that initialization fails,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1765
** then the return value from sqlite3_complete16() will be non-zero
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1766
** regardless of whether or not the input SQL is complete.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1767
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1768
** The input to [sqlite3_complete()] must be a zero-terminated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1769
** UTF-8 string.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1770
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1771
** The input to [sqlite3_complete16()] must be a zero-terminated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1772
** UTF-16 string in native byte order.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1773
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1774
SQLITE_API int sqlite3_complete(const char *sql);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1775
SQLITE_API int sqlite3_complete16(const void *sql);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1776
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1777
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1778
** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1779
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1780
** ^This routine sets a callback function that might be invoked whenever
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1781
** an attempt is made to open a database table that another thread
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1782
** or process has locked.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1783
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1784
** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1785
** is returned immediately upon encountering the lock.  ^If the busy callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1786
** is not NULL, then the callback might be invoked with two arguments.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1787
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1788
** ^The first argument to the busy handler is a copy of the void* pointer which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1789
** is the third argument to sqlite3_busy_handler().  ^The second argument to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1790
** the busy handler callback is the number of times that the busy handler has
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1791
** been invoked for this locking event.  ^If the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1792
** busy callback returns 0, then no additional attempts are made to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1793
** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1794
** ^If the callback returns non-zero, then another attempt
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1795
** is made to open the database for reading and the cycle repeats.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1796
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1797
** The presence of a busy handler does not guarantee that it will be invoked
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1798
** when there is lock contention. ^If SQLite determines that invoking the busy
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1799
** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1800
** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1801
** Consider a scenario where one process is holding a read lock that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1802
** it is trying to promote to a reserved lock and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1803
** a second process is holding a reserved lock that it is trying
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1804
** to promote to an exclusive lock.  The first process cannot proceed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1805
** because it is blocked by the second and the second process cannot
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1806
** proceed because it is blocked by the first.  If both processes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1807
** invoke the busy handlers, neither will make any progress.  Therefore,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1808
** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1809
** will induce the first process to release its read lock and allow
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1810
** the second process to proceed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1811
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1812
** ^The default busy callback is NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1813
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1814
** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1815
** when SQLite is in the middle of a large transaction where all the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1816
** changes will not fit into the in-memory cache.  SQLite will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1817
** already hold a RESERVED lock on the database file, but it needs
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1818
** to promote this lock to EXCLUSIVE so that it can spill cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1819
** pages into the database file without harm to concurrent
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1820
** readers.  ^If it is unable to promote the lock, then the in-memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1821
** cache will be left in an inconsistent state and so the error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1822
** code is promoted from the relatively benign [SQLITE_BUSY] to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1823
** the more severe [SQLITE_IOERR_BLOCKED].  ^This error code promotion
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1824
** forces an automatic rollback of the changes.  See the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1825
** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1826
** CorruptionFollowingBusyError</a> wiki page for a discussion of why
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1827
** this is important.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1828
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1829
** ^(There can only be a single busy handler defined for each
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1830
** [database connection].  Setting a new busy handler clears any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1831
** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1832
** will also set or clear the busy handler.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1833
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1834
** The busy callback should not take any actions which modify the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1835
** database connection that invoked the busy handler.  Any such actions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1836
** result in undefined behavior.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1837
** 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1838
** A busy handler must not close the database connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1839
** or [prepared statement] that invoked the busy handler.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1840
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1841
SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1842
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1843
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1844
** CAPI3REF: Set A Busy Timeout
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1845
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1846
** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1847
** for a specified amount of time when a table is locked.  ^The handler
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1848
** will sleep multiple times until at least "ms" milliseconds of sleeping
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1849
** have accumulated.  ^After at least "ms" milliseconds of sleeping,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1850
** the handler returns 0 which causes [sqlite3_step()] to return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1851
** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1852
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1853
** ^Calling this routine with an argument less than or equal to zero
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1854
** turns off all busy handlers.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1855
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1856
** ^(There can only be a single busy handler for a particular
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1857
** [database connection] any any given moment.  If another busy handler
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1858
** was defined  (using [sqlite3_busy_handler()]) prior to calling
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1859
** this routine, that other busy handler is cleared.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1860
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1861
SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1862
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1863
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1864
** CAPI3REF: Convenience Routines For Running Queries
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1865
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1866
** This is a legacy interface that is preserved for backwards compatibility.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1867
** Use of this interface is not recommended.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1868
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1869
** Definition: A <b>result table</b> is memory data structure created by the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1870
** [sqlite3_get_table()] interface.  A result table records the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1871
** complete query results from one or more queries.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1872
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1873
** The table conceptually has a number of rows and columns.  But
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1874
** these numbers are not part of the result table itself.  These
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1875
** numbers are obtained separately.  Let N be the number of rows
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1876
** and M be the number of columns.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1877
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1878
** A result table is an array of pointers to zero-terminated UTF-8 strings.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1879
** There are (N+1)*M elements in the array.  The first M pointers point
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1880
** to zero-terminated strings that  contain the names of the columns.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1881
** The remaining entries all point to query results.  NULL values result
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1882
** in NULL pointers.  All other values are in their UTF-8 zero-terminated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1883
** string representation as returned by [sqlite3_column_text()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1884
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1885
** A result table might consist of one or more memory allocations.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1886
** It is not safe to pass a result table directly to [sqlite3_free()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1887
** A result table should be deallocated using [sqlite3_free_table()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1888
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1889
** ^(As an example of the result table format, suppose a query result
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1890
** is as follows:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1891
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1892
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1893
**        Name        | Age
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1894
**        -----------------------
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1895
**        Alice       | 43
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1896
**        Bob         | 28
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1897
**        Cindy       | 21
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1898
** </pre></blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1899
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1900
** There are two column (M==2) and three rows (N==3).  Thus the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1901
** result table has 8 entries.  Suppose the result table is stored
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1902
** in an array names azResult.  Then azResult holds this content:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1903
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1904
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1905
**        azResult&#91;0] = "Name";
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1906
**        azResult&#91;1] = "Age";
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1907
**        azResult&#91;2] = "Alice";
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1908
**        azResult&#91;3] = "43";
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1909
**        azResult&#91;4] = "Bob";
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1910
**        azResult&#91;5] = "28";
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1911
**        azResult&#91;6] = "Cindy";
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1912
**        azResult&#91;7] = "21";
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1913
** </pre></blockquote>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1914
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1915
** ^The sqlite3_get_table() function evaluates one or more
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1916
** semicolon-separated SQL statements in the zero-terminated UTF-8
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1917
** string of its 2nd parameter and returns a result table to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1918
** pointer given in its 3rd parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1919
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1920
** After the application has finished with the result from sqlite3_get_table(),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1921
** it must pass the result table pointer to sqlite3_free_table() in order to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1922
** release the memory that was malloced.  Because of the way the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1923
** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1924
** function must not try to call [sqlite3_free()] directly.  Only
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1925
** [sqlite3_free_table()] is able to release the memory properly and safely.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1926
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1927
** The sqlite3_get_table() interface is implemented as a wrapper around
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1928
** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1929
** to any internal data structures of SQLite.  It uses only the public
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1930
** interface defined here.  As a consequence, errors that occur in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1931
** wrapper layer outside of the internal [sqlite3_exec()] call are not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1932
** reflected in subsequent calls to [sqlite3_errcode()] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1933
** [sqlite3_errmsg()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1934
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1935
SQLITE_API int sqlite3_get_table(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1936
  sqlite3 *db,          /* An open database */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1937
  const char *zSql,     /* SQL to be evaluated */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1938
  char ***pazResult,    /* Results of the query */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1939
  int *pnRow,           /* Number of result rows written here */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1940
  int *pnColumn,        /* Number of result columns written here */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1941
  char **pzErrmsg       /* Error msg written here */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1942
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1943
SQLITE_API void sqlite3_free_table(char **result);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1944
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1945
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1946
** CAPI3REF: Formatted String Printing Functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1947
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1948
** These routines are work-alikes of the "printf()" family of functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1949
** from the standard C library.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1950
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1951
** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1952
** results into memory obtained from [sqlite3_malloc()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1953
** The strings returned by these two routines should be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1954
** released by [sqlite3_free()].  ^Both routines return a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1955
** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1956
** memory to hold the resulting string.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1957
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1958
** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1959
** the standard C library.  The result is written into the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1960
** buffer supplied as the second parameter whose size is given by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1961
** the first parameter. Note that the order of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1962
** first two parameters is reversed from snprintf().)^  This is an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1963
** historical accident that cannot be fixed without breaking
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1964
** backwards compatibility.  ^(Note also that sqlite3_snprintf()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1965
** returns a pointer to its buffer instead of the number of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1966
** characters actually written into the buffer.)^  We admit that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1967
** the number of characters written would be a more useful return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1968
** value but we cannot change the implementation of sqlite3_snprintf()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1969
** now without breaking compatibility.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1970
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1971
** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1972
** guarantees that the buffer is always zero-terminated.  ^The first
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1973
** parameter "n" is the total size of the buffer, including space for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1974
** the zero terminator.  So the longest string that can be completely
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1975
** written will be n-1 characters.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1976
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1977
** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1978
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1979
** These routines all implement some additional formatting
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1980
** options that are useful for constructing SQL statements.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1981
** All of the usual printf() formatting options apply.  In addition, there
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1982
** is are "%q", "%Q", and "%z" options.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1983
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1984
** ^(The %q option works like %s in that it substitutes a null-terminated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1985
** string from the argument list.  But %q also doubles every '\'' character.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1986
** %q is designed for use inside a string literal.)^  By doubling each '\''
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1987
** character it escapes that character and allows it to be inserted into
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1988
** the string.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1989
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1990
** For example, assume the string variable zText contains text as follows:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1991
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1992
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1993
**  char *zText = "It's a happy day!";
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1994
** </pre></blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1995
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1996
** One can use this text in an SQL statement as follows:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1997
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1998
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  1999
**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2000
**  sqlite3_exec(db, zSQL, 0, 0, 0);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2001
**  sqlite3_free(zSQL);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2002
** </pre></blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2003
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2004
** Because the %q format string is used, the '\'' character in zText
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2005
** is escaped and the SQL generated is as follows:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2006
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2007
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2008
**  INSERT INTO table1 VALUES('It''s a happy day!')
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2009
** </pre></blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2010
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2011
** This is correct.  Had we used %s instead of %q, the generated SQL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2012
** would have looked like this:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2013
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2014
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2015
**  INSERT INTO table1 VALUES('It's a happy day!');
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2016
** </pre></blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2017
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2018
** This second example is an SQL syntax error.  As a general rule you should
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2019
** always use %q instead of %s when inserting text into a string literal.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2020
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2021
** ^(The %Q option works like %q except it also adds single quotes around
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2022
** the outside of the total string.  Additionally, if the parameter in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2023
** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2024
** single quotes).)^  So, for example, one could say:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2025
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2026
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2027
**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2028
**  sqlite3_exec(db, zSQL, 0, 0, 0);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2029
**  sqlite3_free(zSQL);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2030
** </pre></blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2031
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2032
** The code above will render a correct SQL statement in the zSQL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2033
** variable even if the zText variable is a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2034
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2035
** ^(The "%z" formatting option works like "%s" but with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2036
** addition that after the string has been read and copied into
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2037
** the result, [sqlite3_free()] is called on the input string.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2038
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2039
SQLITE_API char *sqlite3_mprintf(const char*,...);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2040
SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2041
SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2042
SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2043
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2044
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2045
** CAPI3REF: Memory Allocation Subsystem
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2046
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2047
** The SQLite core uses these three routines for all of its own
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2048
** internal memory allocation needs. "Core" in the previous sentence
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2049
** does not include operating-system specific VFS implementation.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2050
** Windows VFS uses native malloc() and free() for some operations.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2051
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2052
** ^The sqlite3_malloc() routine returns a pointer to a block
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2053
** of memory at least N bytes in length, where N is the parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2054
** ^If sqlite3_malloc() is unable to obtain sufficient free
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2055
** memory, it returns a NULL pointer.  ^If the parameter N to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2056
** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2057
** a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2058
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2059
** ^Calling sqlite3_free() with a pointer previously returned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2060
** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2061
** that it might be reused.  ^The sqlite3_free() routine is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2062
** a no-op if is called with a NULL pointer.  Passing a NULL pointer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2063
** to sqlite3_free() is harmless.  After being freed, memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2064
** should neither be read nor written.  Even reading previously freed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2065
** memory might result in a segmentation fault or other severe error.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2066
** Memory corruption, a segmentation fault, or other severe error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2067
** might result if sqlite3_free() is called with a non-NULL pointer that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2068
** was not obtained from sqlite3_malloc() or sqlite3_realloc().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2069
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2070
** ^(The sqlite3_realloc() interface attempts to resize a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2071
** prior memory allocation to be at least N bytes, where N is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2072
** second parameter.  The memory allocation to be resized is the first
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2073
** parameter.)^ ^ If the first parameter to sqlite3_realloc()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2074
** is a NULL pointer then its behavior is identical to calling
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2075
** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2076
** ^If the second parameter to sqlite3_realloc() is zero or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2077
** negative then the behavior is exactly the same as calling
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2078
** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2079
** ^sqlite3_realloc() returns a pointer to a memory allocation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2080
** of at least N bytes in size or NULL if sufficient memory is unavailable.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2081
** ^If M is the size of the prior allocation, then min(N,M) bytes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2082
** of the prior allocation are copied into the beginning of buffer returned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2083
** by sqlite3_realloc() and the prior allocation is freed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2084
** ^If sqlite3_realloc() returns NULL, then the prior allocation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2085
** is not freed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2086
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2087
** ^The memory returned by sqlite3_malloc() and sqlite3_realloc()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2088
** is always aligned to at least an 8 byte boundary, or to a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2089
** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2090
** option is used.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2091
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2092
** In SQLite version 3.5.0 and 3.5.1, it was possible to define
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2093
** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2094
** implementation of these routines to be omitted.  That capability
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2095
** is no longer provided.  Only built-in memory allocators can be used.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2096
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2097
** The Windows OS interface layer calls
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2098
** the system malloc() and free() directly when converting
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2099
** filenames between the UTF-8 encoding used by SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2100
** and whatever filename encoding is used by the particular Windows
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2101
** installation.  Memory allocation errors are detected, but
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2102
** they are reported back as [SQLITE_CANTOPEN] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2103
** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2104
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2105
** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2106
** must be either NULL or else pointers obtained from a prior
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2107
** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2108
** not yet been released.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2109
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2110
** The application must not read or write any part of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2111
** a block of memory after it has been released using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2112
** [sqlite3_free()] or [sqlite3_realloc()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2113
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2114
SQLITE_API void *sqlite3_malloc(int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2115
SQLITE_API void *sqlite3_realloc(void*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2116
SQLITE_API void sqlite3_free(void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2117
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2118
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2119
** CAPI3REF: Memory Allocator Statistics
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2120
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2121
** SQLite provides these two interfaces for reporting on the status
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2122
** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2123
** routines, which form the built-in memory allocation subsystem.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2124
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2125
** ^The [sqlite3_memory_used()] routine returns the number of bytes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2126
** of memory currently outstanding (malloced but not freed).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2127
** ^The [sqlite3_memory_highwater()] routine returns the maximum
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2128
** value of [sqlite3_memory_used()] since the high-water mark
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2129
** was last reset.  ^The values returned by [sqlite3_memory_used()] and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2130
** [sqlite3_memory_highwater()] include any overhead
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2131
** added by SQLite in its implementation of [sqlite3_malloc()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2132
** but not overhead added by the any underlying system library
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2133
** routines that [sqlite3_malloc()] may call.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2134
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2135
** ^The memory high-water mark is reset to the current value of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2136
** [sqlite3_memory_used()] if and only if the parameter to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2137
** [sqlite3_memory_highwater()] is true.  ^The value returned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2138
** by [sqlite3_memory_highwater(1)] is the high-water mark
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2139
** prior to the reset.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2140
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2141
SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2142
SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2143
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2144
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2145
** CAPI3REF: Pseudo-Random Number Generator
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2146
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2147
** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2148
** select random [ROWID | ROWIDs] when inserting new records into a table that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2149
** already uses the largest possible [ROWID].  The PRNG is also used for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2150
** the build-in random() and randomblob() SQL functions.  This interface allows
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2151
** applications to access the same PRNG for other purposes.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2152
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2153
** ^A call to this routine stores N bytes of randomness into buffer P.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2154
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2155
** ^The first time this routine is invoked (either internally or by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2156
** the application) the PRNG is seeded using randomness obtained
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2157
** from the xRandomness method of the default [sqlite3_vfs] object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2158
** ^On all subsequent invocations, the pseudo-randomness is generated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2159
** internally and without recourse to the [sqlite3_vfs] xRandomness
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2160
** method.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2161
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2162
SQLITE_API void sqlite3_randomness(int N, void *P);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2163
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2164
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2165
** CAPI3REF: Compile-Time Authorization Callbacks
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2166
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2167
** ^This routine registers an authorizer callback with a particular
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2168
** [database connection], supplied in the first argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2169
** ^The authorizer callback is invoked as SQL statements are being compiled
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2170
** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2171
** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  ^At various
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2172
** points during the compilation process, as logic is being created
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2173
** to perform various actions, the authorizer callback is invoked to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2174
** see if those actions are allowed.  ^The authorizer callback should
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2175
** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2176
** specific action but allow the SQL statement to continue to be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2177
** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2178
** rejected with an error.  ^If the authorizer callback returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2179
** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2180
** then the [sqlite3_prepare_v2()] or equivalent call that triggered
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2181
** the authorizer will fail with an error message.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2182
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2183
** When the callback returns [SQLITE_OK], that means the operation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2184
** requested is ok.  ^When the callback returns [SQLITE_DENY], the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2185
** [sqlite3_prepare_v2()] or equivalent call that triggered the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2186
** authorizer will fail with an error message explaining that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2187
** access is denied. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2188
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2189
** ^The first parameter to the authorizer callback is a copy of the third
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2190
** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2191
** to the callback is an integer [SQLITE_COPY | action code] that specifies
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2192
** the particular action to be authorized. ^The third through sixth parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2193
** to the callback are zero-terminated strings that contain additional
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2194
** details about the action to be authorized.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2195
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2196
** ^If the action code is [SQLITE_READ]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2197
** and the callback returns [SQLITE_IGNORE] then the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2198
** [prepared statement] statement is constructed to substitute
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2199
** a NULL value in place of the table column that would have
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2200
** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2201
** return can be used to deny an untrusted user access to individual
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2202
** columns of a table.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2203
** ^If the action code is [SQLITE_DELETE] and the callback returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2204
** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2205
** [truncate optimization] is disabled and all rows are deleted individually.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2206
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2207
** An authorizer is used when [sqlite3_prepare | preparing]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2208
** SQL statements from an untrusted source, to ensure that the SQL statements
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2209
** do not try to access data they are not allowed to see, or that they do not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2210
** try to execute malicious statements that damage the database.  For
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2211
** example, an application may allow a user to enter arbitrary
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2212
** SQL queries for evaluation by a database.  But the application does
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2213
** not want the user to be able to make arbitrary changes to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2214
** database.  An authorizer could then be put in place while the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2215
** user-entered SQL is being [sqlite3_prepare | prepared] that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2216
** disallows everything except [SELECT] statements.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2217
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2218
** Applications that need to process SQL from untrusted sources
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2219
** might also consider lowering resource limits using [sqlite3_limit()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2220
** and limiting database size using the [max_page_count] [PRAGMA]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2221
** in addition to using an authorizer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2222
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2223
** ^(Only a single authorizer can be in place on a database connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2224
** at a time.  Each call to sqlite3_set_authorizer overrides the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2225
** previous call.)^  ^Disable the authorizer by installing a NULL callback.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2226
** The authorizer is disabled by default.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2227
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2228
** The authorizer callback must not do anything that will modify
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2229
** the database connection that invoked the authorizer callback.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2230
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2231
** database connections for the meaning of "modify" in this paragraph.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2232
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2233
** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2234
** statement might be re-prepared during [sqlite3_step()] due to a 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2235
** schema change.  Hence, the application should ensure that the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2236
** correct authorizer callback remains in place during the [sqlite3_step()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2237
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2238
** ^Note that the authorizer callback is invoked only during
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2239
** [sqlite3_prepare()] or its variants.  Authorization is not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2240
** performed during statement evaluation in [sqlite3_step()], unless
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2241
** as stated in the previous paragraph, sqlite3_step() invokes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2242
** sqlite3_prepare_v2() to reprepare a statement after a schema change.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2243
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2244
SQLITE_API int sqlite3_set_authorizer(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2245
  sqlite3*,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2246
  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2247
  void *pUserData
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2248
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2249
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2250
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2251
** CAPI3REF: Authorizer Return Codes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2252
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2253
** The [sqlite3_set_authorizer | authorizer callback function] must
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2254
** return either [SQLITE_OK] or one of these two constants in order
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2255
** to signal SQLite whether or not the action is permitted.  See the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2256
** [sqlite3_set_authorizer | authorizer documentation] for additional
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2257
** information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2258
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2259
** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2260
** from the [sqlite3_vtab_on_conflict()] interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2261
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2262
#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2263
#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2264
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2265
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2266
** CAPI3REF: Authorizer Action Codes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2267
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2268
** The [sqlite3_set_authorizer()] interface registers a callback function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2269
** that is invoked to authorize certain SQL statement actions.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2270
** second parameter to the callback is an integer code that specifies
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2271
** what action is being authorized.  These are the integer action codes that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2272
** the authorizer callback may be passed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2273
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2274
** These action code values signify what kind of operation is to be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2275
** authorized.  The 3rd and 4th parameters to the authorization
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2276
** callback function will be parameters or NULL depending on which of these
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2277
** codes is used as the second parameter.  ^(The 5th parameter to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2278
** authorizer callback is the name of the database ("main", "temp",
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2279
** etc.) if applicable.)^  ^The 6th parameter to the authorizer callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2280
** is the name of the inner-most trigger or view that is responsible for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2281
** the access attempt or NULL if this access attempt is directly from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2282
** top-level SQL code.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2283
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2284
/******************************************* 3rd ************ 4th ***********/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2285
#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2286
#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2287
#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2288
#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2289
#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2290
#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2291
#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2292
#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2293
#define SQLITE_DELETE                9   /* Table Name      NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2294
#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2295
#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2296
#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2297
#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2298
#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2299
#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2300
#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2301
#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2302
#define SQLITE_INSERT               18   /* Table Name      NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2303
#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2304
#define SQLITE_READ                 20   /* Table Name      Column Name     */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2305
#define SQLITE_SELECT               21   /* NULL            NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2306
#define SQLITE_TRANSACTION          22   /* Operation       NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2307
#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2308
#define SQLITE_ATTACH               24   /* Filename        NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2309
#define SQLITE_DETACH               25   /* Database Name   NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2310
#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2311
#define SQLITE_REINDEX              27   /* Index Name      NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2312
#define SQLITE_ANALYZE              28   /* Table Name      NULL            */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2313
#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2314
#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2315
#define SQLITE_FUNCTION             31   /* NULL            Function Name   */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2316
#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2317
#define SQLITE_COPY                  0   /* No longer used */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2318
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2319
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2320
** CAPI3REF: Tracing And Profiling Functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2321
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2322
** These routines register callback functions that can be used for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2323
** tracing and profiling the execution of SQL statements.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2324
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2325
** ^The callback function registered by sqlite3_trace() is invoked at
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2326
** various times when an SQL statement is being run by [sqlite3_step()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2327
** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2328
** SQL statement text as the statement first begins executing.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2329
** ^(Additional sqlite3_trace() callbacks might occur
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2330
** as each triggered subprogram is entered.  The callbacks for triggers
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2331
** contain a UTF-8 SQL comment that identifies the trigger.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2332
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2333
** ^The callback function registered by sqlite3_profile() is invoked
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2334
** as each SQL statement finishes.  ^The profile callback contains
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2335
** the original statement text and an estimate of wall-clock time
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2336
** of how long that statement took to run.  ^The profile callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2337
** time is in units of nanoseconds, however the current implementation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2338
** is only capable of millisecond resolution so the six least significant
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2339
** digits in the time are meaningless.  Future versions of SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2340
** might provide greater resolution on the profiler callback.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2341
** sqlite3_profile() function is considered experimental and is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2342
** subject to change in future versions of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2343
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2344
SQLITE_API void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2345
SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2346
   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2347
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2348
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2349
** CAPI3REF: Query Progress Callbacks
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2350
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2351
** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2352
** function X to be invoked periodically during long running calls to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2353
** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2354
** database connection D.  An example use for this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2355
** interface is to keep a GUI updated during a large query.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2356
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2357
** ^The parameter P is passed through as the only parameter to the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2358
** callback function X.  ^The parameter N is the number of 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2359
** [virtual machine instructions] that are evaluated between successive
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2360
** invocations of the callback X.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2361
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2362
** ^Only a single progress handler may be defined at one time per
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2363
** [database connection]; setting a new progress handler cancels the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2364
** old one.  ^Setting parameter X to NULL disables the progress handler.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2365
** ^The progress handler is also disabled by setting N to a value less
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2366
** than 1.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2367
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2368
** ^If the progress callback returns non-zero, the operation is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2369
** interrupted.  This feature can be used to implement a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2370
** "Cancel" button on a GUI progress dialog box.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2371
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2372
** The progress handler callback must not do anything that will modify
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2373
** the database connection that invoked the progress handler.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2374
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2375
** database connections for the meaning of "modify" in this paragraph.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2376
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2377
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2378
SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2379
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2380
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2381
** CAPI3REF: Opening A New Database Connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2382
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2383
** ^These routines open an SQLite database file as specified by the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2384
** filename argument. ^The filename argument is interpreted as UTF-8 for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2385
** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2386
** order for sqlite3_open16(). ^(A [database connection] handle is usually
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2387
** returned in *ppDb, even if an error occurs.  The only exception is that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2388
** if SQLite is unable to allocate memory to hold the [sqlite3] object,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2389
** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2390
** object.)^ ^(If the database is opened (and/or created) successfully, then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2391
** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.)^ ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2392
** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2393
** an English language description of the error following a failure of any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2394
** of the sqlite3_open() routines.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2395
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2396
** ^The default encoding for the database will be UTF-8 if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2397
** sqlite3_open() or sqlite3_open_v2() is called and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2398
** UTF-16 in the native byte order if sqlite3_open16() is used.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2399
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2400
** Whether or not an error occurs when it is opened, resources
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2401
** associated with the [database connection] handle should be released by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2402
** passing it to [sqlite3_close()] when it is no longer required.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2403
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2404
** The sqlite3_open_v2() interface works like sqlite3_open()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2405
** except that it accepts two additional parameters for additional control
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2406
** over the new database connection.  ^(The flags parameter to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2407
** sqlite3_open_v2() can take one of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2408
** the following three values, optionally combined with the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2409
** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2410
** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2411
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2412
** <dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2413
** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2414
** <dd>The database is opened in read-only mode.  If the database does not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2415
** already exist, an error is returned.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2416
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2417
** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2418
** <dd>The database is opened for reading and writing if possible, or reading
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2419
** only if the file is write protected by the operating system.  In either
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2420
** case the database must already exist, otherwise an error is returned.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2421
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2422
** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2423
** <dd>The database is opened for reading and writing, and is created if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2424
** it does not already exist. This is the behavior that is always used for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2425
** sqlite3_open() and sqlite3_open16().</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2426
** </dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2427
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2428
** If the 3rd parameter to sqlite3_open_v2() is not one of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2429
** combinations shown above optionally combined with other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2430
** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2431
** then the behavior is undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2432
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2433
** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2434
** opens in the multi-thread [threading mode] as long as the single-thread
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2435
** mode has not been set at compile-time or start-time.  ^If the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2436
** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2437
** in the serialized [threading mode] unless single-thread was
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2438
** previously selected at compile-time or start-time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2439
** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2440
** eligible to use [shared cache mode], regardless of whether or not shared
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2441
** cache is enabled using [sqlite3_enable_shared_cache()].  ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2442
** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2443
** participate in [shared cache mode] even if it is enabled.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2444
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2445
** ^The fourth parameter to sqlite3_open_v2() is the name of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2446
** [sqlite3_vfs] object that defines the operating system interface that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2447
** the new database connection should use.  ^If the fourth parameter is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2448
** a NULL pointer then the default [sqlite3_vfs] object is used.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2449
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2450
** ^If the filename is ":memory:", then a private, temporary in-memory database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2451
** is created for the connection.  ^This in-memory database will vanish when
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2452
** the database connection is closed.  Future versions of SQLite might
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2453
** make use of additional special filenames that begin with the ":" character.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2454
** It is recommended that when a database filename actually does begin with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2455
** a ":" character you should prefix the filename with a pathname such as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2456
** "./" to avoid ambiguity.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2457
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2458
** ^If the filename is an empty string, then a private, temporary
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2459
** on-disk database will be created.  ^This private database will be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2460
** automatically deleted as soon as the database connection is closed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2461
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2462
** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2463
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2464
** ^If [URI filename] interpretation is enabled, and the filename argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2465
** begins with "file:", then the filename is interpreted as a URI. ^URI
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2466
** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2467
** set in the fourth argument to sqlite3_open_v2(), or if it has
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2468
** been enabled globally using the [SQLITE_CONFIG_URI] option with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2469
** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2470
** As of SQLite version 3.7.7, URI filename interpretation is turned off
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2471
** by default, but future releases of SQLite might enable URI filename
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2472
** interpretation by default.  See "[URI filenames]" for additional
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2473
** information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2474
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2475
** URI filenames are parsed according to RFC 3986. ^If the URI contains an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2476
** authority, then it must be either an empty string or the string 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2477
** "localhost". ^If the authority is not an empty string or "localhost", an 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2478
** error is returned to the caller. ^The fragment component of a URI, if 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2479
** present, is ignored.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2480
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2481
** ^SQLite uses the path component of the URI as the name of the disk file
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2482
** which contains the database. ^If the path begins with a '/' character, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2483
** then it is interpreted as an absolute path. ^If the path does not begin 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2484
** with a '/' (meaning that the authority section is omitted from the URI)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2485
** then the path is interpreted as a relative path. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2486
** ^On windows, the first component of an absolute path 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2487
** is a drive specification (e.g. "C:").
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2488
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2489
** [[core URI query parameters]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2490
** The query component of a URI may contain parameters that are interpreted
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2491
** either by SQLite itself, or by a [VFS | custom VFS implementation].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2492
** SQLite interprets the following three query parameters:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2493
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2494
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2495
**   <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2496
**     a VFS object that provides the operating system interface that should
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2497
**     be used to access the database file on disk. ^If this option is set to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2498
**     an empty string the default VFS object is used. ^Specifying an unknown
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2499
**     VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2500
**     present, then the VFS specified by the option takes precedence over
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2501
**     the value passed as the fourth parameter to sqlite3_open_v2().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2502
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2503
**   <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw" or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2504
**     "rwc". Attempting to set it to any other value is an error)^. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2505
**     ^If "ro" is specified, then the database is opened for read-only 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2506
**     access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2507
**     third argument to sqlite3_prepare_v2(). ^If the mode option is set to 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2508
**     "rw", then the database is opened for read-write (but not create) 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2509
**     access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2510
**     been set. ^Value "rwc" is equivalent to setting both 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2511
**     SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If sqlite3_open_v2() is 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2512
**     used, it is an error to specify a value for the mode parameter that is 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2513
**     less restrictive than that specified by the flags passed as the third 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2514
**     parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2515
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2516
**   <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2517
**     "private". ^Setting it to "shared" is equivalent to setting the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2518
**     SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2519
**     sqlite3_open_v2(). ^Setting the cache parameter to "private" is 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2520
**     equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2521
**     ^If sqlite3_open_v2() is used and the "cache" parameter is present in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2522
**     a URI filename, its value overrides any behaviour requested by setting
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2523
**     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2524
** </ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2525
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2526
** ^Specifying an unknown parameter in the query component of a URI is not an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2527
** error.  Future versions of SQLite might understand additional query
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2528
** parameters.  See "[query parameters with special meaning to SQLite]" for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2529
** additional information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2530
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2531
** [[URI filename examples]] <h3>URI filename examples</h3>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2532
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2533
** <table border="1" align=center cellpadding=5>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2534
** <tr><th> URI filenames <th> Results
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2535
** <tr><td> file:data.db <td> 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2536
**          Open the file "data.db" in the current directory.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2537
** <tr><td> file:/home/fred/data.db<br>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2538
**          file:///home/fred/data.db <br> 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2539
**          file://localhost/home/fred/data.db <br> <td> 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2540
**          Open the database file "/home/fred/data.db".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2541
** <tr><td> file://darkstar/home/fred/data.db <td> 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2542
**          An error. "darkstar" is not a recognized authority.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2543
** <tr><td style="white-space:nowrap"> 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2544
**          file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2545
**     <td> Windows only: Open the file "data.db" on fred's desktop on drive
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2546
**          C:. Note that the %20 escaping in this example is not strictly 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2547
**          necessary - space characters can be used literally
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2548
**          in URI filenames.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2549
** <tr><td> file:data.db?mode=ro&cache=private <td> 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2550
**          Open file "data.db" in the current directory for read-only access.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2551
**          Regardless of whether or not shared-cache mode is enabled by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2552
**          default, use a private cache.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2553
** <tr><td> file:/home/fred/data.db?vfs=unix-nolock <td>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2554
**          Open file "/home/fred/data.db". Use the special VFS "unix-nolock".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2555
** <tr><td> file:data.db?mode=readonly <td> 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2556
**          An error. "readonly" is not a valid option for the "mode" parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2557
** </table>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2558
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2559
** ^URI hexadecimal escape sequences (%HH) are supported within the path and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2560
** query components of a URI. A hexadecimal escape sequence consists of a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2561
** percent sign - "%" - followed by exactly two hexadecimal digits 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2562
** specifying an octet value. ^Before the path or query components of a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2563
** URI filename are interpreted, they are encoded using UTF-8 and all 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2564
** hexadecimal escape sequences replaced by a single byte containing the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2565
** corresponding octet. If this process generates an invalid UTF-8 encoding,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2566
** the results are undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2567
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2568
** <b>Note to Windows users:</b>  The encoding used for the filename argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2569
** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2570
** codepage is currently defined.  Filenames containing international
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2571
** characters must be converted to UTF-8 prior to passing them into
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2572
** sqlite3_open() or sqlite3_open_v2().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2573
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2574
SQLITE_API int sqlite3_open(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2575
  const char *filename,   /* Database filename (UTF-8) */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2576
  sqlite3 **ppDb          /* OUT: SQLite db handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2577
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2578
SQLITE_API int sqlite3_open16(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2579
  const void *filename,   /* Database filename (UTF-16) */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2580
  sqlite3 **ppDb          /* OUT: SQLite db handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2581
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2582
SQLITE_API int sqlite3_open_v2(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2583
  const char *filename,   /* Database filename (UTF-8) */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2584
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2585
  int flags,              /* Flags */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2586
  const char *zVfs        /* Name of VFS module to use */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2587
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2588
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2589
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2590
** CAPI3REF: Obtain Values For URI Parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2591
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2592
** This is a utility routine, useful to VFS implementations, that checks
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2593
** to see if a database file was a URI that contained a specific query 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2594
** parameter, and if so obtains the value of the query parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2595
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2596
** The zFilename argument is the filename pointer passed into the xOpen()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2597
** method of a VFS implementation.  The zParam argument is the name of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2598
** query parameter we seek.  This routine returns the value of the zParam
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2599
** parameter if it exists.  If the parameter does not exist, this routine
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2600
** returns a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2601
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2602
** If the zFilename argument to this function is not a pointer that SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2603
** passed into the xOpen VFS method, then the behavior of this routine
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2604
** is undefined and probably undesirable.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2605
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2606
SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2607
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2608
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2609
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2610
** CAPI3REF: Error Codes And Messages
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2611
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2612
** ^The sqlite3_errcode() interface returns the numeric [result code] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2613
** [extended result code] for the most recent failed sqlite3_* API call
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2614
** associated with a [database connection]. If a prior API call failed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2615
** but the most recent API call succeeded, the return value from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2616
** sqlite3_errcode() is undefined.  ^The sqlite3_extended_errcode()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2617
** interface is the same except that it always returns the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2618
** [extended result code] even when extended result codes are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2619
** disabled.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2620
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2621
** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2622
** text that describes the error, as either UTF-8 or UTF-16 respectively.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2623
** ^(Memory to hold the error message string is managed internally.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2624
** The application does not need to worry about freeing the result.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2625
** However, the error string might be overwritten or deallocated by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2626
** subsequent calls to other SQLite interface functions.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2627
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2628
** When the serialized [threading mode] is in use, it might be the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2629
** case that a second error occurs on a separate thread in between
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2630
** the time of the first error and the call to these interfaces.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2631
** When that happens, the second error will be reported since these
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2632
** interfaces always report the most recent result.  To avoid
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2633
** this, each thread can obtain exclusive use of the [database connection] D
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2634
** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2635
** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2636
** all calls to the interfaces listed here are completed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2637
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2638
** If an interface fails with SQLITE_MISUSE, that means the interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2639
** was invoked incorrectly by the application.  In that case, the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2640
** error code and message may or may not be set.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2641
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2642
SQLITE_API int sqlite3_errcode(sqlite3 *db);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2643
SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2644
SQLITE_API const char *sqlite3_errmsg(sqlite3*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2645
SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2646
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2647
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2648
** CAPI3REF: SQL Statement Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2649
** KEYWORDS: {prepared statement} {prepared statements}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2650
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2651
** An instance of this object represents a single SQL statement.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2652
** This object is variously known as a "prepared statement" or a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2653
** "compiled SQL statement" or simply as a "statement".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2654
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2655
** The life of a statement object goes something like this:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2656
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2657
** <ol>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2658
** <li> Create the object using [sqlite3_prepare_v2()] or a related
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2659
**      function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2660
** <li> Bind values to [host parameters] using the sqlite3_bind_*()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2661
**      interfaces.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2662
** <li> Run the SQL by calling [sqlite3_step()] one or more times.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2663
** <li> Reset the statement using [sqlite3_reset()] then go back
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2664
**      to step 2.  Do this zero or more times.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2665
** <li> Destroy the object using [sqlite3_finalize()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2666
** </ol>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2667
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2668
** Refer to documentation on individual methods above for additional
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2669
** information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2670
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2671
typedef struct sqlite3_stmt sqlite3_stmt;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2672
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2673
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2674
** CAPI3REF: Run-time Limits
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2675
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2676
** ^(This interface allows the size of various constructs to be limited
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2677
** on a connection by connection basis.  The first parameter is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2678
** [database connection] whose limit is to be set or queried.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2679
** second parameter is one of the [limit categories] that define a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2680
** class of constructs to be size limited.  The third parameter is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2681
** new limit for that construct.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2682
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2683
** ^If the new limit is a negative number, the limit is unchanged.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2684
** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2685
** [limits | hard upper bound]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2686
** set at compile-time by a C preprocessor macro called
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2687
** [limits | SQLITE_MAX_<i>NAME</i>].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2688
** (The "_LIMIT_" in the name is changed to "_MAX_".))^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2689
** ^Attempts to increase a limit above its hard upper bound are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2690
** silently truncated to the hard upper bound.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2691
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2692
** ^Regardless of whether or not the limit was changed, the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2693
** [sqlite3_limit()] interface returns the prior value of the limit.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2694
** ^Hence, to find the current value of a limit without changing it,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2695
** simply invoke this interface with the third parameter set to -1.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2696
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2697
** Run-time limits are intended for use in applications that manage
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2698
** both their own internal database and also databases that are controlled
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2699
** by untrusted external sources.  An example application might be a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2700
** web browser that has its own databases for storing history and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2701
** separate databases controlled by JavaScript applications downloaded
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2702
** off the Internet.  The internal databases can be given the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2703
** large, default limits.  Databases managed by external sources can
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2704
** be given much smaller limits designed to prevent a denial of service
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2705
** attack.  Developers might also want to use the [sqlite3_set_authorizer()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2706
** interface to further control untrusted SQL.  The size of the database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2707
** created by an untrusted script can be contained using the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2708
** [max_page_count] [PRAGMA].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2709
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2710
** New run-time limit categories may be added in future releases.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2711
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2712
SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2713
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2714
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2715
** CAPI3REF: Run-Time Limit Categories
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2716
** KEYWORDS: {limit category} {*limit categories}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2717
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2718
** These constants define various performance limits
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2719
** that can be lowered at run-time using [sqlite3_limit()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2720
** The synopsis of the meanings of the various limits is shown below.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2721
** Additional information is available at [limits | Limits in SQLite].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2722
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2723
** <dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2724
** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2725
** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2726
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2727
** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2728
** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2729
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2730
** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2731
** <dd>The maximum number of columns in a table definition or in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2732
** result set of a [SELECT] or the maximum number of columns in an index
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2733
** or in an ORDER BY or GROUP BY clause.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2734
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2735
** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2736
** <dd>The maximum depth of the parse tree on any expression.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2737
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2738
** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2739
** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2740
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2741
** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2742
** <dd>The maximum number of instructions in a virtual machine program
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2743
** used to implement an SQL statement.  This limit is not currently
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2744
** enforced, though that might be added in some future release of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2745
** SQLite.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2746
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2747
** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2748
** <dd>The maximum number of arguments on a function.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2749
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2750
** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2751
** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2752
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2753
** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2754
** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2755
** <dd>The maximum length of the pattern argument to the [LIKE] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2756
** [GLOB] operators.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2757
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2758
** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2759
** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2760
** <dd>The maximum index number of any [parameter] in an SQL statement.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2761
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2762
** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2763
** <dd>The maximum depth of recursion for triggers.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2764
** </dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2765
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2766
#define SQLITE_LIMIT_LENGTH                    0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2767
#define SQLITE_LIMIT_SQL_LENGTH                1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2768
#define SQLITE_LIMIT_COLUMN                    2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2769
#define SQLITE_LIMIT_EXPR_DEPTH                3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2770
#define SQLITE_LIMIT_COMPOUND_SELECT           4
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2771
#define SQLITE_LIMIT_VDBE_OP                   5
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2772
#define SQLITE_LIMIT_FUNCTION_ARG              6
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2773
#define SQLITE_LIMIT_ATTACHED                  7
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2774
#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2775
#define SQLITE_LIMIT_VARIABLE_NUMBER           9
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2776
#define SQLITE_LIMIT_TRIGGER_DEPTH            10
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2777
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2778
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2779
** CAPI3REF: Compiling An SQL Statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2780
** KEYWORDS: {SQL statement compiler}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2781
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2782
** To execute an SQL query, it must first be compiled into a byte-code
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2783
** program using one of these routines.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2784
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2785
** The first argument, "db", is a [database connection] obtained from a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2786
** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2787
** [sqlite3_open16()].  The database connection must not have been closed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2788
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2789
** The second argument, "zSql", is the statement to be compiled, encoded
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2790
** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2791
** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2792
** use UTF-16.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2793
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2794
** ^If the nByte argument is less than zero, then zSql is read up to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2795
** first zero terminator. ^If nByte is non-negative, then it is the maximum
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2796
** number of  bytes read from zSql.  ^When nByte is non-negative, the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2797
** zSql string ends at either the first '\000' or '\u0000' character or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2798
** the nByte-th byte, whichever comes first. If the caller knows
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2799
** that the supplied string is nul-terminated, then there is a small
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2800
** performance advantage to be gained by passing an nByte parameter that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2801
** is equal to the number of bytes in the input string <i>including</i>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2802
** the nul-terminator bytes.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2803
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2804
** ^If pzTail is not NULL then *pzTail is made to point to the first byte
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2805
** past the end of the first SQL statement in zSql.  These routines only
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2806
** compile the first statement in zSql, so *pzTail is left pointing to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2807
** what remains uncompiled.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2808
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2809
** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2810
** executed using [sqlite3_step()].  ^If there is an error, *ppStmt is set
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2811
** to NULL.  ^If the input text contains no SQL (if the input is an empty
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2812
** string or a comment) then *ppStmt is set to NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2813
** The calling procedure is responsible for deleting the compiled
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2814
** SQL statement using [sqlite3_finalize()] after it has finished with it.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2815
** ppStmt may not be NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2816
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2817
** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2818
** otherwise an [error code] is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2819
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2820
** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2821
** recommended for all new programs. The two older interfaces are retained
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2822
** for backwards compatibility, but their use is discouraged.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2823
** ^In the "v2" interfaces, the prepared statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2824
** that is returned (the [sqlite3_stmt] object) contains a copy of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2825
** original SQL text. This causes the [sqlite3_step()] interface to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2826
** behave differently in three ways:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2827
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2828
** <ol>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2829
** <li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2830
** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2831
** always used to do, [sqlite3_step()] will automatically recompile the SQL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2832
** statement and try to run it again.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2833
** </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2834
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2835
** <li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2836
** ^When an error occurs, [sqlite3_step()] will return one of the detailed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2837
** [error codes] or [extended error codes].  ^The legacy behavior was that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2838
** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2839
** and the application would have to make a second call to [sqlite3_reset()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2840
** in order to find the underlying cause of the problem. With the "v2" prepare
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2841
** interfaces, the underlying reason for the error is returned immediately.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2842
** </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2843
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2844
** <li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2845
** ^If the specific value bound to [parameter | host parameter] in the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2846
** WHERE clause might influence the choice of query plan for a statement,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2847
** then the statement will be automatically recompiled, as if there had been 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2848
** a schema change, on the first  [sqlite3_step()] call following any change
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2849
** to the [sqlite3_bind_text | bindings] of that [parameter]. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2850
** ^The specific value of WHERE-clause [parameter] might influence the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2851
** choice of query plan if the parameter is the left-hand side of a [LIKE]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2852
** or [GLOB] operator or if the parameter is compared to an indexed column
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2853
** and the [SQLITE_ENABLE_STAT2] compile-time option is enabled.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2854
** the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2855
** </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2856
** </ol>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2857
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2858
SQLITE_API int sqlite3_prepare(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2859
  sqlite3 *db,            /* Database handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2860
  const char *zSql,       /* SQL statement, UTF-8 encoded */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2861
  int nByte,              /* Maximum length of zSql in bytes. */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2862
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2863
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2864
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2865
SQLITE_API int sqlite3_prepare_v2(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2866
  sqlite3 *db,            /* Database handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2867
  const char *zSql,       /* SQL statement, UTF-8 encoded */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2868
  int nByte,              /* Maximum length of zSql in bytes. */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2869
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2870
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2871
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2872
SQLITE_API int sqlite3_prepare16(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2873
  sqlite3 *db,            /* Database handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2874
  const void *zSql,       /* SQL statement, UTF-16 encoded */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2875
  int nByte,              /* Maximum length of zSql in bytes. */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2876
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2877
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2878
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2879
SQLITE_API int sqlite3_prepare16_v2(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2880
  sqlite3 *db,            /* Database handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2881
  const void *zSql,       /* SQL statement, UTF-16 encoded */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2882
  int nByte,              /* Maximum length of zSql in bytes. */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2883
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2884
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2885
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2886
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2887
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2888
** CAPI3REF: Retrieving Statement SQL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2889
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2890
** ^This interface can be used to retrieve a saved copy of the original
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2891
** SQL text used to create a [prepared statement] if that statement was
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2892
** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2893
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2894
SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2895
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2896
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2897
** CAPI3REF: Determine If An SQL Statement Writes The Database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2898
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2899
** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2900
** and only if the [prepared statement] X makes no direct changes to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2901
** the content of the database file.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2902
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2903
** Note that [application-defined SQL functions] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2904
** [virtual tables] might change the database indirectly as a side effect.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2905
** ^(For example, if an application defines a function "eval()" that 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2906
** calls [sqlite3_exec()], then the following SQL statement would
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2907
** change the database file through side-effects:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2908
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2909
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2910
**    SELECT eval('DELETE FROM t1') FROM t2;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2911
** </pre></blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2912
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2913
** But because the [SELECT] statement does not change the database file
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2914
** directly, sqlite3_stmt_readonly() would still return true.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2915
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2916
** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2917
** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2918
** since the statements themselves do not actually modify the database but
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2919
** rather they control the timing of when other statements modify the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2920
** database.  ^The [ATTACH] and [DETACH] statements also cause
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2921
** sqlite3_stmt_readonly() to return true since, while those statements
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2922
** change the configuration of a database connection, they do not make 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2923
** changes to the content of the database files on disk.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2924
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2925
SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2926
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2927
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2928
** CAPI3REF: Dynamically Typed Value Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2929
** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2930
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2931
** SQLite uses the sqlite3_value object to represent all values
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2932
** that can be stored in a database table. SQLite uses dynamic typing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2933
** for the values it stores.  ^Values stored in sqlite3_value objects
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2934
** can be integers, floating point values, strings, BLOBs, or NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2935
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2936
** An sqlite3_value object may be either "protected" or "unprotected".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2937
** Some interfaces require a protected sqlite3_value.  Other interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2938
** will accept either a protected or an unprotected sqlite3_value.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2939
** Every interface that accepts sqlite3_value arguments specifies
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2940
** whether or not it requires a protected sqlite3_value.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2941
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2942
** The terms "protected" and "unprotected" refer to whether or not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2943
** a mutex is held.  An internal mutex is held for a protected
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2944
** sqlite3_value object but no mutex is held for an unprotected
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2945
** sqlite3_value object.  If SQLite is compiled to be single-threaded
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2946
** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2947
** or if SQLite is run in one of reduced mutex modes 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2948
** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2949
** then there is no distinction between protected and unprotected
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2950
** sqlite3_value objects and they can be used interchangeably.  However,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2951
** for maximum code portability it is recommended that applications
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2952
** still make the distinction between protected and unprotected
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2953
** sqlite3_value objects even when not strictly required.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2954
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2955
** ^The sqlite3_value objects that are passed as parameters into the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2956
** implementation of [application-defined SQL functions] are protected.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2957
** ^The sqlite3_value object returned by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2958
** [sqlite3_column_value()] is unprotected.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2959
** Unprotected sqlite3_value objects may only be used with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2960
** [sqlite3_result_value()] and [sqlite3_bind_value()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2961
** The [sqlite3_value_blob | sqlite3_value_type()] family of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2962
** interfaces require protected sqlite3_value objects.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2963
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2964
typedef struct Mem sqlite3_value;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2965
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2966
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2967
** CAPI3REF: SQL Function Context Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2968
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2969
** The context in which an SQL function executes is stored in an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2970
** sqlite3_context object.  ^A pointer to an sqlite3_context object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2971
** is always first parameter to [application-defined SQL functions].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2972
** The application-defined SQL function implementation will pass this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2973
** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2974
** [sqlite3_aggregate_context()], [sqlite3_user_data()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2975
** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2976
** and/or [sqlite3_set_auxdata()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2977
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2978
typedef struct sqlite3_context sqlite3_context;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2979
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2980
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2981
** CAPI3REF: Binding Values To Prepared Statements
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2982
** KEYWORDS: {host parameter} {host parameters} {host parameter name}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2983
** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2984
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2985
** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2986
** literals may be replaced by a [parameter] that matches one of following
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2987
** templates:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2988
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2989
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2990
** <li>  ?
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2991
** <li>  ?NNN
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2992
** <li>  :VVV
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2993
** <li>  @VVV
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2994
** <li>  $VVV
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2995
** </ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2996
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2997
** In the templates above, NNN represents an integer literal,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2998
** and VVV represents an alphanumeric identifier.)^  ^The values of these
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  2999
** parameters (also called "host parameter names" or "SQL parameters")
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3000
** can be set using the sqlite3_bind_*() routines defined here.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3001
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3002
** ^The first argument to the sqlite3_bind_*() routines is always
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3003
** a pointer to the [sqlite3_stmt] object returned from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3004
** [sqlite3_prepare_v2()] or its variants.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3005
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3006
** ^The second argument is the index of the SQL parameter to be set.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3007
** ^The leftmost SQL parameter has an index of 1.  ^When the same named
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3008
** SQL parameter is used more than once, second and subsequent
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3009
** occurrences have the same index as the first occurrence.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3010
** ^The index for named parameters can be looked up using the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3011
** [sqlite3_bind_parameter_index()] API if desired.  ^The index
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3012
** for "?NNN" parameters is the value of NNN.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3013
** ^The NNN value must be between 1 and the [sqlite3_limit()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3014
** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3015
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3016
** ^The third argument is the value to bind to the parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3017
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3018
** ^(In those routines that have a fourth argument, its value is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3019
** number of bytes in the parameter.  To be clear: the value is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3020
** number of <u>bytes</u> in the value, not the number of characters.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3021
** ^If the fourth parameter is negative, the length of the string is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3022
** the number of bytes up to the first zero terminator.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3023
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3024
** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3025
** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3026
** string after SQLite has finished with it.  ^The destructor is called
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3027
** to dispose of the BLOB or string even if the call to sqlite3_bind_blob(),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3028
** sqlite3_bind_text(), or sqlite3_bind_text16() fails.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3029
** ^If the fifth argument is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3030
** the special value [SQLITE_STATIC], then SQLite assumes that the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3031
** information is in static, unmanaged space and does not need to be freed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3032
** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3033
** SQLite makes its own private copy of the data immediately, before
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3034
** the sqlite3_bind_*() routine returns.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3035
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3036
** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3037
** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3038
** (just an integer to hold its size) while it is being processed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3039
** Zeroblobs are intended to serve as placeholders for BLOBs whose
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3040
** content is later written using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3041
** [sqlite3_blob_open | incremental BLOB I/O] routines.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3042
** ^A negative value for the zeroblob results in a zero-length BLOB.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3043
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3044
** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3045
** for the [prepared statement] or with a prepared statement for which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3046
** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3047
** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3048
** routine is passed a [prepared statement] that has been finalized, the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3049
** result is undefined and probably harmful.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3050
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3051
** ^Bindings are not cleared by the [sqlite3_reset()] routine.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3052
** ^Unbound parameters are interpreted as NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3053
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3054
** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3055
** [error code] if anything goes wrong.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3056
** ^[SQLITE_RANGE] is returned if the parameter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3057
** index is out of range.  ^[SQLITE_NOMEM] is returned if malloc() fails.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3058
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3059
** See also: [sqlite3_bind_parameter_count()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3060
** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3061
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3062
SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3063
SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3064
SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3065
SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3066
SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3067
SQLITE_API int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3068
SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3069
SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3070
SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3071
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3072
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3073
** CAPI3REF: Number Of SQL Parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3074
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3075
** ^This routine can be used to find the number of [SQL parameters]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3076
** in a [prepared statement].  SQL parameters are tokens of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3077
** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3078
** placeholders for values that are [sqlite3_bind_blob | bound]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3079
** to the parameters at a later time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3080
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3081
** ^(This routine actually returns the index of the largest (rightmost)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3082
** parameter. For all forms except ?NNN, this will correspond to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3083
** number of unique parameters.  If parameters of the ?NNN form are used,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3084
** there may be gaps in the list.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3085
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3086
** See also: [sqlite3_bind_blob|sqlite3_bind()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3087
** [sqlite3_bind_parameter_name()], and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3088
** [sqlite3_bind_parameter_index()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3089
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3090
SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3091
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3092
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3093
** CAPI3REF: Name Of A Host Parameter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3094
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3095
** ^The sqlite3_bind_parameter_name(P,N) interface returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3096
** the name of the N-th [SQL parameter] in the [prepared statement] P.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3097
** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3098
** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3099
** respectively.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3100
** In other words, the initial ":" or "$" or "@" or "?"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3101
** is included as part of the name.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3102
** ^Parameters of the form "?" without a following integer have no name
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3103
** and are referred to as "nameless" or "anonymous parameters".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3104
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3105
** ^The first host parameter has an index of 1, not 0.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3106
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3107
** ^If the value N is out of range or if the N-th parameter is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3108
** nameless, then NULL is returned.  ^The returned string is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3109
** always in UTF-8 encoding even if the named parameter was
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3110
** originally specified as UTF-16 in [sqlite3_prepare16()] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3111
** [sqlite3_prepare16_v2()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3112
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3113
** See also: [sqlite3_bind_blob|sqlite3_bind()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3114
** [sqlite3_bind_parameter_count()], and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3115
** [sqlite3_bind_parameter_index()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3116
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3117
SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3118
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3119
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3120
** CAPI3REF: Index Of A Parameter With A Given Name
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3121
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3122
** ^Return the index of an SQL parameter given its name.  ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3123
** index value returned is suitable for use as the second
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3124
** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3125
** is returned if no matching parameter is found.  ^The parameter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3126
** name must be given in UTF-8 even if the original statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3127
** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3128
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3129
** See also: [sqlite3_bind_blob|sqlite3_bind()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3130
** [sqlite3_bind_parameter_count()], and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3131
** [sqlite3_bind_parameter_index()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3132
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3133
SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3134
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3135
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3136
** CAPI3REF: Reset All Bindings On A Prepared Statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3137
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3138
** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3139
** the [sqlite3_bind_blob | bindings] on a [prepared statement].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3140
** ^Use this routine to reset all host parameters to NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3141
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3142
SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3143
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3144
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3145
** CAPI3REF: Number Of Columns In A Result Set
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3146
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3147
** ^Return the number of columns in the result set returned by the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3148
** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3149
** statement that does not return data (for example an [UPDATE]).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3150
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3151
** See also: [sqlite3_data_count()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3152
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3153
SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3154
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3155
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3156
** CAPI3REF: Column Names In A Result Set
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3157
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3158
** ^These routines return the name assigned to a particular column
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3159
** in the result set of a [SELECT] statement.  ^The sqlite3_column_name()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3160
** interface returns a pointer to a zero-terminated UTF-8 string
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3161
** and sqlite3_column_name16() returns a pointer to a zero-terminated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3162
** UTF-16 string.  ^The first parameter is the [prepared statement]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3163
** that implements the [SELECT] statement. ^The second parameter is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3164
** column number.  ^The leftmost column is number 0.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3165
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3166
** ^The returned string pointer is valid until either the [prepared statement]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3167
** is destroyed by [sqlite3_finalize()] or until the statement is automatically
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3168
** reprepared by the first call to [sqlite3_step()] for a particular run
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3169
** or until the next call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3170
** sqlite3_column_name() or sqlite3_column_name16() on the same column.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3171
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3172
** ^If sqlite3_malloc() fails during the processing of either routine
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3173
** (for example during a conversion from UTF-8 to UTF-16) then a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3174
** NULL pointer is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3175
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3176
** ^The name of a result column is the value of the "AS" clause for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3177
** that column, if there is an AS clause.  If there is no AS clause
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3178
** then the name of the column is unspecified and may change from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3179
** one release of SQLite to the next.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3180
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3181
SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3182
SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3183
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3184
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3185
** CAPI3REF: Source Of Data In A Query Result
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3186
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3187
** ^These routines provide a means to determine the database, table, and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3188
** table column that is the origin of a particular result column in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3189
** [SELECT] statement.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3190
** ^The name of the database or table or column can be returned as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3191
** either a UTF-8 or UTF-16 string.  ^The _database_ routines return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3192
** the database name, the _table_ routines return the table name, and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3193
** the origin_ routines return the column name.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3194
** ^The returned string is valid until the [prepared statement] is destroyed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3195
** using [sqlite3_finalize()] or until the statement is automatically
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3196
** reprepared by the first call to [sqlite3_step()] for a particular run
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3197
** or until the same information is requested
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3198
** again in a different encoding.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3199
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3200
** ^The names returned are the original un-aliased names of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3201
** database, table, and column.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3202
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3203
** ^The first argument to these interfaces is a [prepared statement].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3204
** ^These functions return information about the Nth result column returned by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3205
** the statement, where N is the second function argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3206
** ^The left-most column is column 0 for these routines.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3207
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3208
** ^If the Nth column returned by the statement is an expression or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3209
** subquery and is not a column value, then all of these functions return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3210
** NULL.  ^These routine might also return NULL if a memory allocation error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3211
** occurs.  ^Otherwise, they return the name of the attached database, table,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3212
** or column that query result column was extracted from.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3213
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3214
** ^As with all other SQLite APIs, those whose names end with "16" return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3215
** UTF-16 encoded strings and the other functions return UTF-8.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3216
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3217
** ^These APIs are only available if the library was compiled with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3218
** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3219
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3220
** If two or more threads call one or more of these routines against the same
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3221
** prepared statement and column at the same time then the results are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3222
** undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3223
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3224
** If two or more threads call one or more
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3225
** [sqlite3_column_database_name | column metadata interfaces]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3226
** for the same [prepared statement] and result column
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3227
** at the same time then the results are undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3228
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3229
SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3230
SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3231
SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3232
SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3233
SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3234
SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3235
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3236
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3237
** CAPI3REF: Declared Datatype Of A Query Result
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3238
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3239
** ^(The first parameter is a [prepared statement].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3240
** If this statement is a [SELECT] statement and the Nth column of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3241
** returned result set of that [SELECT] is a table column (not an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3242
** expression or subquery) then the declared type of the table
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3243
** column is returned.)^  ^If the Nth column of the result set is an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3244
** expression or subquery, then a NULL pointer is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3245
** ^The returned string is always UTF-8 encoded.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3246
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3247
** ^(For example, given the database schema:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3248
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3249
** CREATE TABLE t1(c1 VARIANT);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3250
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3251
** and the following statement to be compiled:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3252
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3253
** SELECT c1 + 1, c1 FROM t1;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3254
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3255
** this routine would return the string "VARIANT" for the second result
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3256
** column (i==1), and a NULL pointer for the first result column (i==0).)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3257
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3258
** ^SQLite uses dynamic run-time typing.  ^So just because a column
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3259
** is declared to contain a particular type does not mean that the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3260
** data stored in that column is of the declared type.  SQLite is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3261
** strongly typed, but the typing is dynamic not static.  ^Type
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3262
** is associated with individual values, not with the containers
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3263
** used to hold those values.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3264
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3265
SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3266
SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3267
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3268
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3269
** CAPI3REF: Evaluate An SQL Statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3270
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3271
** After a [prepared statement] has been prepared using either
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3272
** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3273
** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3274
** must be called one or more times to evaluate the statement.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3275
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3276
** The details of the behavior of the sqlite3_step() interface depend
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3277
** on whether the statement was prepared using the newer "v2" interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3278
** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3279
** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3280
** new "v2" interface is recommended for new applications but the legacy
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3281
** interface will continue to be supported.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3282
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3283
** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3284
** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3285
** ^With the "v2" interface, any of the other [result codes] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3286
** [extended result codes] might be returned as well.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3287
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3288
** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3289
** database locks it needs to do its job.  ^If the statement is a [COMMIT]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3290
** or occurs outside of an explicit transaction, then you can retry the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3291
** statement.  If the statement is not a [COMMIT] and occurs within an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3292
** explicit transaction then you should rollback the transaction before
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3293
** continuing.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3294
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3295
** ^[SQLITE_DONE] means that the statement has finished executing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3296
** successfully.  sqlite3_step() should not be called again on this virtual
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3297
** machine without first calling [sqlite3_reset()] to reset the virtual
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3298
** machine back to its initial state.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3299
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3300
** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3301
** is returned each time a new row of data is ready for processing by the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3302
** caller. The values may be accessed using the [column access functions].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3303
** sqlite3_step() is called again to retrieve the next row of data.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3304
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3305
** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3306
** violation) has occurred.  sqlite3_step() should not be called again on
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3307
** the VM. More information may be found by calling [sqlite3_errmsg()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3308
** ^With the legacy interface, a more specific error code (for example,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3309
** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3310
** can be obtained by calling [sqlite3_reset()] on the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3311
** [prepared statement].  ^In the "v2" interface,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3312
** the more specific error code is returned directly by sqlite3_step().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3313
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3314
** [SQLITE_MISUSE] means that the this routine was called inappropriately.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3315
** Perhaps it was called on a [prepared statement] that has
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3316
** already been [sqlite3_finalize | finalized] or on one that had
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3317
** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3318
** be the case that the same database connection is being used by two or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3319
** more threads at the same moment in time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3320
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3321
** For all versions of SQLite up to and including 3.6.23.1, a call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3322
** [sqlite3_reset()] was required after sqlite3_step() returned anything
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3323
** other than [SQLITE_ROW] before any subsequent invocation of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3324
** sqlite3_step().  Failure to reset the prepared statement using 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3325
** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3326
** sqlite3_step().  But after version 3.6.23.1, sqlite3_step() began
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3327
** calling [sqlite3_reset()] automatically in this circumstance rather
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3328
** than returning [SQLITE_MISUSE].  This is not considered a compatibility
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3329
** break because any application that ever receives an SQLITE_MISUSE error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3330
** is broken by definition.  The [SQLITE_OMIT_AUTORESET] compile-time option
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3331
** can be used to restore the legacy behavior.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3332
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3333
** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3334
** API always returns a generic error code, [SQLITE_ERROR], following any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3335
** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3336
** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3337
** specific [error codes] that better describes the error.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3338
** We admit that this is a goofy design.  The problem has been fixed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3339
** with the "v2" interface.  If you prepare all of your SQL statements
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3340
** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3341
** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3342
** then the more specific [error codes] are returned directly
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3343
** by sqlite3_step().  The use of the "v2" interface is recommended.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3344
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3345
SQLITE_API int sqlite3_step(sqlite3_stmt*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3346
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3347
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3348
** CAPI3REF: Number of columns in a result set
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3349
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3350
** ^The sqlite3_data_count(P) interface returns the number of columns in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3351
** current row of the result set of [prepared statement] P.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3352
** ^If prepared statement P does not have results ready to return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3353
** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3354
** interfaces) then sqlite3_data_count(P) returns 0.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3355
** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3356
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3357
** See also: [sqlite3_column_count()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3358
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3359
SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3360
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3361
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3362
** CAPI3REF: Fundamental Datatypes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3363
** KEYWORDS: SQLITE_TEXT
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3364
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3365
** ^(Every value in SQLite has one of five fundamental datatypes:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3366
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3367
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3368
** <li> 64-bit signed integer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3369
** <li> 64-bit IEEE floating point number
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3370
** <li> string
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3371
** <li> BLOB
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3372
** <li> NULL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3373
** </ul>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3374
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3375
** These constants are codes for each of those types.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3376
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3377
** Note that the SQLITE_TEXT constant was also used in SQLite version 2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3378
** for a completely different meaning.  Software that links against both
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3379
** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3380
** SQLITE_TEXT.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3381
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3382
#define SQLITE_INTEGER  1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3383
#define SQLITE_FLOAT    2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3384
#define SQLITE_BLOB     4
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3385
#define SQLITE_NULL     5
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3386
#ifdef SQLITE_TEXT
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3387
# undef SQLITE_TEXT
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3388
#else
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3389
# define SQLITE_TEXT     3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3390
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3391
#define SQLITE3_TEXT     3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3392
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3393
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3394
** CAPI3REF: Result Values From A Query
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3395
** KEYWORDS: {column access functions}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3396
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3397
** These routines form the "result set" interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3398
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3399
** ^These routines return information about a single column of the current
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3400
** result row of a query.  ^In every case the first argument is a pointer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3401
** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3402
** that was returned from [sqlite3_prepare_v2()] or one of its variants)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3403
** and the second argument is the index of the column for which information
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3404
** should be returned. ^The leftmost column of the result set has the index 0.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3405
** ^The number of columns in the result can be determined using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3406
** [sqlite3_column_count()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3407
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3408
** If the SQL statement does not currently point to a valid row, or if the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3409
** column index is out of range, the result is undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3410
** These routines may only be called when the most recent call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3411
** [sqlite3_step()] has returned [SQLITE_ROW] and neither
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3412
** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3413
** If any of these routines are called after [sqlite3_reset()] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3414
** [sqlite3_finalize()] or after [sqlite3_step()] has returned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3415
** something other than [SQLITE_ROW], the results are undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3416
** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3417
** are called from a different thread while any of these routines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3418
** are pending, then the results are undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3419
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3420
** ^The sqlite3_column_type() routine returns the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3421
** [SQLITE_INTEGER | datatype code] for the initial data type
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3422
** of the result column.  ^The returned value is one of [SQLITE_INTEGER],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3423
** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3424
** returned by sqlite3_column_type() is only meaningful if no type
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3425
** conversions have occurred as described below.  After a type conversion,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3426
** the value returned by sqlite3_column_type() is undefined.  Future
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3427
** versions of SQLite may change the behavior of sqlite3_column_type()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3428
** following a type conversion.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3429
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3430
** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3431
** routine returns the number of bytes in that BLOB or string.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3432
** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3433
** the string to UTF-8 and then returns the number of bytes.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3434
** ^If the result is a numeric value then sqlite3_column_bytes() uses
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3435
** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3436
** the number of bytes in that string.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3437
** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3438
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3439
** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3440
** routine returns the number of bytes in that BLOB or string.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3441
** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3442
** the string to UTF-16 and then returns the number of bytes.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3443
** ^If the result is a numeric value then sqlite3_column_bytes16() uses
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3444
** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3445
** the number of bytes in that string.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3446
** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3447
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3448
** ^The values returned by [sqlite3_column_bytes()] and 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3449
** [sqlite3_column_bytes16()] do not include the zero terminators at the end
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3450
** of the string.  ^For clarity: the values returned by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3451
** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3452
** bytes in the string, not the number of characters.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3453
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3454
** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3455
** even empty strings, are always zero terminated.  ^The return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3456
** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3457
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3458
** ^The object returned by [sqlite3_column_value()] is an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3459
** [unprotected sqlite3_value] object.  An unprotected sqlite3_value object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3460
** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3461
** If the [unprotected sqlite3_value] object returned by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3462
** [sqlite3_column_value()] is used in any other way, including calls
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3463
** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3464
** or [sqlite3_value_bytes()], then the behavior is undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3465
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3466
** These routines attempt to convert the value where appropriate.  ^For
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3467
** example, if the internal representation is FLOAT and a text result
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3468
** is requested, [sqlite3_snprintf()] is used internally to perform the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3469
** conversion automatically.  ^(The following table details the conversions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3470
** that are applied:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3471
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3472
** <blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3473
** <table border="1">
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3474
** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3475
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3476
** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3477
** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3478
** <tr><td>  NULL    <td>   TEXT    <td> Result is NULL pointer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3479
** <tr><td>  NULL    <td>   BLOB    <td> Result is NULL pointer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3480
** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3481
** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3482
** <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3483
** <tr><td>  FLOAT   <td> INTEGER   <td> Convert from float to integer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3484
** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3485
** <tr><td>  FLOAT   <td>   BLOB    <td> Same as FLOAT->TEXT
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3486
** <tr><td>  TEXT    <td> INTEGER   <td> Use atoi()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3487
** <tr><td>  TEXT    <td>  FLOAT    <td> Use atof()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3488
** <tr><td>  TEXT    <td>   BLOB    <td> No change
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3489
** <tr><td>  BLOB    <td> INTEGER   <td> Convert to TEXT then use atoi()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3490
** <tr><td>  BLOB    <td>  FLOAT    <td> Convert to TEXT then use atof()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3491
** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3492
** </table>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3493
** </blockquote>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3494
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3495
** The table above makes reference to standard C library functions atoi()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3496
** and atof().  SQLite does not really use these functions.  It has its
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3497
** own equivalent internal routines.  The atoi() and atof() names are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3498
** used in the table for brevity and because they are familiar to most
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3499
** C programmers.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3500
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3501
** Note that when type conversions occur, pointers returned by prior
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3502
** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3503
** sqlite3_column_text16() may be invalidated.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3504
** Type conversions and pointer invalidations might occur
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3505
** in the following cases:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3506
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3507
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3508
** <li> The initial content is a BLOB and sqlite3_column_text() or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3509
**      sqlite3_column_text16() is called.  A zero-terminator might
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3510
**      need to be added to the string.</li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3511
** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3512
**      sqlite3_column_text16() is called.  The content must be converted
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3513
**      to UTF-16.</li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3514
** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3515
**      sqlite3_column_text() is called.  The content must be converted
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3516
**      to UTF-8.</li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3517
** </ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3518
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3519
** ^Conversions between UTF-16be and UTF-16le are always done in place and do
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3520
** not invalidate a prior pointer, though of course the content of the buffer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3521
** that the prior pointer references will have been modified.  Other kinds
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3522
** of conversion are done in place when it is possible, but sometimes they
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3523
** are not possible and in those cases prior pointers are invalidated.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3524
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3525
** The safest and easiest to remember policy is to invoke these routines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3526
** in one of the following ways:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3527
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3528
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3529
**  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3530
**  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3531
**  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3532
** </ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3533
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3534
** In other words, you should call sqlite3_column_text(),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3535
** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3536
** into the desired format, then invoke sqlite3_column_bytes() or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3537
** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3538
** to sqlite3_column_text() or sqlite3_column_blob() with calls to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3539
** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3540
** with calls to sqlite3_column_bytes().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3541
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3542
** ^The pointers returned are valid until a type conversion occurs as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3543
** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3544
** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3545
** and BLOBs is freed automatically.  Do <b>not</b> pass the pointers returned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3546
** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3547
** [sqlite3_free()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3548
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3549
** ^(If a memory allocation error occurs during the evaluation of any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3550
** of these routines, a default value is returned.  The default value
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3551
** is either the integer 0, the floating point number 0.0, or a NULL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3552
** pointer.  Subsequent calls to [sqlite3_errcode()] will return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3553
** [SQLITE_NOMEM].)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3554
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3555
SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3556
SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3557
SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3558
SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3559
SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3560
SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3561
SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3562
SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3563
SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3564
SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3565
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3566
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3567
** CAPI3REF: Destroy A Prepared Statement Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3568
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3569
** ^The sqlite3_finalize() function is called to delete a [prepared statement].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3570
** ^If the most recent evaluation of the statement encountered no errors
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3571
** or if the statement is never been evaluated, then sqlite3_finalize() returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3572
** SQLITE_OK.  ^If the most recent evaluation of statement S failed, then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3573
** sqlite3_finalize(S) returns the appropriate [error code] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3574
** [extended error code].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3575
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3576
** ^The sqlite3_finalize(S) routine can be called at any point during
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3577
** the life cycle of [prepared statement] S:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3578
** before statement S is ever evaluated, after
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3579
** one or more calls to [sqlite3_reset()], or after any call
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3580
** to [sqlite3_step()] regardless of whether or not the statement has
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3581
** completed execution.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3582
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3583
** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3584
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3585
** The application must finalize every [prepared statement] in order to avoid
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3586
** resource leaks.  It is a grievous error for the application to try to use
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3587
** a prepared statement after it has been finalized.  Any use of a prepared
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3588
** statement after it has been finalized can result in undefined and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3589
** undesirable behavior such as segfaults and heap corruption.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3590
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3591
SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3592
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3593
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3594
** CAPI3REF: Reset A Prepared Statement Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3595
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3596
** The sqlite3_reset() function is called to reset a [prepared statement]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3597
** object back to its initial state, ready to be re-executed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3598
** ^Any SQL statement variables that had values bound to them using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3599
** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3600
** Use [sqlite3_clear_bindings()] to reset the bindings.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3601
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3602
** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3603
** back to the beginning of its program.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3604
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3605
** ^If the most recent call to [sqlite3_step(S)] for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3606
** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3607
** or if [sqlite3_step(S)] has never before been called on S,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3608
** then [sqlite3_reset(S)] returns [SQLITE_OK].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3609
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3610
** ^If the most recent call to [sqlite3_step(S)] for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3611
** [prepared statement] S indicated an error, then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3612
** [sqlite3_reset(S)] returns an appropriate [error code].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3613
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3614
** ^The [sqlite3_reset(S)] interface does not change the values
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3615
** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3616
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3617
SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3618
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3619
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3620
** CAPI3REF: Create Or Redefine SQL Functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3621
** KEYWORDS: {function creation routines}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3622
** KEYWORDS: {application-defined SQL function}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3623
** KEYWORDS: {application-defined SQL functions}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3624
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3625
** ^These functions (collectively known as "function creation routines")
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3626
** are used to add SQL functions or aggregates or to redefine the behavior
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3627
** of existing SQL functions or aggregates.  The only differences between
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3628
** these routines are the text encoding expected for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3629
** the second parameter (the name of the function being created)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3630
** and the presence or absence of a destructor callback for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3631
** the application data pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3632
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3633
** ^The first parameter is the [database connection] to which the SQL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3634
** function is to be added.  ^If an application uses more than one database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3635
** connection then application-defined SQL functions must be added
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3636
** to each database connection separately.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3637
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3638
** ^The second parameter is the name of the SQL function to be created or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3639
** redefined.  ^The length of the name is limited to 255 bytes in a UTF-8
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3640
** representation, exclusive of the zero-terminator.  ^Note that the name
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3641
** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3642
** ^Any attempt to create a function with a longer name
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3643
** will result in [SQLITE_MISUSE] being returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3644
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3645
** ^The third parameter (nArg)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3646
** is the number of arguments that the SQL function or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3647
** aggregate takes. ^If this parameter is -1, then the SQL function or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3648
** aggregate may take any number of arguments between 0 and the limit
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3649
** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]).  If the third
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3650
** parameter is less than -1 or greater than 127 then the behavior is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3651
** undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3652
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3653
** ^The fourth parameter, eTextRep, specifies what
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3654
** [SQLITE_UTF8 | text encoding] this SQL function prefers for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3655
** its parameters.  Every SQL function implementation must be able to work
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3656
** with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3657
** more efficient with one encoding than another.  ^An application may
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3658
** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3659
** times with the same function but with different values of eTextRep.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3660
** ^When multiple implementations of the same function are available, SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3661
** will pick the one that involves the least amount of data conversion.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3662
** If there is only a single implementation which does not care what text
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3663
** encoding is used, then the fourth argument should be [SQLITE_ANY].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3664
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3665
** ^(The fifth parameter is an arbitrary pointer.  The implementation of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3666
** function can gain access to this pointer using [sqlite3_user_data()].)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3667
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3668
** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3669
** pointers to C-language functions that implement the SQL function or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3670
** aggregate. ^A scalar SQL function requires an implementation of the xFunc
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3671
** callback only; NULL pointers must be passed as the xStep and xFinal
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3672
** parameters. ^An aggregate SQL function requires an implementation of xStep
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3673
** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3674
** SQL function or aggregate, pass NULL pointers for all three function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3675
** callbacks.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3676
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3677
** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3678
** then it is destructor for the application data pointer. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3679
** The destructor is invoked when the function is deleted, either by being
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3680
** overloaded or when the database connection closes.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3681
** ^The destructor is also invoked if the call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3682
** sqlite3_create_function_v2() fails.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3683
** ^When the destructor callback of the tenth parameter is invoked, it
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3684
** is passed a single argument which is a copy of the application data 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3685
** pointer which was the fifth parameter to sqlite3_create_function_v2().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3686
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3687
** ^It is permitted to register multiple implementations of the same
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3688
** functions with the same name but with either differing numbers of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3689
** arguments or differing preferred text encodings.  ^SQLite will use
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3690
** the implementation that most closely matches the way in which the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3691
** SQL function is used.  ^A function implementation with a non-negative
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3692
** nArg parameter is a better match than a function implementation with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3693
** a negative nArg.  ^A function where the preferred text encoding
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3694
** matches the database encoding is a better
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3695
** match than a function where the encoding is different.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3696
** ^A function where the encoding difference is between UTF16le and UTF16be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3697
** is a closer match than a function where the encoding difference is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3698
** between UTF8 and UTF16.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3699
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3700
** ^Built-in functions may be overloaded by new application-defined functions.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3701
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3702
** ^An application-defined function is permitted to call other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3703
** SQLite interfaces.  However, such calls must not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3704
** close the database connection nor finalize or reset the prepared
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3705
** statement in which the function is running.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3706
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3707
SQLITE_API int sqlite3_create_function(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3708
  sqlite3 *db,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3709
  const char *zFunctionName,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3710
  int nArg,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3711
  int eTextRep,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3712
  void *pApp,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3713
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3714
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3715
  void (*xFinal)(sqlite3_context*)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3716
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3717
SQLITE_API int sqlite3_create_function16(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3718
  sqlite3 *db,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3719
  const void *zFunctionName,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3720
  int nArg,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3721
  int eTextRep,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3722
  void *pApp,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3723
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3724
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3725
  void (*xFinal)(sqlite3_context*)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3726
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3727
SQLITE_API int sqlite3_create_function_v2(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3728
  sqlite3 *db,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3729
  const char *zFunctionName,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3730
  int nArg,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3731
  int eTextRep,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3732
  void *pApp,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3733
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3734
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3735
  void (*xFinal)(sqlite3_context*),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3736
  void(*xDestroy)(void*)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3737
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3738
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3739
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3740
** CAPI3REF: Text Encodings
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3741
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3742
** These constant define integer codes that represent the various
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3743
** text encodings supported by SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3744
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3745
#define SQLITE_UTF8           1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3746
#define SQLITE_UTF16LE        2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3747
#define SQLITE_UTF16BE        3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3748
#define SQLITE_UTF16          4    /* Use native byte order */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3749
#define SQLITE_ANY            5    /* sqlite3_create_function only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3750
#define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3751
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3752
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3753
** CAPI3REF: Deprecated Functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3754
** DEPRECATED
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3755
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3756
** These functions are [deprecated].  In order to maintain
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3757
** backwards compatibility with older code, these functions continue 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3758
** to be supported.  However, new applications should avoid
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3759
** the use of these functions.  To help encourage people to avoid
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3760
** using these functions, we are not going to tell you what they do.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3761
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3762
#ifndef SQLITE_OMIT_DEPRECATED
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3763
SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3764
SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3765
SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3766
SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3767
SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3768
SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3769
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3770
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3771
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3772
** CAPI3REF: Obtaining SQL Function Parameter Values
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3773
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3774
** The C-language implementation of SQL functions and aggregates uses
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3775
** this set of interface routines to access the parameter values on
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3776
** the function or aggregate.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3777
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3778
** The xFunc (for scalar functions) or xStep (for aggregates) parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3779
** to [sqlite3_create_function()] and [sqlite3_create_function16()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3780
** define callbacks that implement the SQL functions and aggregates.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3781
** The 3rd parameter to these callbacks is an array of pointers to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3782
** [protected sqlite3_value] objects.  There is one [sqlite3_value] object for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3783
** each parameter to the SQL function.  These routines are used to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3784
** extract values from the [sqlite3_value] objects.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3785
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3786
** These routines work only with [protected sqlite3_value] objects.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3787
** Any attempt to use these routines on an [unprotected sqlite3_value]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3788
** object results in undefined behavior.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3789
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3790
** ^These routines work just like the corresponding [column access functions]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3791
** except that  these routines take a single [protected sqlite3_value] object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3792
** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3793
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3794
** ^The sqlite3_value_text16() interface extracts a UTF-16 string
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3795
** in the native byte-order of the host machine.  ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3796
** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3797
** extract UTF-16 strings as big-endian and little-endian respectively.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3798
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3799
** ^(The sqlite3_value_numeric_type() interface attempts to apply
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3800
** numeric affinity to the value.  This means that an attempt is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3801
** made to convert the value to an integer or floating point.  If
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3802
** such a conversion is possible without loss of information (in other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3803
** words, if the value is a string that looks like a number)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3804
** then the conversion is performed.  Otherwise no conversion occurs.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3805
** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3806
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3807
** Please pay particular attention to the fact that the pointer returned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3808
** from [sqlite3_value_blob()], [sqlite3_value_text()], or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3809
** [sqlite3_value_text16()] can be invalidated by a subsequent call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3810
** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3811
** or [sqlite3_value_text16()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3812
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3813
** These routines must be called from the same thread as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3814
** the SQL function that supplied the [sqlite3_value*] parameters.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3815
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3816
SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3817
SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3818
SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3819
SQLITE_API double sqlite3_value_double(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3820
SQLITE_API int sqlite3_value_int(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3821
SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3822
SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3823
SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3824
SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3825
SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3826
SQLITE_API int sqlite3_value_type(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3827
SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3828
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3829
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3830
** CAPI3REF: Obtain Aggregate Function Context
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3831
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3832
** Implementations of aggregate SQL functions use this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3833
** routine to allocate memory for storing their state.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3834
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3835
** ^The first time the sqlite3_aggregate_context(C,N) routine is called 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3836
** for a particular aggregate function, SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3837
** allocates N of memory, zeroes out that memory, and returns a pointer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3838
** to the new memory. ^On second and subsequent calls to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3839
** sqlite3_aggregate_context() for the same aggregate function instance,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3840
** the same buffer is returned.  Sqlite3_aggregate_context() is normally
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3841
** called once for each invocation of the xStep callback and then one
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3842
** last time when the xFinal callback is invoked.  ^(When no rows match
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3843
** an aggregate query, the xStep() callback of the aggregate function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3844
** implementation is never called and xFinal() is called exactly once.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3845
** In those cases, sqlite3_aggregate_context() might be called for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3846
** first time from within xFinal().)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3847
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3848
** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3849
** less than or equal to zero or if a memory allocate error occurs.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3850
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3851
** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3852
** determined by the N parameter on first successful call.  Changing the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3853
** value of N in subsequent call to sqlite3_aggregate_context() within
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3854
** the same aggregate function instance will not resize the memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3855
** allocation.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3856
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3857
** ^SQLite automatically frees the memory allocated by 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3858
** sqlite3_aggregate_context() when the aggregate query concludes.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3859
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3860
** The first parameter must be a copy of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3861
** [sqlite3_context | SQL function context] that is the first parameter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3862
** to the xStep or xFinal callback routine that implements the aggregate
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3863
** function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3864
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3865
** This routine must be called from the same thread in which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3866
** the aggregate SQL function is running.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3867
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3868
SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3869
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3870
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3871
** CAPI3REF: User Data For Functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3872
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3873
** ^The sqlite3_user_data() interface returns a copy of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3874
** the pointer that was the pUserData parameter (the 5th parameter)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3875
** of the [sqlite3_create_function()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3876
** and [sqlite3_create_function16()] routines that originally
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3877
** registered the application defined function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3878
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3879
** This routine must be called from the same thread in which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3880
** the application-defined function is running.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3881
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3882
SQLITE_API void *sqlite3_user_data(sqlite3_context*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3883
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3884
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3885
** CAPI3REF: Database Connection For Functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3886
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3887
** ^The sqlite3_context_db_handle() interface returns a copy of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3888
** the pointer to the [database connection] (the 1st parameter)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3889
** of the [sqlite3_create_function()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3890
** and [sqlite3_create_function16()] routines that originally
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3891
** registered the application defined function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3892
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3893
SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3894
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3895
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3896
** CAPI3REF: Function Auxiliary Data
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3897
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3898
** The following two functions may be used by scalar SQL functions to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3899
** associate metadata with argument values. If the same value is passed to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3900
** multiple invocations of the same SQL function during query execution, under
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3901
** some circumstances the associated metadata may be preserved. This may
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3902
** be used, for example, to add a regular-expression matching scalar
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3903
** function. The compiled version of the regular expression is stored as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3904
** metadata associated with the SQL value passed as the regular expression
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3905
** pattern.  The compiled regular expression can be reused on multiple
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3906
** invocations of the same function so that the original pattern string
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3907
** does not need to be recompiled on each invocation.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3908
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3909
** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3910
** associated by the sqlite3_set_auxdata() function with the Nth argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3911
** value to the application-defined function. ^If no metadata has been ever
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3912
** been set for the Nth argument of the function, or if the corresponding
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3913
** function parameter has changed since the meta-data was set,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3914
** then sqlite3_get_auxdata() returns a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3915
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3916
** ^The sqlite3_set_auxdata() interface saves the metadata
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3917
** pointed to by its 3rd parameter as the metadata for the N-th
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3918
** argument of the application-defined function.  Subsequent
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3919
** calls to sqlite3_get_auxdata() might return this data, if it has
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3920
** not been destroyed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3921
** ^If it is not NULL, SQLite will invoke the destructor
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3922
** function given by the 4th parameter to sqlite3_set_auxdata() on
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3923
** the metadata when the corresponding function parameter changes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3924
** or when the SQL statement completes, whichever comes first.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3925
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3926
** SQLite is free to call the destructor and drop metadata on any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3927
** parameter of any function at any time.  ^The only guarantee is that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3928
** the destructor will be called before the metadata is dropped.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3929
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3930
** ^(In practice, metadata is preserved between function calls for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3931
** expressions that are constant at compile time. This includes literal
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3932
** values and [parameters].)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3933
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3934
** These routines must be called from the same thread in which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3935
** the SQL function is running.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3936
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3937
SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3938
SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3939
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3940
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3941
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3942
** CAPI3REF: Constants Defining Special Destructor Behavior
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3943
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3944
** These are special values for the destructor that is passed in as the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3945
** final argument to routines like [sqlite3_result_blob()].  ^If the destructor
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3946
** argument is SQLITE_STATIC, it means that the content pointer is constant
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3947
** and will never change.  It does not need to be destroyed.  ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3948
** SQLITE_TRANSIENT value means that the content will likely change in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3949
** the near future and that SQLite should make its own private copy of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3950
** the content before returning.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3951
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3952
** The typedef is necessary to work around problems in certain
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3953
** C++ compilers.  See ticket #2191.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3954
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3955
typedef void (*sqlite3_destructor_type)(void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3956
#define SQLITE_STATIC      ((sqlite3_destructor_type)0)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3957
#define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3958
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3959
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3960
** CAPI3REF: Setting The Result Of An SQL Function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3961
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3962
** These routines are used by the xFunc or xFinal callbacks that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3963
** implement SQL functions and aggregates.  See
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3964
** [sqlite3_create_function()] and [sqlite3_create_function16()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3965
** for additional information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3966
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3967
** These functions work very much like the [parameter binding] family of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3968
** functions used to bind values to host parameters in prepared statements.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3969
** Refer to the [SQL parameter] documentation for additional information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3970
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3971
** ^The sqlite3_result_blob() interface sets the result from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3972
** an application-defined function to be the BLOB whose content is pointed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3973
** to by the second parameter and which is N bytes long where N is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3974
** third parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3975
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3976
** ^The sqlite3_result_zeroblob() interfaces set the result of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3977
** the application-defined function to be a BLOB containing all zero
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3978
** bytes and N bytes in size, where N is the value of the 2nd parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3979
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3980
** ^The sqlite3_result_double() interface sets the result from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3981
** an application-defined function to be a floating point value specified
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3982
** by its 2nd argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3983
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3984
** ^The sqlite3_result_error() and sqlite3_result_error16() functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3985
** cause the implemented SQL function to throw an exception.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3986
** ^SQLite uses the string pointed to by the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3987
** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3988
** as the text of an error message.  ^SQLite interprets the error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3989
** message string from sqlite3_result_error() as UTF-8. ^SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3990
** interprets the string from sqlite3_result_error16() as UTF-16 in native
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3991
** byte order.  ^If the third parameter to sqlite3_result_error()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3992
** or sqlite3_result_error16() is negative then SQLite takes as the error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3993
** message all text up through the first zero character.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3994
** ^If the third parameter to sqlite3_result_error() or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3995
** sqlite3_result_error16() is non-negative then SQLite takes that many
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3996
** bytes (not characters) from the 2nd parameter as the error message.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3997
** ^The sqlite3_result_error() and sqlite3_result_error16()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3998
** routines make a private copy of the error message text before
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  3999
** they return.  Hence, the calling function can deallocate or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4000
** modify the text after they return without harm.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4001
** ^The sqlite3_result_error_code() function changes the error code
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4002
** returned by SQLite as a result of an error in a function.  ^By default,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4003
** the error code is SQLITE_ERROR.  ^A subsequent call to sqlite3_result_error()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4004
** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4005
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4006
** ^The sqlite3_result_toobig() interface causes SQLite to throw an error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4007
** indicating that a string or BLOB is too long to represent.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4008
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4009
** ^The sqlite3_result_nomem() interface causes SQLite to throw an error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4010
** indicating that a memory allocation failed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4011
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4012
** ^The sqlite3_result_int() interface sets the return value
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4013
** of the application-defined function to be the 32-bit signed integer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4014
** value given in the 2nd argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4015
** ^The sqlite3_result_int64() interface sets the return value
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4016
** of the application-defined function to be the 64-bit signed integer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4017
** value given in the 2nd argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4018
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4019
** ^The sqlite3_result_null() interface sets the return value
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4020
** of the application-defined function to be NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4021
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4022
** ^The sqlite3_result_text(), sqlite3_result_text16(),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4023
** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4024
** set the return value of the application-defined function to be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4025
** a text string which is represented as UTF-8, UTF-16 native byte order,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4026
** UTF-16 little endian, or UTF-16 big endian, respectively.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4027
** ^SQLite takes the text result from the application from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4028
** the 2nd parameter of the sqlite3_result_text* interfaces.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4029
** ^If the 3rd parameter to the sqlite3_result_text* interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4030
** is negative, then SQLite takes result text from the 2nd parameter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4031
** through the first zero character.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4032
** ^If the 3rd parameter to the sqlite3_result_text* interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4033
** is non-negative, then as many bytes (not characters) of the text
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4034
** pointed to by the 2nd parameter are taken as the application-defined
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4035
** function result.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4036
** ^If the 4th parameter to the sqlite3_result_text* interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4037
** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4038
** function as the destructor on the text or BLOB result when it has
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4039
** finished using that result.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4040
** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4041
** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4042
** assumes that the text or BLOB result is in constant space and does not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4043
** copy the content of the parameter nor call a destructor on the content
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4044
** when it has finished using that result.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4045
** ^If the 4th parameter to the sqlite3_result_text* interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4046
** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4047
** then SQLite makes a copy of the result into space obtained from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4048
** from [sqlite3_malloc()] before it returns.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4049
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4050
** ^The sqlite3_result_value() interface sets the result of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4051
** the application-defined function to be a copy the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4052
** [unprotected sqlite3_value] object specified by the 2nd parameter.  ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4053
** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4054
** so that the [sqlite3_value] specified in the parameter may change or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4055
** be deallocated after sqlite3_result_value() returns without harm.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4056
** ^A [protected sqlite3_value] object may always be used where an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4057
** [unprotected sqlite3_value] object is required, so either
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4058
** kind of [sqlite3_value] object can be used with this interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4059
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4060
** If these routines are called from within the different thread
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4061
** than the one containing the application-defined function that received
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4062
** the [sqlite3_context] pointer, the results are undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4063
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4064
SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4065
SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4066
SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4067
SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4068
SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4069
SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4070
SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4071
SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4072
SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4073
SQLITE_API void sqlite3_result_null(sqlite3_context*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4074
SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4075
SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4076
SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4077
SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4078
SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4079
SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4080
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4081
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4082
** CAPI3REF: Define New Collating Sequences
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4083
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4084
** ^These functions add, remove, or modify a [collation] associated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4085
** with the [database connection] specified as the first argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4086
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4087
** ^The name of the collation is a UTF-8 string
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4088
** for sqlite3_create_collation() and sqlite3_create_collation_v2()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4089
** and a UTF-16 string in native byte order for sqlite3_create_collation16().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4090
** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4091
** considered to be the same name.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4092
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4093
** ^(The third argument (eTextRep) must be one of the constants:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4094
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4095
** <li> [SQLITE_UTF8],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4096
** <li> [SQLITE_UTF16LE],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4097
** <li> [SQLITE_UTF16BE],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4098
** <li> [SQLITE_UTF16], or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4099
** <li> [SQLITE_UTF16_ALIGNED].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4100
** </ul>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4101
** ^The eTextRep argument determines the encoding of strings passed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4102
** to the collating function callback, xCallback.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4103
** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4104
** force strings to be UTF16 with native byte order.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4105
** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4106
** on an even byte address.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4107
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4108
** ^The fourth argument, pArg, is an application data pointer that is passed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4109
** through as the first argument to the collating function callback.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4110
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4111
** ^The fifth argument, xCallback, is a pointer to the collating function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4112
** ^Multiple collating functions can be registered using the same name but
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4113
** with different eTextRep parameters and SQLite will use whichever
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4114
** function requires the least amount of data transformation.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4115
** ^If the xCallback argument is NULL then the collating function is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4116
** deleted.  ^When all collating functions having the same name are deleted,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4117
** that collation is no longer usable.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4118
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4119
** ^The collating function callback is invoked with a copy of the pArg 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4120
** application data pointer and with two strings in the encoding specified
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4121
** by the eTextRep argument.  The collating function must return an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4122
** integer that is negative, zero, or positive
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4123
** if the first string is less than, equal to, or greater than the second,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4124
** respectively.  A collating function must always return the same answer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4125
** given the same inputs.  If two or more collating functions are registered
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4126
** to the same collation name (using different eTextRep values) then all
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4127
** must give an equivalent answer when invoked with equivalent strings.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4128
** The collating function must obey the following properties for all
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4129
** strings A, B, and C:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4130
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4131
** <ol>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4132
** <li> If A==B then B==A.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4133
** <li> If A==B and B==C then A==C.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4134
** <li> If A&lt;B THEN B&gt;A.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4135
** <li> If A&lt;B and B&lt;C then A&lt;C.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4136
** </ol>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4137
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4138
** If a collating function fails any of the above constraints and that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4139
** collating function is  registered and used, then the behavior of SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4140
** is undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4141
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4142
** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4143
** with the addition that the xDestroy callback is invoked on pArg when
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4144
** the collating function is deleted.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4145
** ^Collating functions are deleted when they are overridden by later
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4146
** calls to the collation creation functions or when the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4147
** [database connection] is closed using [sqlite3_close()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4148
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4149
** ^The xDestroy callback is <u>not</u> called if the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4150
** sqlite3_create_collation_v2() function fails.  Applications that invoke
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4151
** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4152
** check the return code and dispose of the application data pointer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4153
** themselves rather than expecting SQLite to deal with it for them.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4154
** This is different from every other SQLite interface.  The inconsistency 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4155
** is unfortunate but cannot be changed without breaking backwards 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4156
** compatibility.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4157
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4158
** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4159
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4160
SQLITE_API int sqlite3_create_collation(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4161
  sqlite3*, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4162
  const char *zName, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4163
  int eTextRep, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4164
  void *pArg,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4165
  int(*xCompare)(void*,int,const void*,int,const void*)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4166
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4167
SQLITE_API int sqlite3_create_collation_v2(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4168
  sqlite3*, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4169
  const char *zName, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4170
  int eTextRep, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4171
  void *pArg,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4172
  int(*xCompare)(void*,int,const void*,int,const void*),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4173
  void(*xDestroy)(void*)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4174
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4175
SQLITE_API int sqlite3_create_collation16(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4176
  sqlite3*, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4177
  const void *zName,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4178
  int eTextRep, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4179
  void *pArg,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4180
  int(*xCompare)(void*,int,const void*,int,const void*)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4181
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4182
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4183
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4184
** CAPI3REF: Collation Needed Callbacks
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4185
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4186
** ^To avoid having to register all collation sequences before a database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4187
** can be used, a single callback function may be registered with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4188
** [database connection] to be invoked whenever an undefined collation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4189
** sequence is required.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4190
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4191
** ^If the function is registered using the sqlite3_collation_needed() API,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4192
** then it is passed the names of undefined collation sequences as strings
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4193
** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4194
** the names are passed as UTF-16 in machine native byte order.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4195
** ^A call to either function replaces the existing collation-needed callback.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4196
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4197
** ^(When the callback is invoked, the first argument passed is a copy
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4198
** of the second argument to sqlite3_collation_needed() or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4199
** sqlite3_collation_needed16().  The second argument is the database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4200
** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4201
** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4202
** sequence function required.  The fourth parameter is the name of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4203
** required collation sequence.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4204
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4205
** The callback function should register the desired collation using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4206
** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4207
** [sqlite3_create_collation_v2()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4208
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4209
SQLITE_API int sqlite3_collation_needed(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4210
  sqlite3*, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4211
  void*, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4212
  void(*)(void*,sqlite3*,int eTextRep,const char*)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4213
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4214
SQLITE_API int sqlite3_collation_needed16(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4215
  sqlite3*, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4216
  void*,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4217
  void(*)(void*,sqlite3*,int eTextRep,const void*)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4218
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4219
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4220
#ifdef SQLITE_HAS_CODEC
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4221
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4222
** Specify the key for an encrypted database.  This routine should be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4223
** called right after sqlite3_open().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4224
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4225
** The code to implement this API is not available in the public release
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4226
** of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4227
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4228
SQLITE_API int sqlite3_key(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4229
  sqlite3 *db,                   /* Database to be rekeyed */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4230
  const void *pKey, int nKey     /* The key */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4231
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4232
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4233
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4234
** Change the key on an open database.  If the current database is not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4235
** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4236
** database is decrypted.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4237
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4238
** The code to implement this API is not available in the public release
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4239
** of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4240
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4241
SQLITE_API int sqlite3_rekey(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4242
  sqlite3 *db,                   /* Database to be rekeyed */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4243
  const void *pKey, int nKey     /* The new key */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4244
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4245
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4246
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4247
** Specify the activation key for a SEE database.  Unless 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4248
** activated, none of the SEE routines will work.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4249
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4250
SQLITE_API void sqlite3_activate_see(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4251
  const char *zPassPhrase        /* Activation phrase */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4252
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4253
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4254
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4255
#ifdef SQLITE_ENABLE_CEROD
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4256
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4257
** Specify the activation key for a CEROD database.  Unless 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4258
** activated, none of the CEROD routines will work.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4259
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4260
SQLITE_API void sqlite3_activate_cerod(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4261
  const char *zPassPhrase        /* Activation phrase */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4262
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4263
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4264
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4265
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4266
** CAPI3REF: Suspend Execution For A Short Time
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4267
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4268
** The sqlite3_sleep() function causes the current thread to suspend execution
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4269
** for at least a number of milliseconds specified in its parameter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4270
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4271
** If the operating system does not support sleep requests with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4272
** millisecond time resolution, then the time will be rounded up to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4273
** the nearest second. The number of milliseconds of sleep actually
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4274
** requested from the operating system is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4275
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4276
** ^SQLite implements this interface by calling the xSleep()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4277
** method of the default [sqlite3_vfs] object.  If the xSleep() method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4278
** of the default VFS is not implemented correctly, or not implemented at
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4279
** all, then the behavior of sqlite3_sleep() may deviate from the description
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4280
** in the previous paragraphs.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4281
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4282
SQLITE_API int sqlite3_sleep(int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4283
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4284
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4285
** CAPI3REF: Name Of The Folder Holding Temporary Files
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4286
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4287
** ^(If this global variable is made to point to a string which is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4288
** the name of a folder (a.k.a. directory), then all temporary files
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4289
** created by SQLite when using a built-in [sqlite3_vfs | VFS]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4290
** will be placed in that directory.)^  ^If this variable
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4291
** is a NULL pointer, then SQLite performs a search for an appropriate
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4292
** temporary file directory.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4293
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4294
** It is not safe to read or modify this variable in more than one
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4295
** thread at a time.  It is not safe to read or modify this variable
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4296
** if a [database connection] is being used at the same time in a separate
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4297
** thread.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4298
** It is intended that this variable be set once
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4299
** as part of process initialization and before any SQLite interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4300
** routines have been called and that this variable remain unchanged
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4301
** thereafter.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4302
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4303
** ^The [temp_store_directory pragma] may modify this variable and cause
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4304
** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4305
** the [temp_store_directory pragma] always assumes that any string
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4306
** that this variable points to is held in memory obtained from 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4307
** [sqlite3_malloc] and the pragma may attempt to free that memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4308
** using [sqlite3_free].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4309
** Hence, if this variable is modified directly, either it should be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4310
** made NULL or made to point to memory obtained from [sqlite3_malloc]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4311
** or else the use of the [temp_store_directory pragma] should be avoided.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4312
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4313
SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4314
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4315
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4316
** CAPI3REF: Test For Auto-Commit Mode
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4317
** KEYWORDS: {autocommit mode}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4318
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4319
** ^The sqlite3_get_autocommit() interface returns non-zero or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4320
** zero if the given database connection is or is not in autocommit mode,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4321
** respectively.  ^Autocommit mode is on by default.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4322
** ^Autocommit mode is disabled by a [BEGIN] statement.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4323
** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4324
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4325
** If certain kinds of errors occur on a statement within a multi-statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4326
** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4327
** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4328
** transaction might be rolled back automatically.  The only way to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4329
** find out whether SQLite automatically rolled back the transaction after
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4330
** an error is to use this function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4331
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4332
** If another thread changes the autocommit status of the database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4333
** connection while this routine is running, then the return value
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4334
** is undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4335
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4336
SQLITE_API int sqlite3_get_autocommit(sqlite3*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4337
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4338
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4339
** CAPI3REF: Find The Database Handle Of A Prepared Statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4340
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4341
** ^The sqlite3_db_handle interface returns the [database connection] handle
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4342
** to which a [prepared statement] belongs.  ^The [database connection]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4343
** returned by sqlite3_db_handle is the same [database connection]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4344
** that was the first argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4345
** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4346
** create the statement in the first place.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4347
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4348
SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4349
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4350
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4351
** CAPI3REF: Find the next prepared statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4352
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4353
** ^This interface returns a pointer to the next [prepared statement] after
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4354
** pStmt associated with the [database connection] pDb.  ^If pStmt is NULL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4355
** then this interface returns a pointer to the first prepared statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4356
** associated with the database connection pDb.  ^If no prepared statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4357
** satisfies the conditions of this routine, it returns NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4358
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4359
** The [database connection] pointer D in a call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4360
** [sqlite3_next_stmt(D,S)] must refer to an open database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4361
** connection and in particular must not be a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4362
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4363
SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4364
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4365
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4366
** CAPI3REF: Commit And Rollback Notification Callbacks
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4367
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4368
** ^The sqlite3_commit_hook() interface registers a callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4369
** function to be invoked whenever a transaction is [COMMIT | committed].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4370
** ^Any callback set by a previous call to sqlite3_commit_hook()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4371
** for the same database connection is overridden.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4372
** ^The sqlite3_rollback_hook() interface registers a callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4373
** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4374
** ^Any callback set by a previous call to sqlite3_rollback_hook()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4375
** for the same database connection is overridden.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4376
** ^The pArg argument is passed through to the callback.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4377
** ^If the callback on a commit hook function returns non-zero,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4378
** then the commit is converted into a rollback.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4379
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4380
** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4381
** return the P argument from the previous call of the same function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4382
** on the same [database connection] D, or NULL for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4383
** the first call for each function on D.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4384
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4385
** The callback implementation must not do anything that will modify
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4386
** the database connection that invoked the callback.  Any actions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4387
** to modify the database connection must be deferred until after the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4388
** completion of the [sqlite3_step()] call that triggered the commit
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4389
** or rollback hook in the first place.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4390
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4391
** database connections for the meaning of "modify" in this paragraph.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4392
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4393
** ^Registering a NULL function disables the callback.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4394
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4395
** ^When the commit hook callback routine returns zero, the [COMMIT]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4396
** operation is allowed to continue normally.  ^If the commit hook
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4397
** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4398
** ^The rollback hook is invoked on a rollback that results from a commit
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4399
** hook returning non-zero, just as it would be with any other rollback.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4400
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4401
** ^For the purposes of this API, a transaction is said to have been
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4402
** rolled back if an explicit "ROLLBACK" statement is executed, or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4403
** an error or constraint causes an implicit rollback to occur.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4404
** ^The rollback callback is not invoked if a transaction is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4405
** automatically rolled back because the database connection is closed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4406
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4407
** See also the [sqlite3_update_hook()] interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4408
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4409
SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4410
SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4411
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4412
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4413
** CAPI3REF: Data Change Notification Callbacks
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4414
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4415
** ^The sqlite3_update_hook() interface registers a callback function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4416
** with the [database connection] identified by the first argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4417
** to be invoked whenever a row is updated, inserted or deleted.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4418
** ^Any callback set by a previous call to this function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4419
** for the same database connection is overridden.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4420
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4421
** ^The second argument is a pointer to the function to invoke when a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4422
** row is updated, inserted or deleted.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4423
** ^The first argument to the callback is a copy of the third argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4424
** to sqlite3_update_hook().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4425
** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4426
** or [SQLITE_UPDATE], depending on the operation that caused the callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4427
** to be invoked.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4428
** ^The third and fourth arguments to the callback contain pointers to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4429
** database and table name containing the affected row.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4430
** ^The final callback parameter is the [rowid] of the row.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4431
** ^In the case of an update, this is the [rowid] after the update takes place.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4432
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4433
** ^(The update hook is not invoked when internal system tables are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4434
** modified (i.e. sqlite_master and sqlite_sequence).)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4435
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4436
** ^In the current implementation, the update hook
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4437
** is not invoked when duplication rows are deleted because of an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4438
** [ON CONFLICT | ON CONFLICT REPLACE] clause.  ^Nor is the update hook
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4439
** invoked when rows are deleted using the [truncate optimization].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4440
** The exceptions defined in this paragraph might change in a future
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4441
** release of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4442
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4443
** The update hook implementation must not do anything that will modify
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4444
** the database connection that invoked the update hook.  Any actions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4445
** to modify the database connection must be deferred until after the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4446
** completion of the [sqlite3_step()] call that triggered the update hook.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4447
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4448
** database connections for the meaning of "modify" in this paragraph.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4449
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4450
** ^The sqlite3_update_hook(D,C,P) function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4451
** returns the P argument from the previous call
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4452
** on the same [database connection] D, or NULL for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4453
** the first call on D.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4454
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4455
** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4456
** interfaces.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4457
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4458
SQLITE_API void *sqlite3_update_hook(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4459
  sqlite3*, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4460
  void(*)(void *,int ,char const *,char const *,sqlite3_int64),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4461
  void*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4462
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4463
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4464
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4465
** CAPI3REF: Enable Or Disable Shared Pager Cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4466
** KEYWORDS: {shared cache}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4467
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4468
** ^(This routine enables or disables the sharing of the database cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4469
** and schema data structures between [database connection | connections]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4470
** to the same database. Sharing is enabled if the argument is true
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4471
** and disabled if the argument is false.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4472
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4473
** ^Cache sharing is enabled and disabled for an entire process.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4474
** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4475
** sharing was enabled or disabled for each thread separately.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4476
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4477
** ^(The cache sharing mode set by this interface effects all subsequent
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4478
** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4479
** Existing database connections continue use the sharing mode
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4480
** that was in effect at the time they were opened.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4481
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4482
** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4483
** successfully.  An [error code] is returned otherwise.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4484
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4485
** ^Shared cache is disabled by default. But this might change in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4486
** future releases of SQLite.  Applications that care about shared
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4487
** cache setting should set it explicitly.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4488
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4489
** See Also:  [SQLite Shared-Cache Mode]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4490
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4491
SQLITE_API int sqlite3_enable_shared_cache(int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4492
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4493
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4494
** CAPI3REF: Attempt To Free Heap Memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4495
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4496
** ^The sqlite3_release_memory() interface attempts to free N bytes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4497
** of heap memory by deallocating non-essential memory allocations
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4498
** held by the database library.   Memory used to cache database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4499
** pages to improve performance is an example of non-essential memory.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4500
** ^sqlite3_release_memory() returns the number of bytes actually freed,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4501
** which might be more or less than the amount requested.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4502
** ^The sqlite3_release_memory() routine is a no-op returning zero
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4503
** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4504
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4505
SQLITE_API int sqlite3_release_memory(int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4506
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4507
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4508
** CAPI3REF: Impose A Limit On Heap Size
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4509
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4510
** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4511
** soft limit on the amount of heap memory that may be allocated by SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4512
** ^SQLite strives to keep heap memory utilization below the soft heap
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4513
** limit by reducing the number of pages held in the page cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4514
** as heap memory usages approaches the limit.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4515
** ^The soft heap limit is "soft" because even though SQLite strives to stay
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4516
** below the limit, it will exceed the limit rather than generate
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4517
** an [SQLITE_NOMEM] error.  In other words, the soft heap limit 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4518
** is advisory only.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4519
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4520
** ^The return value from sqlite3_soft_heap_limit64() is the size of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4521
** the soft heap limit prior to the call.  ^If the argument N is negative
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4522
** then no change is made to the soft heap limit.  Hence, the current
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4523
** size of the soft heap limit can be determined by invoking
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4524
** sqlite3_soft_heap_limit64() with a negative argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4525
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4526
** ^If the argument N is zero then the soft heap limit is disabled.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4527
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4528
** ^(The soft heap limit is not enforced in the current implementation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4529
** if one or more of following conditions are true:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4530
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4531
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4532
** <li> The soft heap limit is set to zero.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4533
** <li> Memory accounting is disabled using a combination of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4534
**      [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4535
**      the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4536
** <li> An alternative page cache implementation is specified using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4537
**      [sqlite3_config]([SQLITE_CONFIG_PCACHE],...).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4538
** <li> The page cache allocates from its own memory pool supplied
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4539
**      by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4540
**      from the heap.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4541
** </ul>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4542
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4543
** Beginning with SQLite version 3.7.3, the soft heap limit is enforced
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4544
** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4545
** compile-time option is invoked.  With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4546
** the soft heap limit is enforced on every memory allocation.  Without
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4547
** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4548
** when memory is allocated by the page cache.  Testing suggests that because
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4549
** the page cache is the predominate memory user in SQLite, most
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4550
** applications will achieve adequate soft heap limit enforcement without
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4551
** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4552
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4553
** The circumstances under which SQLite will enforce the soft heap limit may
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4554
** changes in future releases of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4555
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4556
SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4557
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4558
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4559
** CAPI3REF: Deprecated Soft Heap Limit Interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4560
** DEPRECATED
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4561
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4562
** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4563
** interface.  This routine is provided for historical compatibility
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4564
** only.  All new applications should use the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4565
** [sqlite3_soft_heap_limit64()] interface rather than this one.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4566
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4567
SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4568
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4569
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4570
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4571
** CAPI3REF: Extract Metadata About A Column Of A Table
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4572
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4573
** ^This routine returns metadata about a specific column of a specific
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4574
** database table accessible using the [database connection] handle
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4575
** passed as the first function argument.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4576
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4577
** ^The column is identified by the second, third and fourth parameters to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4578
** this function. ^The second parameter is either the name of the database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4579
** (i.e. "main", "temp", or an attached database) containing the specified
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4580
** table or NULL. ^If it is NULL, then all attached databases are searched
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4581
** for the table using the same algorithm used by the database engine to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4582
** resolve unqualified table references.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4583
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4584
** ^The third and fourth parameters to this function are the table and column
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4585
** name of the desired column, respectively. Neither of these parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4586
** may be NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4587
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4588
** ^Metadata is returned by writing to the memory locations passed as the 5th
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4589
** and subsequent parameters to this function. ^Any of these arguments may be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4590
** NULL, in which case the corresponding element of metadata is omitted.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4591
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4592
** ^(<blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4593
** <table border="1">
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4594
** <tr><th> Parameter <th> Output<br>Type <th>  Description
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4595
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4596
** <tr><td> 5th <td> const char* <td> Data type
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4597
** <tr><td> 6th <td> const char* <td> Name of default collation sequence
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4598
** <tr><td> 7th <td> int         <td> True if column has a NOT NULL constraint
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4599
** <tr><td> 8th <td> int         <td> True if column is part of the PRIMARY KEY
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4600
** <tr><td> 9th <td> int         <td> True if column is [AUTOINCREMENT]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4601
** </table>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4602
** </blockquote>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4603
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4604
** ^The memory pointed to by the character pointers returned for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4605
** declaration type and collation sequence is valid only until the next
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4606
** call to any SQLite API function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4607
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4608
** ^If the specified table is actually a view, an [error code] is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4609
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4610
** ^If the specified column is "rowid", "oid" or "_rowid_" and an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4611
** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4612
** parameters are set for the explicitly declared column. ^(If there is no
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4613
** explicitly declared [INTEGER PRIMARY KEY] column, then the output
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4614
** parameters are set as follows:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4615
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4616
** <pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4617
**     data type: "INTEGER"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4618
**     collation sequence: "BINARY"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4619
**     not null: 0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4620
**     primary key: 1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4621
**     auto increment: 0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4622
** </pre>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4623
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4624
** ^(This function may load one or more schemas from database files. If an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4625
** error occurs during this process, or if the requested table or column
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4626
** cannot be found, an [error code] is returned and an error message left
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4627
** in the [database connection] (to be retrieved using sqlite3_errmsg()).)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4628
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4629
** ^This API is only available if the library was compiled with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4630
** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4631
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4632
SQLITE_API int sqlite3_table_column_metadata(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4633
  sqlite3 *db,                /* Connection handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4634
  const char *zDbName,        /* Database name or NULL */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4635
  const char *zTableName,     /* Table name */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4636
  const char *zColumnName,    /* Column name */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4637
  char const **pzDataType,    /* OUTPUT: Declared data type */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4638
  char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4639
  int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4640
  int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4641
  int *pAutoinc               /* OUTPUT: True if column is auto-increment */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4642
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4643
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4644
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4645
** CAPI3REF: Load An Extension
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4646
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4647
** ^This interface loads an SQLite extension library from the named file.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4648
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4649
** ^The sqlite3_load_extension() interface attempts to load an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4650
** SQLite extension library contained in the file zFile.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4651
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4652
** ^The entry point is zProc.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4653
** ^zProc may be 0, in which case the name of the entry point
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4654
** defaults to "sqlite3_extension_init".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4655
** ^The sqlite3_load_extension() interface returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4656
** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4657
** ^If an error occurs and pzErrMsg is not 0, then the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4658
** [sqlite3_load_extension()] interface shall attempt to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4659
** fill *pzErrMsg with error message text stored in memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4660
** obtained from [sqlite3_malloc()]. The calling function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4661
** should free this memory by calling [sqlite3_free()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4662
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4663
** ^Extension loading must be enabled using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4664
** [sqlite3_enable_load_extension()] prior to calling this API,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4665
** otherwise an error will be returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4666
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4667
** See also the [load_extension() SQL function].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4668
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4669
SQLITE_API int sqlite3_load_extension(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4670
  sqlite3 *db,          /* Load the extension into this database connection */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4671
  const char *zFile,    /* Name of the shared library containing extension */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4672
  const char *zProc,    /* Entry point.  Derived from zFile if 0 */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4673
  char **pzErrMsg       /* Put error message here if not 0 */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4674
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4675
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4676
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4677
** CAPI3REF: Enable Or Disable Extension Loading
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4678
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4679
** ^So as not to open security holes in older applications that are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4680
** unprepared to deal with extension loading, and as a means of disabling
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4681
** extension loading while evaluating user-entered SQL, the following API
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4682
** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4683
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4684
** ^Extension loading is off by default. See ticket #1863.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4685
** ^Call the sqlite3_enable_load_extension() routine with onoff==1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4686
** to turn extension loading on and call it with onoff==0 to turn
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4687
** it back off again.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4688
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4689
SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4690
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4691
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4692
** CAPI3REF: Automatically Load Statically Linked Extensions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4693
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4694
** ^This interface causes the xEntryPoint() function to be invoked for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4695
** each new [database connection] that is created.  The idea here is that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4696
** xEntryPoint() is the entry point for a statically linked SQLite extension
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4697
** that is to be automatically loaded into all new database connections.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4698
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4699
** ^(Even though the function prototype shows that xEntryPoint() takes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4700
** no arguments and returns void, SQLite invokes xEntryPoint() with three
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4701
** arguments and expects and integer result as if the signature of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4702
** entry point where as follows:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4703
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4704
** <blockquote><pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4705
** &nbsp;  int xEntryPoint(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4706
** &nbsp;    sqlite3 *db,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4707
** &nbsp;    const char **pzErrMsg,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4708
** &nbsp;    const struct sqlite3_api_routines *pThunk
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4709
** &nbsp;  );
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4710
** </pre></blockquote>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4711
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4712
** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4713
** point to an appropriate error message (obtained from [sqlite3_mprintf()])
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4714
** and return an appropriate [error code].  ^SQLite ensures that *pzErrMsg
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4715
** is NULL before calling the xEntryPoint().  ^SQLite will invoke
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4716
** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns.  ^If any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4717
** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4718
** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4719
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4720
** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4721
** on the list of automatic extensions is a harmless no-op. ^No entry point
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4722
** will be called more than once for each database connection that is opened.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4723
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4724
** See also: [sqlite3_reset_auto_extension()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4725
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4726
SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4727
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4728
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4729
** CAPI3REF: Reset Automatic Extension Loading
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4730
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4731
** ^This interface disables all automatic extensions previously
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4732
** registered using [sqlite3_auto_extension()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4733
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4734
SQLITE_API void sqlite3_reset_auto_extension(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4735
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4736
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4737
** The interface to the virtual-table mechanism is currently considered
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4738
** to be experimental.  The interface might change in incompatible ways.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4739
** If this is a problem for you, do not use the interface at this time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4740
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4741
** When the virtual-table mechanism stabilizes, we will declare the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4742
** interface fixed, support it indefinitely, and remove this comment.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4743
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4744
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4745
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4746
** Structures used by the virtual table interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4747
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4748
typedef struct sqlite3_vtab sqlite3_vtab;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4749
typedef struct sqlite3_index_info sqlite3_index_info;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4750
typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4751
typedef struct sqlite3_module sqlite3_module;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4752
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4753
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4754
** CAPI3REF: Virtual Table Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4755
** KEYWORDS: sqlite3_module {virtual table module}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4756
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4757
** This structure, sometimes called a "virtual table module", 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4758
** defines the implementation of a [virtual tables].  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4759
** This structure consists mostly of methods for the module.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4760
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4761
** ^A virtual table module is created by filling in a persistent
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4762
** instance of this structure and passing a pointer to that instance
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4763
** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4764
** ^The registration remains valid until it is replaced by a different
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4765
** module or until the [database connection] closes.  The content
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4766
** of this structure must not change while it is registered with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4767
** any database connection.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4768
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4769
struct sqlite3_module {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4770
  int iVersion;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4771
  int (*xCreate)(sqlite3*, void *pAux,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4772
               int argc, const char *const*argv,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4773
               sqlite3_vtab **ppVTab, char**);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4774
  int (*xConnect)(sqlite3*, void *pAux,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4775
               int argc, const char *const*argv,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4776
               sqlite3_vtab **ppVTab, char**);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4777
  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4778
  int (*xDisconnect)(sqlite3_vtab *pVTab);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4779
  int (*xDestroy)(sqlite3_vtab *pVTab);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4780
  int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4781
  int (*xClose)(sqlite3_vtab_cursor*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4782
  int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4783
                int argc, sqlite3_value **argv);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4784
  int (*xNext)(sqlite3_vtab_cursor*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4785
  int (*xEof)(sqlite3_vtab_cursor*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4786
  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4787
  int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4788
  int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4789
  int (*xBegin)(sqlite3_vtab *pVTab);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4790
  int (*xSync)(sqlite3_vtab *pVTab);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4791
  int (*xCommit)(sqlite3_vtab *pVTab);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4792
  int (*xRollback)(sqlite3_vtab *pVTab);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4793
  int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4794
                       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4795
                       void **ppArg);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4796
  int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4797
  /* The methods above are in version 1 of the sqlite_module object. Those 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4798
  ** below are for version 2 and greater. */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4799
  int (*xSavepoint)(sqlite3_vtab *pVTab, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4800
  int (*xRelease)(sqlite3_vtab *pVTab, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4801
  int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4802
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4803
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4804
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4805
** CAPI3REF: Virtual Table Indexing Information
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4806
** KEYWORDS: sqlite3_index_info
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4807
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4808
** The sqlite3_index_info structure and its substructures is used as part
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4809
** of the [virtual table] interface to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4810
** pass information into and receive the reply from the [xBestIndex]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4811
** method of a [virtual table module].  The fields under **Inputs** are the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4812
** inputs to xBestIndex and are read-only.  xBestIndex inserts its
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4813
** results into the **Outputs** fields.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4814
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4815
** ^(The aConstraint[] array records WHERE clause constraints of the form:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4816
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4817
** <blockquote>column OP expr</blockquote>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4818
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4819
** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.)^  ^(The particular operator is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4820
** stored in aConstraint[].op using one of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4821
** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4822
** ^(The index of the column is stored in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4823
** aConstraint[].iColumn.)^  ^(aConstraint[].usable is TRUE if the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4824
** expr on the right-hand side can be evaluated (and thus the constraint
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4825
** is usable) and false if it cannot.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4826
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4827
** ^The optimizer automatically inverts terms of the form "expr OP column"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4828
** and makes other simplifications to the WHERE clause in an attempt to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4829
** get as many WHERE clause terms into the form shown above as possible.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4830
** ^The aConstraint[] array only reports WHERE clause terms that are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4831
** relevant to the particular virtual table being queried.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4832
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4833
** ^Information about the ORDER BY clause is stored in aOrderBy[].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4834
** ^Each term of aOrderBy records a column of the ORDER BY clause.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4835
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4836
** The [xBestIndex] method must fill aConstraintUsage[] with information
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4837
** about what parameters to pass to xFilter.  ^If argvIndex>0 then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4838
** the right-hand side of the corresponding aConstraint[] is evaluated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4839
** and becomes the argvIndex-th entry in argv.  ^(If aConstraintUsage[].omit
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4840
** is true, then the constraint is assumed to be fully handled by the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4841
** virtual table and is not checked again by SQLite.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4842
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4843
** ^The idxNum and idxPtr values are recorded and passed into the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4844
** [xFilter] method.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4845
** ^[sqlite3_free()] is used to free idxPtr if and only if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4846
** needToFreeIdxPtr is true.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4847
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4848
** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4849
** the correct order to satisfy the ORDER BY clause so that no separate
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4850
** sorting step is required.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4851
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4852
** ^The estimatedCost value is an estimate of the cost of doing the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4853
** particular lookup.  A full scan of a table with N entries should have
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4854
** a cost of N.  A binary search of a table of N entries should have a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4855
** cost of approximately log(N).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4856
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4857
struct sqlite3_index_info {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4858
  /* Inputs */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4859
  int nConstraint;           /* Number of entries in aConstraint */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4860
  struct sqlite3_index_constraint {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4861
     int iColumn;              /* Column on left-hand side of constraint */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4862
     unsigned char op;         /* Constraint operator */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4863
     unsigned char usable;     /* True if this constraint is usable */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4864
     int iTermOffset;          /* Used internally - xBestIndex should ignore */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4865
  } *aConstraint;            /* Table of WHERE clause constraints */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4866
  int nOrderBy;              /* Number of terms in the ORDER BY clause */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4867
  struct sqlite3_index_orderby {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4868
     int iColumn;              /* Column number */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4869
     unsigned char desc;       /* True for DESC.  False for ASC. */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4870
  } *aOrderBy;               /* The ORDER BY clause */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4871
  /* Outputs */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4872
  struct sqlite3_index_constraint_usage {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4873
    int argvIndex;           /* if >0, constraint is part of argv to xFilter */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4874
    unsigned char omit;      /* Do not code a test for this constraint */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4875
  } *aConstraintUsage;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4876
  int idxNum;                /* Number used to identify the index */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4877
  char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4878
  int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4879
  int orderByConsumed;       /* True if output is already ordered */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4880
  double estimatedCost;      /* Estimated cost of using this index */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4881
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4882
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4883
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4884
** CAPI3REF: Virtual Table Constraint Operator Codes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4885
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4886
** These macros defined the allowed values for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4887
** [sqlite3_index_info].aConstraint[].op field.  Each value represents
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4888
** an operator that is part of a constraint term in the wHERE clause of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4889
** a query that uses a [virtual table].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4890
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4891
#define SQLITE_INDEX_CONSTRAINT_EQ    2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4892
#define SQLITE_INDEX_CONSTRAINT_GT    4
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4893
#define SQLITE_INDEX_CONSTRAINT_LE    8
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4894
#define SQLITE_INDEX_CONSTRAINT_LT    16
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4895
#define SQLITE_INDEX_CONSTRAINT_GE    32
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4896
#define SQLITE_INDEX_CONSTRAINT_MATCH 64
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4897
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4898
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4899
** CAPI3REF: Register A Virtual Table Implementation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4900
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4901
** ^These routines are used to register a new [virtual table module] name.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4902
** ^Module names must be registered before
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4903
** creating a new [virtual table] using the module and before using a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4904
** preexisting [virtual table] for the module.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4905
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4906
** ^The module name is registered on the [database connection] specified
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4907
** by the first parameter.  ^The name of the module is given by the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4908
** second parameter.  ^The third parameter is a pointer to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4909
** the implementation of the [virtual table module].   ^The fourth
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4910
** parameter is an arbitrary client data pointer that is passed through
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4911
** into the [xCreate] and [xConnect] methods of the virtual table module
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4912
** when a new virtual table is be being created or reinitialized.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4913
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4914
** ^The sqlite3_create_module_v2() interface has a fifth parameter which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4915
** is a pointer to a destructor for the pClientData.  ^SQLite will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4916
** invoke the destructor function (if it is not NULL) when SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4917
** no longer needs the pClientData pointer.  ^The destructor will also
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4918
** be invoked if the call to sqlite3_create_module_v2() fails.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4919
** ^The sqlite3_create_module()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4920
** interface is equivalent to sqlite3_create_module_v2() with a NULL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4921
** destructor.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4922
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4923
SQLITE_API int sqlite3_create_module(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4924
  sqlite3 *db,               /* SQLite connection to register module with */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4925
  const char *zName,         /* Name of the module */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4926
  const sqlite3_module *p,   /* Methods for the module */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4927
  void *pClientData          /* Client data for xCreate/xConnect */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4928
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4929
SQLITE_API int sqlite3_create_module_v2(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4930
  sqlite3 *db,               /* SQLite connection to register module with */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4931
  const char *zName,         /* Name of the module */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4932
  const sqlite3_module *p,   /* Methods for the module */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4933
  void *pClientData,         /* Client data for xCreate/xConnect */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4934
  void(*xDestroy)(void*)     /* Module destructor function */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4935
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4936
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4937
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4938
** CAPI3REF: Virtual Table Instance Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4939
** KEYWORDS: sqlite3_vtab
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4940
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4941
** Every [virtual table module] implementation uses a subclass
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4942
** of this object to describe a particular instance
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4943
** of the [virtual table].  Each subclass will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4944
** be tailored to the specific needs of the module implementation.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4945
** The purpose of this superclass is to define certain fields that are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4946
** common to all module implementations.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4947
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4948
** ^Virtual tables methods can set an error message by assigning a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4949
** string obtained from [sqlite3_mprintf()] to zErrMsg.  The method should
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4950
** take care that any prior string is freed by a call to [sqlite3_free()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4951
** prior to assigning a new string to zErrMsg.  ^After the error message
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4952
** is delivered up to the client application, the string will be automatically
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4953
** freed by sqlite3_free() and the zErrMsg field will be zeroed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4954
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4955
struct sqlite3_vtab {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4956
  const sqlite3_module *pModule;  /* The module for this virtual table */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4957
  int nRef;                       /* NO LONGER USED */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4958
  char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4959
  /* Virtual table implementations will typically add additional fields */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4960
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4961
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4962
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4963
** CAPI3REF: Virtual Table Cursor Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4964
** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4965
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4966
** Every [virtual table module] implementation uses a subclass of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4967
** following structure to describe cursors that point into the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4968
** [virtual table] and are used
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4969
** to loop through the virtual table.  Cursors are created using the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4970
** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4971
** by the [sqlite3_module.xClose | xClose] method.  Cursors are used
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4972
** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4973
** of the module.  Each module implementation will define
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4974
** the content of a cursor structure to suit its own needs.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4975
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4976
** This superclass exists in order to define fields of the cursor that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4977
** are common to all implementations.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4978
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4979
struct sqlite3_vtab_cursor {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4980
  sqlite3_vtab *pVtab;      /* Virtual table of this cursor */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4981
  /* Virtual table implementations will typically add additional fields */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4982
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4983
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4984
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4985
** CAPI3REF: Declare The Schema Of A Virtual Table
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4986
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4987
** ^The [xCreate] and [xConnect] methods of a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4988
** [virtual table module] call this interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4989
** to declare the format (the names and datatypes of the columns) of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4990
** the virtual tables they implement.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4991
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4992
SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4993
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4994
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4995
** CAPI3REF: Overload A Function For A Virtual Table
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4996
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4997
** ^(Virtual tables can provide alternative implementations of functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4998
** using the [xFindFunction] method of the [virtual table module].  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  4999
** But global versions of those functions
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5000
** must exist in order to be overloaded.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5001
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5002
** ^(This API makes sure a global version of a function with a particular
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5003
** name and number of parameters exists.  If no such function exists
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5004
** before this API is called, a new function is created.)^  ^The implementation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5005
** of the new function always causes an exception to be thrown.  So
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5006
** the new function is not good for anything by itself.  Its only
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5007
** purpose is to be a placeholder function that can be overloaded
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5008
** by a [virtual table].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5009
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5010
SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5011
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5012
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5013
** The interface to the virtual-table mechanism defined above (back up
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5014
** to a comment remarkably similar to this one) is currently considered
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5015
** to be experimental.  The interface might change in incompatible ways.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5016
** If this is a problem for you, do not use the interface at this time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5017
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5018
** When the virtual-table mechanism stabilizes, we will declare the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5019
** interface fixed, support it indefinitely, and remove this comment.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5020
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5021
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5022
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5023
** CAPI3REF: A Handle To An Open BLOB
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5024
** KEYWORDS: {BLOB handle} {BLOB handles}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5025
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5026
** An instance of this object represents an open BLOB on which
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5027
** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5028
** ^Objects of this type are created by [sqlite3_blob_open()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5029
** and destroyed by [sqlite3_blob_close()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5030
** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5031
** can be used to read or write small subsections of the BLOB.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5032
** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5033
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5034
typedef struct sqlite3_blob sqlite3_blob;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5035
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5036
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5037
** CAPI3REF: Open A BLOB For Incremental I/O
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5038
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5039
** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5040
** in row iRow, column zColumn, table zTable in database zDb;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5041
** in other words, the same BLOB that would be selected by:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5042
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5043
** <pre>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5044
**     SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5045
** </pre>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5046
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5047
** ^If the flags parameter is non-zero, then the BLOB is opened for read
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5048
** and write access. ^If it is zero, the BLOB is opened for read access.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5049
** ^It is not possible to open a column that is part of an index or primary 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5050
** key for writing. ^If [foreign key constraints] are enabled, it is 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5051
** not possible to open a column that is part of a [child key] for writing.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5052
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5053
** ^Note that the database name is not the filename that contains
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5054
** the database but rather the symbolic name of the database that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5055
** appears after the AS keyword when the database is connected using [ATTACH].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5056
** ^For the main database file, the database name is "main".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5057
** ^For TEMP tables, the database name is "temp".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5058
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5059
** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5060
** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5061
** to be a null pointer.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5062
** ^This function sets the [database connection] error code and message
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5063
** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5064
** functions. ^Note that the *ppBlob variable is always initialized in a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5065
** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5066
** regardless of the success or failure of this routine.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5067
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5068
** ^(If the row that a BLOB handle points to is modified by an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5069
** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5070
** then the BLOB handle is marked as "expired".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5071
** This is true if any column of the row is changed, even a column
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5072
** other than the one the BLOB handle is open on.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5073
** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5074
** an expired BLOB handle fail with a return code of [SQLITE_ABORT].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5075
** ^(Changes written into a BLOB prior to the BLOB expiring are not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5076
** rolled back by the expiration of the BLOB.  Such changes will eventually
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5077
** commit if the transaction continues to completion.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5078
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5079
** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5080
** the opened blob.  ^The size of a blob may not be changed by this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5081
** interface.  Use the [UPDATE] SQL command to change the size of a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5082
** blob.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5083
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5084
** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5085
** and the built-in [zeroblob] SQL function can be used, if desired,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5086
** to create an empty, zero-filled blob in which to read or write using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5087
** this interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5088
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5089
** To avoid a resource leak, every open [BLOB handle] should eventually
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5090
** be released by a call to [sqlite3_blob_close()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5091
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5092
SQLITE_API int sqlite3_blob_open(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5093
  sqlite3*,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5094
  const char *zDb,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5095
  const char *zTable,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5096
  const char *zColumn,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5097
  sqlite3_int64 iRow,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5098
  int flags,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5099
  sqlite3_blob **ppBlob
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5100
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5101
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5102
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5103
** CAPI3REF: Move a BLOB Handle to a New Row
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5104
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5105
** ^This function is used to move an existing blob handle so that it points
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5106
** to a different row of the same database table. ^The new row is identified
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5107
** by the rowid value passed as the second argument. Only the row can be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5108
** changed. ^The database, table and column on which the blob handle is open
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5109
** remain the same. Moving an existing blob handle to a new row can be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5110
** faster than closing the existing handle and opening a new one.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5111
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5112
** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5113
** it must exist and there must be either a blob or text value stored in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5114
** the nominated column.)^ ^If the new row is not present in the table, or if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5115
** it does not contain a blob or text value, or if another error occurs, an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5116
** SQLite error code is returned and the blob handle is considered aborted.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5117
** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5118
** [sqlite3_blob_reopen()] on an aborted blob handle immediately return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5119
** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5120
** always returns zero.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5121
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5122
** ^This function sets the database handle error code and message.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5123
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5124
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5125
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5126
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5127
** CAPI3REF: Close A BLOB Handle
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5128
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5129
** ^Closes an open [BLOB handle].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5130
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5131
** ^Closing a BLOB shall cause the current transaction to commit
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5132
** if there are no other BLOBs, no pending prepared statements, and the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5133
** database connection is in [autocommit mode].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5134
** ^If any writes were made to the BLOB, they might be held in cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5135
** until the close operation if they will fit.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5136
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5137
** ^(Closing the BLOB often forces the changes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5138
** out to disk and so if any I/O errors occur, they will likely occur
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5139
** at the time when the BLOB is closed.  Any errors that occur during
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5140
** closing are reported as a non-zero return value.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5141
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5142
** ^(The BLOB is closed unconditionally.  Even if this routine returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5143
** an error code, the BLOB is still closed.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5144
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5145
** ^Calling this routine with a null pointer (such as would be returned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5146
** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5147
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5148
SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5149
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5150
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5151
** CAPI3REF: Return The Size Of An Open BLOB
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5152
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5153
** ^Returns the size in bytes of the BLOB accessible via the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5154
** successfully opened [BLOB handle] in its only argument.  ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5155
** incremental blob I/O routines can only read or overwriting existing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5156
** blob content; they cannot change the size of a blob.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5157
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5158
** This routine only works on a [BLOB handle] which has been created
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5159
** by a prior successful call to [sqlite3_blob_open()] and which has not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5160
** been closed by [sqlite3_blob_close()].  Passing any other pointer in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5161
** to this routine results in undefined and probably undesirable behavior.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5162
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5163
SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5164
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5165
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5166
** CAPI3REF: Read Data From A BLOB Incrementally
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5167
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5168
** ^(This function is used to read data from an open [BLOB handle] into a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5169
** caller-supplied buffer. N bytes of data are copied into buffer Z
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5170
** from the open BLOB, starting at offset iOffset.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5171
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5172
** ^If offset iOffset is less than N bytes from the end of the BLOB,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5173
** [SQLITE_ERROR] is returned and no data is read.  ^If N or iOffset is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5174
** less than zero, [SQLITE_ERROR] is returned and no data is read.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5175
** ^The size of the blob (and hence the maximum value of N+iOffset)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5176
** can be determined using the [sqlite3_blob_bytes()] interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5177
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5178
** ^An attempt to read from an expired [BLOB handle] fails with an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5179
** error code of [SQLITE_ABORT].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5180
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5181
** ^(On success, sqlite3_blob_read() returns SQLITE_OK.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5182
** Otherwise, an [error code] or an [extended error code] is returned.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5183
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5184
** This routine only works on a [BLOB handle] which has been created
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5185
** by a prior successful call to [sqlite3_blob_open()] and which has not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5186
** been closed by [sqlite3_blob_close()].  Passing any other pointer in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5187
** to this routine results in undefined and probably undesirable behavior.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5188
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5189
** See also: [sqlite3_blob_write()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5190
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5191
SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5192
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5193
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5194
** CAPI3REF: Write Data Into A BLOB Incrementally
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5195
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5196
** ^This function is used to write data into an open [BLOB handle] from a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5197
** caller-supplied buffer. ^N bytes of data are copied from the buffer Z
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5198
** into the open BLOB, starting at offset iOffset.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5199
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5200
** ^If the [BLOB handle] passed as the first argument was not opened for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5201
** writing (the flags parameter to [sqlite3_blob_open()] was zero),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5202
** this function returns [SQLITE_READONLY].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5203
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5204
** ^This function may only modify the contents of the BLOB; it is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5205
** not possible to increase the size of a BLOB using this API.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5206
** ^If offset iOffset is less than N bytes from the end of the BLOB,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5207
** [SQLITE_ERROR] is returned and no data is written.  ^If N is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5208
** less than zero [SQLITE_ERROR] is returned and no data is written.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5209
** The size of the BLOB (and hence the maximum value of N+iOffset)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5210
** can be determined using the [sqlite3_blob_bytes()] interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5211
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5212
** ^An attempt to write to an expired [BLOB handle] fails with an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5213
** error code of [SQLITE_ABORT].  ^Writes to the BLOB that occurred
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5214
** before the [BLOB handle] expired are not rolled back by the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5215
** expiration of the handle, though of course those changes might
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5216
** have been overwritten by the statement that expired the BLOB handle
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5217
** or by other independent statements.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5218
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5219
** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5220
** Otherwise, an  [error code] or an [extended error code] is returned.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5221
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5222
** This routine only works on a [BLOB handle] which has been created
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5223
** by a prior successful call to [sqlite3_blob_open()] and which has not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5224
** been closed by [sqlite3_blob_close()].  Passing any other pointer in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5225
** to this routine results in undefined and probably undesirable behavior.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5226
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5227
** See also: [sqlite3_blob_read()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5228
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5229
SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5230
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5231
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5232
** CAPI3REF: Virtual File System Objects
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5233
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5234
** A virtual filesystem (VFS) is an [sqlite3_vfs] object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5235
** that SQLite uses to interact
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5236
** with the underlying operating system.  Most SQLite builds come with a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5237
** single default VFS that is appropriate for the host computer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5238
** New VFSes can be registered and existing VFSes can be unregistered.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5239
** The following interfaces are provided.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5240
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5241
** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5242
** ^Names are case sensitive.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5243
** ^Names are zero-terminated UTF-8 strings.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5244
** ^If there is no match, a NULL pointer is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5245
** ^If zVfsName is NULL then the default VFS is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5246
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5247
** ^New VFSes are registered with sqlite3_vfs_register().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5248
** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5249
** ^The same VFS can be registered multiple times without injury.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5250
** ^To make an existing VFS into the default VFS, register it again
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5251
** with the makeDflt flag set.  If two different VFSes with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5252
** same name are registered, the behavior is undefined.  If a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5253
** VFS is registered with a name that is NULL or an empty string,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5254
** then the behavior is undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5255
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5256
** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5257
** ^(If the default VFS is unregistered, another VFS is chosen as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5258
** the default.  The choice for the new VFS is arbitrary.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5259
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5260
SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5261
SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5262
SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5263
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5264
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5265
** CAPI3REF: Mutexes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5266
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5267
** The SQLite core uses these routines for thread
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5268
** synchronization. Though they are intended for internal
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5269
** use by SQLite, code that links against SQLite is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5270
** permitted to use any of these routines.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5271
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5272
** The SQLite source code contains multiple implementations
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5273
** of these mutex routines.  An appropriate implementation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5274
** is selected automatically at compile-time.  ^(The following
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5275
** implementations are available in the SQLite core:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5276
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5277
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5278
** <li>   SQLITE_MUTEX_OS2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5279
** <li>   SQLITE_MUTEX_PTHREAD
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5280
** <li>   SQLITE_MUTEX_W32
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5281
** <li>   SQLITE_MUTEX_NOOP
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5282
** </ul>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5283
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5284
** ^The SQLITE_MUTEX_NOOP implementation is a set of routines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5285
** that does no real locking and is appropriate for use in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5286
** a single-threaded application.  ^The SQLITE_MUTEX_OS2,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5287
** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5288
** are appropriate for use on OS/2, Unix, and Windows.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5289
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5290
** ^(If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5291
** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5292
** implementation is included with the library. In this case the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5293
** application must supply a custom mutex implementation using the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5294
** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5295
** before calling sqlite3_initialize() or any other public sqlite3_
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5296
** function that calls sqlite3_initialize().)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5297
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5298
** ^The sqlite3_mutex_alloc() routine allocates a new
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5299
** mutex and returns a pointer to it. ^If it returns NULL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5300
** that means that a mutex could not be allocated.  ^SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5301
** will unwind its stack and return an error.  ^(The argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5302
** to sqlite3_mutex_alloc() is one of these integer constants:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5303
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5304
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5305
** <li>  SQLITE_MUTEX_FAST
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5306
** <li>  SQLITE_MUTEX_RECURSIVE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5307
** <li>  SQLITE_MUTEX_STATIC_MASTER
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5308
** <li>  SQLITE_MUTEX_STATIC_MEM
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5309
** <li>  SQLITE_MUTEX_STATIC_MEM2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5310
** <li>  SQLITE_MUTEX_STATIC_PRNG
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5311
** <li>  SQLITE_MUTEX_STATIC_LRU
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5312
** <li>  SQLITE_MUTEX_STATIC_LRU2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5313
** </ul>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5314
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5315
** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5316
** cause sqlite3_mutex_alloc() to create
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5317
** a new mutex.  ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5318
** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5319
** The mutex implementation does not need to make a distinction
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5320
** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5321
** not want to.  ^SQLite will only request a recursive mutex in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5322
** cases where it really needs one.  ^If a faster non-recursive mutex
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5323
** implementation is available on the host platform, the mutex subsystem
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5324
** might return such a mutex in response to SQLITE_MUTEX_FAST.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5325
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5326
** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5327
** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5328
** a pointer to a static preexisting mutex.  ^Six static mutexes are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5329
** used by the current version of SQLite.  Future versions of SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5330
** may add additional static mutexes.  Static mutexes are for internal
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5331
** use by SQLite only.  Applications that use SQLite mutexes should
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5332
** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5333
** SQLITE_MUTEX_RECURSIVE.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5334
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5335
** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5336
** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5337
** returns a different mutex on every call.  ^But for the static
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5338
** mutex types, the same mutex is returned on every call that has
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5339
** the same type number.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5340
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5341
** ^The sqlite3_mutex_free() routine deallocates a previously
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5342
** allocated dynamic mutex.  ^SQLite is careful to deallocate every
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5343
** dynamic mutex that it allocates.  The dynamic mutexes must not be in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5344
** use when they are deallocated.  Attempting to deallocate a static
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5345
** mutex results in undefined behavior.  ^SQLite never deallocates
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5346
** a static mutex.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5347
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5348
** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5349
** to enter a mutex.  ^If another thread is already within the mutex,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5350
** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5351
** SQLITE_BUSY.  ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5352
** upon successful entry.  ^(Mutexes created using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5353
** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5354
** In such cases the,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5355
** mutex must be exited an equal number of times before another thread
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5356
** can enter.)^  ^(If the same thread tries to enter any other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5357
** kind of mutex more than once, the behavior is undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5358
** SQLite will never exhibit
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5359
** such behavior in its own use of mutexes.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5360
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5361
** ^(Some systems (for example, Windows 95) do not support the operation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5362
** implemented by sqlite3_mutex_try().  On those systems, sqlite3_mutex_try()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5363
** will always return SQLITE_BUSY.  The SQLite core only ever uses
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5364
** sqlite3_mutex_try() as an optimization so this is acceptable behavior.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5365
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5366
** ^The sqlite3_mutex_leave() routine exits a mutex that was
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5367
** previously entered by the same thread.   ^(The behavior
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5368
** is undefined if the mutex is not currently entered by the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5369
** calling thread or is not currently allocated.  SQLite will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5370
** never do either.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5371
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5372
** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5373
** sqlite3_mutex_leave() is a NULL pointer, then all three routines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5374
** behave as no-ops.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5375
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5376
** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5377
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5378
SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5379
SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5380
SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5381
SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5382
SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5383
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5384
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5385
** CAPI3REF: Mutex Methods Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5386
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5387
** An instance of this structure defines the low-level routines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5388
** used to allocate and use mutexes.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5389
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5390
** Usually, the default mutex implementations provided by SQLite are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5391
** sufficient, however the user has the option of substituting a custom
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5392
** implementation for specialized deployments or systems for which SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5393
** does not provide a suitable implementation. In this case, the user
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5394
** creates and populates an instance of this structure to pass
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5395
** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5396
** Additionally, an instance of this structure can be used as an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5397
** output variable when querying the system for the current mutex
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5398
** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5399
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5400
** ^The xMutexInit method defined by this structure is invoked as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5401
** part of system initialization by the sqlite3_initialize() function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5402
** ^The xMutexInit routine is called by SQLite exactly once for each
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5403
** effective call to [sqlite3_initialize()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5404
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5405
** ^The xMutexEnd method defined by this structure is invoked as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5406
** part of system shutdown by the sqlite3_shutdown() function. The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5407
** implementation of this method is expected to release all outstanding
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5408
** resources obtained by the mutex methods implementation, especially
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5409
** those obtained by the xMutexInit method.  ^The xMutexEnd()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5410
** interface is invoked exactly once for each call to [sqlite3_shutdown()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5411
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5412
** ^(The remaining seven methods defined by this structure (xMutexAlloc,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5413
** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5414
** xMutexNotheld) implement the following interfaces (respectively):
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5415
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5416
** <ul>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5417
**   <li>  [sqlite3_mutex_alloc()] </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5418
**   <li>  [sqlite3_mutex_free()] </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5419
**   <li>  [sqlite3_mutex_enter()] </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5420
**   <li>  [sqlite3_mutex_try()] </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5421
**   <li>  [sqlite3_mutex_leave()] </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5422
**   <li>  [sqlite3_mutex_held()] </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5423
**   <li>  [sqlite3_mutex_notheld()] </li>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5424
** </ul>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5425
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5426
** The only difference is that the public sqlite3_XXX functions enumerated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5427
** above silently ignore any invocations that pass a NULL pointer instead
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5428
** of a valid mutex handle. The implementations of the methods defined
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5429
** by this structure are not required to handle this case, the results
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5430
** of passing a NULL pointer instead of a valid mutex handle are undefined
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5431
** (i.e. it is acceptable to provide an implementation that segfaults if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5432
** it is passed a NULL pointer).
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5433
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5434
** The xMutexInit() method must be threadsafe.  ^It must be harmless to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5435
** invoke xMutexInit() multiple times within the same process and without
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5436
** intervening calls to xMutexEnd().  Second and subsequent calls to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5437
** xMutexInit() must be no-ops.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5438
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5439
** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5440
** and its associates).  ^Similarly, xMutexAlloc() must not use SQLite memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5441
** allocation for a static mutex.  ^However xMutexAlloc() may use SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5442
** memory allocation for a fast or recursive mutex.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5443
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5444
** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5445
** called, but only if the prior call to xMutexInit returned SQLITE_OK.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5446
** If xMutexInit fails in any way, it is expected to clean up after itself
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5447
** prior to returning.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5448
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5449
typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5450
struct sqlite3_mutex_methods {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5451
  int (*xMutexInit)(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5452
  int (*xMutexEnd)(void);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5453
  sqlite3_mutex *(*xMutexAlloc)(int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5454
  void (*xMutexFree)(sqlite3_mutex *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5455
  void (*xMutexEnter)(sqlite3_mutex *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5456
  int (*xMutexTry)(sqlite3_mutex *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5457
  void (*xMutexLeave)(sqlite3_mutex *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5458
  int (*xMutexHeld)(sqlite3_mutex *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5459
  int (*xMutexNotheld)(sqlite3_mutex *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5460
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5461
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5462
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5463
** CAPI3REF: Mutex Verification Routines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5464
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5465
** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5466
** are intended for use inside assert() statements.  ^The SQLite core
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5467
** never uses these routines except inside an assert() and applications
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5468
** are advised to follow the lead of the core.  ^The SQLite core only
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5469
** provides implementations for these routines when it is compiled
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5470
** with the SQLITE_DEBUG flag.  ^External mutex implementations
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5471
** are only required to provide these routines if SQLITE_DEBUG is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5472
** defined and if NDEBUG is not defined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5473
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5474
** ^These routines should return true if the mutex in their argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5475
** is held or not held, respectively, by the calling thread.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5476
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5477
** ^The implementation is not required to provided versions of these
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5478
** routines that actually work. If the implementation does not provide working
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5479
** versions of these routines, it should at least provide stubs that always
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5480
** return true so that one does not get spurious assertion failures.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5481
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5482
** ^If the argument to sqlite3_mutex_held() is a NULL pointer then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5483
** the routine should return 1.   This seems counter-intuitive since
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5484
** clearly the mutex cannot be held if it does not exist.  But
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5485
** the reason the mutex does not exist is because the build is not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5486
** using mutexes.  And we do not want the assert() containing the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5487
** call to sqlite3_mutex_held() to fail, so a non-zero return is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5488
** the appropriate thing to do.  ^The sqlite3_mutex_notheld()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5489
** interface should also return 1 when given a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5490
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5491
#ifndef NDEBUG
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5492
SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5493
SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5494
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5495
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5496
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5497
** CAPI3REF: Mutex Types
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5498
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5499
** The [sqlite3_mutex_alloc()] interface takes a single argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5500
** which is one of these integer constants.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5501
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5502
** The set of static mutexes may change from one SQLite release to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5503
** next.  Applications that override the built-in mutex logic must be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5504
** prepared to accommodate additional static mutexes.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5505
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5506
#define SQLITE_MUTEX_FAST             0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5507
#define SQLITE_MUTEX_RECURSIVE        1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5508
#define SQLITE_MUTEX_STATIC_MASTER    2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5509
#define SQLITE_MUTEX_STATIC_MEM       3  /* sqlite3_malloc() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5510
#define SQLITE_MUTEX_STATIC_MEM2      4  /* NOT USED */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5511
#define SQLITE_MUTEX_STATIC_OPEN      4  /* sqlite3BtreeOpen() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5512
#define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_random() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5513
#define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5514
#define SQLITE_MUTEX_STATIC_LRU2      7  /* NOT USED */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5515
#define SQLITE_MUTEX_STATIC_PMEM      7  /* sqlite3PageMalloc() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5516
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5517
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5518
** CAPI3REF: Retrieve the mutex for a database connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5519
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5520
** ^This interface returns a pointer the [sqlite3_mutex] object that 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5521
** serializes access to the [database connection] given in the argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5522
** when the [threading mode] is Serialized.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5523
** ^If the [threading mode] is Single-thread or Multi-thread then this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5524
** routine returns a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5525
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5526
SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5527
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5528
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5529
** CAPI3REF: Low-Level Control Of Database Files
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5530
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5531
** ^The [sqlite3_file_control()] interface makes a direct call to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5532
** xFileControl method for the [sqlite3_io_methods] object associated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5533
** with a particular database identified by the second argument. ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5534
** name of the database is "main" for the main database or "temp" for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5535
** TEMP database, or the name that appears after the AS keyword for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5536
** databases that are added using the [ATTACH] SQL command.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5537
** ^A NULL pointer can be used in place of "main" to refer to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5538
** main database file.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5539
** ^The third and fourth parameters to this routine
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5540
** are passed directly through to the second and third parameters of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5541
** the xFileControl method.  ^The return value of the xFileControl
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5542
** method becomes the return value of this routine.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5543
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5544
** ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5545
** a pointer to the underlying [sqlite3_file] object to be written into
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5546
** the space pointed to by the 4th parameter.  ^The SQLITE_FCNTL_FILE_POINTER
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5547
** case is a short-circuit path which does not actually invoke the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5548
** underlying sqlite3_io_methods.xFileControl method.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5549
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5550
** ^If the second parameter (zDbName) does not match the name of any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5551
** open database file, then SQLITE_ERROR is returned.  ^This error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5552
** code is not remembered and will not be recalled by [sqlite3_errcode()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5553
** or [sqlite3_errmsg()].  The underlying xFileControl method might
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5554
** also return SQLITE_ERROR.  There is no way to distinguish between
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5555
** an incorrect zDbName and an SQLITE_ERROR return from the underlying
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5556
** xFileControl method.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5557
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5558
** See also: [SQLITE_FCNTL_LOCKSTATE]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5559
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5560
SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5561
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5562
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5563
** CAPI3REF: Testing Interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5564
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5565
** ^The sqlite3_test_control() interface is used to read out internal
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5566
** state of SQLite and to inject faults into SQLite for testing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5567
** purposes.  ^The first parameter is an operation code that determines
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5568
** the number, meaning, and operation of all subsequent parameters.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5569
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5570
** This interface is not for use by applications.  It exists solely
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5571
** for verifying the correct operation of the SQLite library.  Depending
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5572
** on how the SQLite library is compiled, this interface might not exist.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5573
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5574
** The details of the operation codes, their meanings, the parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5575
** they take, and what they do are all subject to change without notice.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5576
** Unlike most of the SQLite API, this function is not guaranteed to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5577
** operate consistently from one release to the next.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5578
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5579
SQLITE_API int sqlite3_test_control(int op, ...);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5580
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5581
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5582
** CAPI3REF: Testing Interface Operation Codes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5583
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5584
** These constants are the valid operation code parameters used
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5585
** as the first argument to [sqlite3_test_control()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5586
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5587
** These parameters and their meanings are subject to change
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5588
** without notice.  These values are for testing purposes only.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5589
** Applications should not use any of these parameters or the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5590
** [sqlite3_test_control()] interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5591
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5592
#define SQLITE_TESTCTRL_FIRST                    5
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5593
#define SQLITE_TESTCTRL_PRNG_SAVE                5
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5594
#define SQLITE_TESTCTRL_PRNG_RESTORE             6
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5595
#define SQLITE_TESTCTRL_PRNG_RESET               7
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5596
#define SQLITE_TESTCTRL_BITVEC_TEST              8
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5597
#define SQLITE_TESTCTRL_FAULT_INSTALL            9
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5598
#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5599
#define SQLITE_TESTCTRL_PENDING_BYTE            11
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5600
#define SQLITE_TESTCTRL_ASSERT                  12
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5601
#define SQLITE_TESTCTRL_ALWAYS                  13
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5602
#define SQLITE_TESTCTRL_RESERVE                 14
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5603
#define SQLITE_TESTCTRL_OPTIMIZATIONS           15
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5604
#define SQLITE_TESTCTRL_ISKEYWORD               16
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5605
#define SQLITE_TESTCTRL_PGHDRSZ                 17
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5606
#define SQLITE_TESTCTRL_SCRATCHMALLOC           18
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5607
#define SQLITE_TESTCTRL_LOCALTIME_FAULT         19
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5608
#define SQLITE_TESTCTRL_LAST                    19
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5609
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5610
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5611
** CAPI3REF: SQLite Runtime Status
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5612
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5613
** ^This interface is used to retrieve runtime status information
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5614
** about the performance of SQLite, and optionally to reset various
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5615
** highwater marks.  ^The first argument is an integer code for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5616
** the specific parameter to measure.  ^(Recognized integer codes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5617
** are of the form [status parameters | SQLITE_STATUS_...].)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5618
** ^The current value of the parameter is returned into *pCurrent.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5619
** ^The highest recorded value is returned in *pHighwater.  ^If the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5620
** resetFlag is true, then the highest record value is reset after
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5621
** *pHighwater is written.  ^(Some parameters do not record the highest
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5622
** value.  For those parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5623
** nothing is written into *pHighwater and the resetFlag is ignored.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5624
** ^(Other parameters record only the highwater mark and not the current
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5625
** value.  For these latter parameters nothing is written into *pCurrent.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5626
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5627
** ^The sqlite3_status() routine returns SQLITE_OK on success and a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5628
** non-zero [error code] on failure.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5629
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5630
** This routine is threadsafe but is not atomic.  This routine can be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5631
** called while other threads are running the same or different SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5632
** interfaces.  However the values returned in *pCurrent and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5633
** *pHighwater reflect the status of SQLite at different points in time
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5634
** and it is possible that another thread might change the parameter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5635
** in between the times when *pCurrent and *pHighwater are written.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5636
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5637
** See also: [sqlite3_db_status()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5638
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5639
SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5640
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5641
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5642
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5643
** CAPI3REF: Status Parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5644
** KEYWORDS: {status parameters}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5645
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5646
** These integer constants designate various run-time status parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5647
** that can be returned by [sqlite3_status()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5648
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5649
** <dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5650
** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5651
** <dd>This parameter is the current amount of memory checked out
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5652
** using [sqlite3_malloc()], either directly or indirectly.  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5653
** figure includes calls made to [sqlite3_malloc()] by the application
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5654
** and internal memory usage by the SQLite library.  Scratch memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5655
** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5656
** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5657
** this parameter.  The amount returned is the sum of the allocation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5658
** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5659
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5660
** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5661
** <dd>This parameter records the largest memory allocation request
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5662
** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5663
** internal equivalents).  Only the value returned in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5664
** *pHighwater parameter to [sqlite3_status()] is of interest.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5665
** The value written into the *pCurrent parameter is undefined.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5666
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5667
** [[SQLITE_STATUS_MALLOC_COUNT]] ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5668
** <dd>This parameter records the number of separate memory allocations
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5669
** currently checked out.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5670
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5671
** [[SQLITE_STATUS_PAGECACHE_USED]] ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5672
** <dd>This parameter returns the number of pages used out of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5673
** [pagecache memory allocator] that was configured using 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5674
** [SQLITE_CONFIG_PAGECACHE].  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5675
** value returned is in pages, not in bytes.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5676
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5677
** [[SQLITE_STATUS_PAGECACHE_OVERFLOW]] 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5678
** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5679
** <dd>This parameter returns the number of bytes of page cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5680
** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5681
** buffer and where forced to overflow to [sqlite3_malloc()].  The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5682
** returned value includes allocations that overflowed because they
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5683
** where too large (they were larger than the "sz" parameter to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5684
** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5685
** no space was left in the page cache.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5686
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5687
** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5688
** <dd>This parameter records the largest memory allocation request
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5689
** handed to [pagecache memory allocator].  Only the value returned in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5690
** *pHighwater parameter to [sqlite3_status()] is of interest.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5691
** The value written into the *pCurrent parameter is undefined.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5692
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5693
** [[SQLITE_STATUS_SCRATCH_USED]] ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5694
** <dd>This parameter returns the number of allocations used out of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5695
** [scratch memory allocator] configured using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5696
** [SQLITE_CONFIG_SCRATCH].  The value returned is in allocations, not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5697
** in bytes.  Since a single thread may only have one scratch allocation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5698
** outstanding at time, this parameter also reports the number of threads
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5699
** using scratch memory at the same time.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5700
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5701
** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5702
** <dd>This parameter returns the number of bytes of scratch memory
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5703
** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5704
** buffer and where forced to overflow to [sqlite3_malloc()].  The values
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5705
** returned include overflows because the requested allocation was too
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5706
** larger (that is, because the requested allocation was larger than the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5707
** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5708
** slots were available.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5709
** </dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5710
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5711
** [[SQLITE_STATUS_SCRATCH_SIZE]] ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5712
** <dd>This parameter records the largest memory allocation request
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5713
** handed to [scratch memory allocator].  Only the value returned in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5714
** *pHighwater parameter to [sqlite3_status()] is of interest.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5715
** The value written into the *pCurrent parameter is undefined.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5716
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5717
** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5718
** <dd>This parameter records the deepest parser stack.  It is only
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5719
** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5720
** </dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5721
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5722
** New status parameters may be added from time to time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5723
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5724
#define SQLITE_STATUS_MEMORY_USED          0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5725
#define SQLITE_STATUS_PAGECACHE_USED       1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5726
#define SQLITE_STATUS_PAGECACHE_OVERFLOW   2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5727
#define SQLITE_STATUS_SCRATCH_USED         3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5728
#define SQLITE_STATUS_SCRATCH_OVERFLOW     4
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5729
#define SQLITE_STATUS_MALLOC_SIZE          5
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5730
#define SQLITE_STATUS_PARSER_STACK         6
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5731
#define SQLITE_STATUS_PAGECACHE_SIZE       7
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5732
#define SQLITE_STATUS_SCRATCH_SIZE         8
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5733
#define SQLITE_STATUS_MALLOC_COUNT         9
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5734
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5735
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5736
** CAPI3REF: Database Connection Status
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5737
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5738
** ^This interface is used to retrieve runtime status information 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5739
** about a single [database connection].  ^The first argument is the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5740
** database connection object to be interrogated.  ^The second argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5741
** is an integer constant, taken from the set of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5742
** [SQLITE_DBSTATUS options], that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5743
** determines the parameter to interrogate.  The set of 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5744
** [SQLITE_DBSTATUS options] is likely
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5745
** to grow in future releases of SQLite.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5746
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5747
** ^The current value of the requested parameter is written into *pCur
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5748
** and the highest instantaneous value is written into *pHiwtr.  ^If
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5749
** the resetFlg is true, then the highest instantaneous value is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5750
** reset back down to the current value.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5751
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5752
** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5753
** non-zero [error code] on failure.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5754
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5755
** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5756
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5757
SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5758
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5759
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5760
** CAPI3REF: Status Parameters for database connections
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5761
** KEYWORDS: {SQLITE_DBSTATUS options}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5762
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5763
** These constants are the available integer "verbs" that can be passed as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5764
** the second argument to the [sqlite3_db_status()] interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5765
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5766
** New verbs may be added in future releases of SQLite. Existing verbs
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5767
** might be discontinued. Applications should check the return code from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5768
** [sqlite3_db_status()] to make sure that the call worked.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5769
** The [sqlite3_db_status()] interface will return a non-zero error code
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5770
** if a discontinued or unsupported verb is invoked.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5771
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5772
** <dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5773
** [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5774
** <dd>This parameter returns the number of lookaside memory slots currently
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5775
** checked out.</dd>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5776
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5777
** [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5778
** <dd>This parameter returns the number malloc attempts that were 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5779
** satisfied using lookaside memory. Only the high-water value is meaningful;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5780
** the current value is always zero.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5781
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5782
** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5783
** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5784
** <dd>This parameter returns the number malloc attempts that might have
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5785
** been satisfied using lookaside memory but failed due to the amount of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5786
** memory requested being larger than the lookaside slot size.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5787
** Only the high-water value is meaningful;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5788
** the current value is always zero.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5789
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5790
** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5791
** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5792
** <dd>This parameter returns the number malloc attempts that might have
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5793
** been satisfied using lookaside memory but failed due to all lookaside
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5794
** memory already being in use.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5795
** Only the high-water value is meaningful;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5796
** the current value is always zero.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5797
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5798
** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5799
** <dd>This parameter returns the approximate number of of bytes of heap
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5800
** memory used by all pager caches associated with the database connection.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5801
** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5802
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5803
** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5804
** <dd>This parameter returns the approximate number of of bytes of heap
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5805
** memory used to store the schema for all databases associated
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5806
** with the connection - main, temp, and any [ATTACH]-ed databases.)^ 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5807
** ^The full amount of memory used by the schemas is reported, even if the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5808
** schema memory is shared with other database connections due to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5809
** [shared cache mode] being enabled.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5810
** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5811
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5812
** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5813
** <dd>This parameter returns the approximate number of of bytes of heap
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5814
** and lookaside memory used by all prepared statements associated with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5815
** the database connection.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5816
** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5817
** </dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5818
** </dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5819
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5820
#define SQLITE_DBSTATUS_LOOKASIDE_USED       0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5821
#define SQLITE_DBSTATUS_CACHE_USED           1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5822
#define SQLITE_DBSTATUS_SCHEMA_USED          2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5823
#define SQLITE_DBSTATUS_STMT_USED            3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5824
#define SQLITE_DBSTATUS_LOOKASIDE_HIT        4
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5825
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE  5
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5826
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL  6
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5827
#define SQLITE_DBSTATUS_MAX                  6   /* Largest defined DBSTATUS */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5828
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5829
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5830
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5831
** CAPI3REF: Prepared Statement Status
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5832
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5833
** ^(Each prepared statement maintains various
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5834
** [SQLITE_STMTSTATUS counters] that measure the number
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5835
** of times it has performed specific operations.)^  These counters can
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5836
** be used to monitor the performance characteristics of the prepared
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5837
** statements.  For example, if the number of table steps greatly exceeds
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5838
** the number of table searches or result rows, that would tend to indicate
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5839
** that the prepared statement is using a full table scan rather than
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5840
** an index.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5841
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5842
** ^(This interface is used to retrieve and reset counter values from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5843
** a [prepared statement].  The first argument is the prepared statement
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5844
** object to be interrogated.  The second argument
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5845
** is an integer code for a specific [SQLITE_STMTSTATUS counter]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5846
** to be interrogated.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5847
** ^The current value of the requested counter is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5848
** ^If the resetFlg is true, then the counter is reset to zero after this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5849
** interface call returns.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5850
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5851
** See also: [sqlite3_status()] and [sqlite3_db_status()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5852
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5853
SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5854
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5855
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5856
** CAPI3REF: Status Parameters for prepared statements
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5857
** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5858
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5859
** These preprocessor macros define integer codes that name counter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5860
** values associated with the [sqlite3_stmt_status()] interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5861
** The meanings of the various counters are as follows:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5862
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5863
** <dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5864
** [[SQLITE_STMTSTATUS_FULLSCAN_STEP]] <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5865
** <dd>^This is the number of times that SQLite has stepped forward in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5866
** a table as part of a full table scan.  Large numbers for this counter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5867
** may indicate opportunities for performance improvement through 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5868
** careful use of indices.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5869
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5870
** [[SQLITE_STMTSTATUS_SORT]] <dt>SQLITE_STMTSTATUS_SORT</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5871
** <dd>^This is the number of sort operations that have occurred.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5872
** A non-zero value in this counter may indicate an opportunity to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5873
** improvement performance through careful use of indices.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5874
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5875
** [[SQLITE_STMTSTATUS_AUTOINDEX]] <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5876
** <dd>^This is the number of rows inserted into transient indices that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5877
** were created automatically in order to help joins run faster.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5878
** A non-zero value in this counter may indicate an opportunity to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5879
** improvement performance by adding permanent indices that do not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5880
** need to be reinitialized each time the statement is run.</dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5881
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5882
** </dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5883
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5884
#define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5885
#define SQLITE_STMTSTATUS_SORT              2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5886
#define SQLITE_STMTSTATUS_AUTOINDEX         3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5887
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5888
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5889
** CAPI3REF: Custom Page Cache Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5890
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5891
** The sqlite3_pcache type is opaque.  It is implemented by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5892
** the pluggable module.  The SQLite core has no knowledge of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5893
** its size or internal structure and never deals with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5894
** sqlite3_pcache object except by holding and passing pointers
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5895
** to the object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5896
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5897
** See [sqlite3_pcache_methods] for additional information.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5898
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5899
typedef struct sqlite3_pcache sqlite3_pcache;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5900
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5901
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5902
** CAPI3REF: Application Defined Page Cache.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5903
** KEYWORDS: {page cache}
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5904
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5905
** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5906
** register an alternative page cache implementation by passing in an 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5907
** instance of the sqlite3_pcache_methods structure.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5908
** In many applications, most of the heap memory allocated by 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5909
** SQLite is used for the page cache.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5910
** By implementing a 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5911
** custom page cache using this API, an application can better control
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5912
** the amount of memory consumed by SQLite, the way in which 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5913
** that memory is allocated and released, and the policies used to 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5914
** determine exactly which parts of a database file are cached and for 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5915
** how long.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5916
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5917
** The alternative page cache mechanism is an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5918
** extreme measure that is only needed by the most demanding applications.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5919
** The built-in page cache is recommended for most uses.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5920
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5921
** ^(The contents of the sqlite3_pcache_methods structure are copied to an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5922
** internal buffer by SQLite within the call to [sqlite3_config].  Hence
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5923
** the application may discard the parameter after the call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5924
** [sqlite3_config()] returns.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5925
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5926
** [[the xInit() page cache method]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5927
** ^(The xInit() method is called once for each effective 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5928
** call to [sqlite3_initialize()])^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5929
** (usually only once during the lifetime of the process). ^(The xInit()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5930
** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5931
** The intent of the xInit() method is to set up global data structures 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5932
** required by the custom page cache implementation. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5933
** ^(If the xInit() method is NULL, then the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5934
** built-in default page cache is used instead of the application defined
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5935
** page cache.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5936
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5937
** [[the xShutdown() page cache method]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5938
** ^The xShutdown() method is called by [sqlite3_shutdown()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5939
** It can be used to clean up 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5940
** any outstanding resources before process shutdown, if required.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5941
** ^The xShutdown() method may be NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5942
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5943
** ^SQLite automatically serializes calls to the xInit method,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5944
** so the xInit method need not be threadsafe.  ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5945
** xShutdown method is only called from [sqlite3_shutdown()] so it does
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5946
** not need to be threadsafe either.  All other methods must be threadsafe
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5947
** in multithreaded applications.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5948
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5949
** ^SQLite will never invoke xInit() more than once without an intervening
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5950
** call to xShutdown().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5951
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5952
** [[the xCreate() page cache methods]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5953
** ^SQLite invokes the xCreate() method to construct a new cache instance.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5954
** SQLite will typically create one cache instance for each open database file,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5955
** though this is not guaranteed. ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5956
** first parameter, szPage, is the size in bytes of the pages that must
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5957
** be allocated by the cache.  ^szPage will not be a power of two.  ^szPage
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5958
** will the page size of the database file that is to be cached plus an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5959
** increment (here called "R") of less than 250.  SQLite will use the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5960
** extra R bytes on each page to store metadata about the underlying
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5961
** database page on disk.  The value of R depends
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5962
** on the SQLite version, the target platform, and how SQLite was compiled.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5963
** ^(R is constant for a particular build of SQLite. Except, there are two
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5964
** distinct values of R when SQLite is compiled with the proprietary
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5965
** ZIPVFS extension.)^  ^The second argument to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5966
** xCreate(), bPurgeable, is true if the cache being created will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5967
** be used to cache database pages of a file stored on disk, or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5968
** false if it is used for an in-memory database. The cache implementation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5969
** does not have to do anything special based with the value of bPurgeable;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5970
** it is purely advisory.  ^On a cache where bPurgeable is false, SQLite will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5971
** never invoke xUnpin() except to deliberately delete a page.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5972
** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5973
** false will always have the "discard" flag set to true.  
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5974
** ^Hence, a cache created with bPurgeable false will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5975
** never contain any unpinned pages.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5976
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5977
** [[the xCachesize() page cache method]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5978
** ^(The xCachesize() method may be called at any time by SQLite to set the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5979
** suggested maximum cache-size (number of pages stored by) the cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5980
** instance passed as the first argument. This is the value configured using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5981
** the SQLite "[PRAGMA cache_size]" command.)^  As with the bPurgeable
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5982
** parameter, the implementation is not required to do anything with this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5983
** value; it is advisory only.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5984
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5985
** [[the xPagecount() page cache methods]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5986
** The xPagecount() method must return the number of pages currently
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5987
** stored in the cache, both pinned and unpinned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5988
** 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5989
** [[the xFetch() page cache methods]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5990
** The xFetch() method locates a page in the cache and returns a pointer to 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5991
** the page, or a NULL pointer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5992
** A "page", in this context, means a buffer of szPage bytes aligned at an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5993
** 8-byte boundary. The page to be fetched is determined by the key. ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5994
** minimum key value is 1.  After it has been retrieved using xFetch, the page 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5995
** is considered to be "pinned".
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5996
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5997
** If the requested page is already in the page cache, then the page cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5998
** implementation must return a pointer to the page buffer with its content
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  5999
** intact.  If the requested page is not already in the cache, then the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6000
** cache implementation should use the value of the createFlag
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6001
** parameter to help it determined what action to take:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6002
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6003
** <table border=1 width=85% align=center>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6004
** <tr><th> createFlag <th> Behaviour when page is not already in cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6005
** <tr><td> 0 <td> Do not allocate a new page.  Return NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6006
** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6007
**                 Otherwise return NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6008
** <tr><td> 2 <td> Make every effort to allocate a new page.  Only return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6009
**                 NULL if allocating a new page is effectively impossible.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6010
** </table>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6011
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6012
** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1.  SQLite
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6013
** will only use a createFlag of 2 after a prior call with a createFlag of 1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6014
** failed.)^  In between the to xFetch() calls, SQLite may
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6015
** attempt to unpin one or more cache pages by spilling the content of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6016
** pinned pages to disk and synching the operating system disk cache.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6017
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6018
** [[the xUnpin() page cache method]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6019
** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6020
** as its second argument.  If the third parameter, discard, is non-zero,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6021
** then the page must be evicted from the cache.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6022
** ^If the discard parameter is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6023
** zero, then the page may be discarded or retained at the discretion of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6024
** page cache implementation. ^The page cache implementation
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6025
** may choose to evict unpinned pages at any time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6026
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6027
** The cache must not perform any reference counting. A single 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6028
** call to xUnpin() unpins the page regardless of the number of prior calls 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6029
** to xFetch().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6030
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6031
** [[the xRekey() page cache methods]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6032
** The xRekey() method is used to change the key value associated with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6033
** page passed as the second argument. If the cache
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6034
** previously contains an entry associated with newKey, it must be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6035
** discarded. ^Any prior cache entry associated with newKey is guaranteed not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6036
** to be pinned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6037
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6038
** When SQLite calls the xTruncate() method, the cache must discard all
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6039
** existing cache entries with page numbers (keys) greater than or equal
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6040
** to the value of the iLimit parameter passed to xTruncate(). If any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6041
** of these pages are pinned, they are implicitly unpinned, meaning that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6042
** they can be safely discarded.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6043
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6044
** [[the xDestroy() page cache method]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6045
** ^The xDestroy() method is used to delete a cache allocated by xCreate().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6046
** All resources associated with the specified cache should be freed. ^After
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6047
** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6048
** handle invalid, and will not use it with any other sqlite3_pcache_methods
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6049
** functions.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6050
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6051
typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6052
struct sqlite3_pcache_methods {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6053
  void *pArg;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6054
  int (*xInit)(void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6055
  void (*xShutdown)(void*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6056
  sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6057
  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6058
  int (*xPagecount)(sqlite3_pcache*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6059
  void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6060
  void (*xUnpin)(sqlite3_pcache*, void*, int discard);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6061
  void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6062
  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6063
  void (*xDestroy)(sqlite3_pcache*);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6064
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6065
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6066
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6067
** CAPI3REF: Online Backup Object
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6068
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6069
** The sqlite3_backup object records state information about an ongoing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6070
** online backup operation.  ^The sqlite3_backup object is created by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6071
** a call to [sqlite3_backup_init()] and is destroyed by a call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6072
** [sqlite3_backup_finish()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6073
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6074
** See Also: [Using the SQLite Online Backup API]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6075
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6076
typedef struct sqlite3_backup sqlite3_backup;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6077
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6078
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6079
** CAPI3REF: Online Backup API.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6080
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6081
** The backup API copies the content of one database into another.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6082
** It is useful either for creating backups of databases or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6083
** for copying in-memory databases to or from persistent files. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6084
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6085
** See Also: [Using the SQLite Online Backup API]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6086
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6087
** ^SQLite holds a write transaction open on the destination database file
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6088
** for the duration of the backup operation.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6089
** ^The source database is read-locked only while it is being read;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6090
** it is not locked continuously for the entire backup operation.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6091
** ^Thus, the backup may be performed on a live source database without
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6092
** preventing other database connections from
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6093
** reading or writing to the source database while the backup is underway.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6094
** 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6095
** ^(To perform a backup operation: 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6096
**   <ol>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6097
**     <li><b>sqlite3_backup_init()</b> is called once to initialize the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6098
**         backup, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6099
**     <li><b>sqlite3_backup_step()</b> is called one or more times to transfer 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6100
**         the data between the two databases, and finally
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6101
**     <li><b>sqlite3_backup_finish()</b> is called to release all resources 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6102
**         associated with the backup operation. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6103
**   </ol>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6104
** There should be exactly one call to sqlite3_backup_finish() for each
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6105
** successful call to sqlite3_backup_init().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6106
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6107
** [[sqlite3_backup_init()]] <b>sqlite3_backup_init()</b>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6108
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6109
** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6110
** [database connection] associated with the destination database 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6111
** and the database name, respectively.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6112
** ^The database name is "main" for the main database, "temp" for the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6113
** temporary database, or the name specified after the AS keyword in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6114
** an [ATTACH] statement for an attached database.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6115
** ^The S and M arguments passed to 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6116
** sqlite3_backup_init(D,N,S,M) identify the [database connection]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6117
** and database name of the source database, respectively.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6118
** ^The source and destination [database connections] (parameters S and D)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6119
** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6120
** an error.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6121
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6122
** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6123
** returned and an error code and error message are stored in the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6124
** destination [database connection] D.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6125
** ^The error code and message for the failed call to sqlite3_backup_init()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6126
** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6127
** [sqlite3_errmsg16()] functions.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6128
** ^A successful call to sqlite3_backup_init() returns a pointer to an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6129
** [sqlite3_backup] object.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6130
** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6131
** sqlite3_backup_finish() functions to perform the specified backup 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6132
** operation.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6133
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6134
** [[sqlite3_backup_step()]] <b>sqlite3_backup_step()</b>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6135
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6136
** ^Function sqlite3_backup_step(B,N) will copy up to N pages between 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6137
** the source and destination databases specified by [sqlite3_backup] object B.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6138
** ^If N is negative, all remaining source pages are copied. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6139
** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6140
** are still more pages to be copied, then the function returns [SQLITE_OK].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6141
** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6142
** from source to destination, then it returns [SQLITE_DONE].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6143
** ^If an error occurs while running sqlite3_backup_step(B,N),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6144
** then an [error code] is returned. ^As well as [SQLITE_OK] and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6145
** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6146
** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6147
** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6148
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6149
** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6150
** <ol>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6151
** <li> the destination database was opened read-only, or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6152
** <li> the destination database is using write-ahead-log journaling
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6153
** and the destination and source page sizes differ, or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6154
** <li> the destination database is an in-memory database and the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6155
** destination and source page sizes differ.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6156
** </ol>)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6157
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6158
** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6159
** the [sqlite3_busy_handler | busy-handler function]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6160
** is invoked (if one is specified). ^If the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6161
** busy-handler returns non-zero before the lock is available, then 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6162
** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6163
** sqlite3_backup_step() can be retried later. ^If the source
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6164
** [database connection]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6165
** is being used to write to the source database when sqlite3_backup_step()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6166
** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6167
** case the call to sqlite3_backup_step() can be retried later on. ^(If
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6168
** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6169
** [SQLITE_READONLY] is returned, then 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6170
** there is no point in retrying the call to sqlite3_backup_step(). These 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6171
** errors are considered fatal.)^  The application must accept 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6172
** that the backup operation has failed and pass the backup operation handle 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6173
** to the sqlite3_backup_finish() to release associated resources.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6174
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6175
** ^The first call to sqlite3_backup_step() obtains an exclusive lock
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6176
** on the destination file. ^The exclusive lock is not released until either 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6177
** sqlite3_backup_finish() is called or the backup operation is complete 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6178
** and sqlite3_backup_step() returns [SQLITE_DONE].  ^Every call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6179
** sqlite3_backup_step() obtains a [shared lock] on the source database that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6180
** lasts for the duration of the sqlite3_backup_step() call.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6181
** ^Because the source database is not locked between calls to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6182
** sqlite3_backup_step(), the source database may be modified mid-way
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6183
** through the backup process.  ^If the source database is modified by an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6184
** external process or via a database connection other than the one being
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6185
** used by the backup operation, then the backup will be automatically
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6186
** restarted by the next call to sqlite3_backup_step(). ^If the source 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6187
** database is modified by the using the same database connection as is used
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6188
** by the backup operation, then the backup database is automatically
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6189
** updated at the same time.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6190
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6191
** [[sqlite3_backup_finish()]] <b>sqlite3_backup_finish()</b>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6192
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6193
** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6194
** application wishes to abandon the backup operation, the application
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6195
** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6196
** ^The sqlite3_backup_finish() interfaces releases all
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6197
** resources associated with the [sqlite3_backup] object. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6198
** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6199
** active write-transaction on the destination database is rolled back.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6200
** The [sqlite3_backup] object is invalid
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6201
** and may not be used following a call to sqlite3_backup_finish().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6202
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6203
** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6204
** sqlite3_backup_step() errors occurred, regardless or whether or not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6205
** sqlite3_backup_step() completed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6206
** ^If an out-of-memory condition or IO error occurred during any prior
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6207
** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6208
** sqlite3_backup_finish() returns the corresponding [error code].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6209
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6210
** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6211
** is not a permanent error and does not affect the return value of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6212
** sqlite3_backup_finish().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6213
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6214
** [[sqlite3_backup__remaining()]] [[sqlite3_backup_pagecount()]]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6215
** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6216
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6217
** ^Each call to sqlite3_backup_step() sets two values inside
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6218
** the [sqlite3_backup] object: the number of pages still to be backed
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6219
** up and the total number of pages in the source database file.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6220
** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6221
** retrieve these two values, respectively.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6222
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6223
** ^The values returned by these functions are only updated by
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6224
** sqlite3_backup_step(). ^If the source database is modified during a backup
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6225
** operation, then the values are not updated to account for any extra
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6226
** pages that need to be updated or the size of the source database file
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6227
** changing.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6228
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6229
** <b>Concurrent Usage of Database Handles</b>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6230
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6231
** ^The source [database connection] may be used by the application for other
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6232
** purposes while a backup operation is underway or being initialized.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6233
** ^If SQLite is compiled and configured to support threadsafe database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6234
** connections, then the source database connection may be used concurrently
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6235
** from within other threads.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6236
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6237
** However, the application must guarantee that the destination 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6238
** [database connection] is not passed to any other API (by any thread) after 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6239
** sqlite3_backup_init() is called and before the corresponding call to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6240
** sqlite3_backup_finish().  SQLite does not currently check to see
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6241
** if the application incorrectly accesses the destination [database connection]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6242
** and so no error code is reported, but the operations may malfunction
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6243
** nevertheless.  Use of the destination database connection while a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6244
** backup is in progress might also also cause a mutex deadlock.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6245
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6246
** If running in [shared cache mode], the application must
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6247
** guarantee that the shared cache used by the destination database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6248
** is not accessed while the backup is running. In practice this means
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6249
** that the application must guarantee that the disk file being 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6250
** backed up to is not accessed by any connection within the process,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6251
** not just the specific connection that was passed to sqlite3_backup_init().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6252
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6253
** The [sqlite3_backup] object itself is partially threadsafe. Multiple 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6254
** threads may safely make multiple concurrent calls to sqlite3_backup_step().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6255
** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6256
** APIs are not strictly speaking threadsafe. If they are invoked at the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6257
** same time as another thread is invoking sqlite3_backup_step() it is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6258
** possible that they return invalid values.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6259
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6260
SQLITE_API sqlite3_backup *sqlite3_backup_init(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6261
  sqlite3 *pDest,                        /* Destination database handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6262
  const char *zDestName,                 /* Destination database name */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6263
  sqlite3 *pSource,                      /* Source database handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6264
  const char *zSourceName                /* Source database name */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6265
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6266
SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6267
SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6268
SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6269
SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6270
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6271
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6272
** CAPI3REF: Unlock Notification
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6273
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6274
** ^When running in shared-cache mode, a database operation may fail with
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6275
** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6276
** individual tables within the shared-cache cannot be obtained. See
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6277
** [SQLite Shared-Cache Mode] for a description of shared-cache locking. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6278
** ^This API may be used to register a callback that SQLite will invoke 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6279
** when the connection currently holding the required lock relinquishes it.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6280
** ^This API is only available if the library was compiled with the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6281
** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6282
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6283
** See Also: [Using the SQLite Unlock Notification Feature].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6284
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6285
** ^Shared-cache locks are released when a database connection concludes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6286
** its current transaction, either by committing it or rolling it back. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6287
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6288
** ^When a connection (known as the blocked connection) fails to obtain a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6289
** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6290
** identity of the database connection (the blocking connection) that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6291
** has locked the required resource is stored internally. ^After an 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6292
** application receives an SQLITE_LOCKED error, it may call the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6293
** sqlite3_unlock_notify() method with the blocked connection handle as 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6294
** the first argument to register for a callback that will be invoked
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6295
** when the blocking connections current transaction is concluded. ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6296
** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6297
** call that concludes the blocking connections transaction.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6298
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6299
** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6300
** there is a chance that the blocking connection will have already
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6301
** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6302
** If this happens, then the specified callback is invoked immediately,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6303
** from within the call to sqlite3_unlock_notify().)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6304
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6305
** ^If the blocked connection is attempting to obtain a write-lock on a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6306
** shared-cache table, and more than one other connection currently holds
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6307
** a read-lock on the same table, then SQLite arbitrarily selects one of 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6308
** the other connections to use as the blocking connection.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6309
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6310
** ^(There may be at most one unlock-notify callback registered by a 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6311
** blocked connection. If sqlite3_unlock_notify() is called when the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6312
** blocked connection already has a registered unlock-notify callback,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6313
** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6314
** called with a NULL pointer as its second argument, then any existing
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6315
** unlock-notify callback is canceled. ^The blocked connections 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6316
** unlock-notify callback may also be canceled by closing the blocked
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6317
** connection using [sqlite3_close()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6318
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6319
** The unlock-notify callback is not reentrant. If an application invokes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6320
** any sqlite3_xxx API functions from within an unlock-notify callback, a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6321
** crash or deadlock may be the result.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6322
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6323
** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6324
** returns SQLITE_OK.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6325
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6326
** <b>Callback Invocation Details</b>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6327
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6328
** When an unlock-notify callback is registered, the application provides a 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6329
** single void* pointer that is passed to the callback when it is invoked.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6330
** However, the signature of the callback function allows SQLite to pass
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6331
** it an array of void* context pointers. The first argument passed to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6332
** an unlock-notify callback is a pointer to an array of void* pointers,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6333
** and the second is the number of entries in the array.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6334
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6335
** When a blocking connections transaction is concluded, there may be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6336
** more than one blocked connection that has registered for an unlock-notify
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6337
** callback. ^If two or more such blocked connections have specified the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6338
** same callback function, then instead of invoking the callback function
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6339
** multiple times, it is invoked once with the set of void* context pointers
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6340
** specified by the blocked connections bundled together into an array.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6341
** This gives the application an opportunity to prioritize any actions 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6342
** related to the set of unblocked database connections.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6343
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6344
** <b>Deadlock Detection</b>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6345
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6346
** Assuming that after registering for an unlock-notify callback a 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6347
** database waits for the callback to be issued before taking any further
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6348
** action (a reasonable assumption), then using this API may cause the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6349
** application to deadlock. For example, if connection X is waiting for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6350
** connection Y's transaction to be concluded, and similarly connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6351
** Y is waiting on connection X's transaction, then neither connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6352
** will proceed and the system may remain deadlocked indefinitely.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6353
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6354
** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6355
** detection. ^If a given call to sqlite3_unlock_notify() would put the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6356
** system in a deadlocked state, then SQLITE_LOCKED is returned and no
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6357
** unlock-notify callback is registered. The system is said to be in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6358
** a deadlocked state if connection A has registered for an unlock-notify
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6359
** callback on the conclusion of connection B's transaction, and connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6360
** B has itself registered for an unlock-notify callback when connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6361
** A's transaction is concluded. ^Indirect deadlock is also detected, so
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6362
** the system is also considered to be deadlocked if connection B has
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6363
** registered for an unlock-notify callback on the conclusion of connection
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6364
** C's transaction, where connection C is waiting on connection A. ^Any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6365
** number of levels of indirection are allowed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6366
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6367
** <b>The "DROP TABLE" Exception</b>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6368
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6369
** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6370
** always appropriate to call sqlite3_unlock_notify(). There is however,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6371
** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6372
** SQLite checks if there are any currently executing SELECT statements
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6373
** that belong to the same connection. If there are, SQLITE_LOCKED is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6374
** returned. In this case there is no "blocking connection", so invoking
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6375
** sqlite3_unlock_notify() results in the unlock-notify callback being
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6376
** invoked immediately. If the application then re-attempts the "DROP TABLE"
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6377
** or "DROP INDEX" query, an infinite loop might be the result.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6378
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6379
** One way around this problem is to check the extended error code returned
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6380
** by an sqlite3_step() call. ^(If there is a blocking connection, then the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6381
** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6382
** the special "DROP TABLE/INDEX" case, the extended error code is just 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6383
** SQLITE_LOCKED.)^
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6384
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6385
SQLITE_API int sqlite3_unlock_notify(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6386
  sqlite3 *pBlocked,                          /* Waiting connection */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6387
  void (*xNotify)(void **apArg, int nArg),    /* Callback function to invoke */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6388
  void *pNotifyArg                            /* Argument to pass to xNotify */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6389
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6390
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6391
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6392
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6393
** CAPI3REF: String Comparison
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6394
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6395
** ^The [sqlite3_strnicmp()] API allows applications and extensions to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6396
** compare the contents of two buffers containing UTF-8 strings in a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6397
** case-independent fashion, using the same definition of case independence 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6398
** that SQLite uses internally when comparing identifiers.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6399
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6400
SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6401
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6402
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6403
** CAPI3REF: Error Logging Interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6404
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6405
** ^The [sqlite3_log()] interface writes a message into the error log
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6406
** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6407
** ^If logging is enabled, the zFormat string and subsequent arguments are
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6408
** used with [sqlite3_snprintf()] to generate the final output string.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6409
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6410
** The sqlite3_log() interface is intended for use by extensions such as
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6411
** virtual tables, collating functions, and SQL functions.  While there is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6412
** nothing to prevent an application from calling sqlite3_log(), doing so
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6413
** is considered bad form.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6414
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6415
** The zFormat string must not be NULL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6416
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6417
** To avoid deadlocks and other threading problems, the sqlite3_log() routine
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6418
** will not use dynamically allocated memory.  The log message is stored in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6419
** a fixed-length buffer on the stack.  If the log message is longer than
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6420
** a few hundred characters, it will be truncated to the length of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6421
** buffer.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6422
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6423
SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6424
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6425
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6426
** CAPI3REF: Write-Ahead Log Commit Hook
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6427
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6428
** ^The [sqlite3_wal_hook()] function is used to register a callback that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6429
** will be invoked each time a database connection commits data to a
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6430
** [write-ahead log] (i.e. whenever a transaction is committed in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6431
** [journal_mode | journal_mode=WAL mode]). 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6432
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6433
** ^The callback is invoked by SQLite after the commit has taken place and 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6434
** the associated write-lock on the database released, so the implementation 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6435
** may read, write or [checkpoint] the database as required.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6436
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6437
** ^The first parameter passed to the callback function when it is invoked
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6438
** is a copy of the third parameter passed to sqlite3_wal_hook() when
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6439
** registering the callback. ^The second is a copy of the database handle.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6440
** ^The third parameter is the name of the database that was written to -
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6441
** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6442
** is the number of pages currently in the write-ahead log file,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6443
** including those that were just committed.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6444
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6445
** The callback function should normally return [SQLITE_OK].  ^If an error
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6446
** code is returned, that error will propagate back up through the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6447
** SQLite code base to cause the statement that provoked the callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6448
** to report an error, though the commit will have still occurred. If the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6449
** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6450
** that does not correspond to any valid SQLite error code, the results
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6451
** are undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6452
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6453
** A single database handle may have at most a single write-ahead log callback 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6454
** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6455
** previously registered write-ahead log callback. ^Note that the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6456
** [sqlite3_wal_autocheckpoint()] interface and the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6457
** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6458
** those overwrite any prior [sqlite3_wal_hook()] settings.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6459
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6460
SQLITE_API void *sqlite3_wal_hook(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6461
  sqlite3*, 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6462
  int(*)(void *,sqlite3*,const char*,int),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6463
  void*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6464
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6465
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6466
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6467
** CAPI3REF: Configure an auto-checkpoint
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6468
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6469
** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6470
** [sqlite3_wal_hook()] that causes any database on [database connection] D
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6471
** to automatically [checkpoint]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6472
** after committing a transaction if there are N or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6473
** more frames in the [write-ahead log] file.  ^Passing zero or 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6474
** a negative value as the nFrame parameter disables automatic
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6475
** checkpoints entirely.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6476
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6477
** ^The callback registered by this function replaces any existing callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6478
** registered using [sqlite3_wal_hook()].  ^Likewise, registering a callback
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6479
** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6480
** configured by this function.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6481
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6482
** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6483
** from SQL.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6484
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6485
** ^Every new [database connection] defaults to having the auto-checkpoint
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6486
** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6487
** pages.  The use of this interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6488
** is only necessary if the default setting is found to be suboptimal
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6489
** for a particular application.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6490
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6491
SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6492
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6493
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6494
** CAPI3REF: Checkpoint a database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6495
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6496
** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6497
** on [database connection] D to be [checkpointed].  ^If X is NULL or an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6498
** empty string, then a checkpoint is run on all databases of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6499
** connection D.  ^If the database connection D is not in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6500
** [WAL | write-ahead log mode] then this interface is a harmless no-op.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6501
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6502
** ^The [wal_checkpoint pragma] can be used to invoke this interface
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6503
** from SQL.  ^The [sqlite3_wal_autocheckpoint()] interface and the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6504
** [wal_autocheckpoint pragma] can be used to cause this interface to be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6505
** run whenever the WAL reaches a certain size threshold.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6506
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6507
** See also: [sqlite3_wal_checkpoint_v2()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6508
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6509
SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6510
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6511
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6512
** CAPI3REF: Checkpoint a database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6513
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6514
** Run a checkpoint operation on WAL database zDb attached to database 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6515
** handle db. The specific operation is determined by the value of the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6516
** eMode parameter:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6517
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6518
** <dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6519
** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6520
**   Checkpoint as many frames as possible without waiting for any database 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6521
**   readers or writers to finish. Sync the db file if all frames in the log
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6522
**   are checkpointed. This mode is the same as calling 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6523
**   sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6524
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6525
** <dt>SQLITE_CHECKPOINT_FULL<dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6526
**   This mode blocks (calls the busy-handler callback) until there is no
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6527
**   database writer and all readers are reading from the most recent database
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6528
**   snapshot. It then checkpoints all frames in the log file and syncs the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6529
**   database file. This call blocks database writers while it is running,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6530
**   but not database readers.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6531
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6532
** <dt>SQLITE_CHECKPOINT_RESTART<dd>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6533
**   This mode works the same way as SQLITE_CHECKPOINT_FULL, except after 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6534
**   checkpointing the log file it blocks (calls the busy-handler callback)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6535
**   until all readers are reading from the database file only. This ensures 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6536
**   that the next client to write to the database file restarts the log file 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6537
**   from the beginning. This call blocks database writers while it is running,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6538
**   but not database readers.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6539
** </dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6540
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6541
** If pnLog is not NULL, then *pnLog is set to the total number of frames in
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6542
** the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6543
** the total number of checkpointed frames (including any that were already
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6544
** checkpointed when this function is called). *pnLog and *pnCkpt may be
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6545
** populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6546
** If no values are available because of an error, they are both set to -1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6547
** before returning to communicate this to the caller.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6548
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6549
** All calls obtain an exclusive "checkpoint" lock on the database file. If
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6550
** any other process is running a checkpoint operation at the same time, the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6551
** lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6552
** busy-handler configured, it will not be invoked in this case.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6553
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6554
** The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6555
** "writer" lock on the database file. If the writer lock cannot be obtained
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6556
** immediately, and a busy-handler is configured, it is invoked and the writer
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6557
** lock retried until either the busy-handler returns 0 or the lock is
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6558
** successfully obtained. The busy-handler is also invoked while waiting for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6559
** database readers as described above. If the busy-handler returns 0 before
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6560
** the writer lock is obtained or while waiting for database readers, the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6561
** checkpoint operation proceeds from that point in the same way as 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6562
** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6563
** without blocking any further. SQLITE_BUSY is returned in this case.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6564
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6565
** If parameter zDb is NULL or points to a zero length string, then the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6566
** specified operation is attempted on all WAL databases. In this case the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6567
** values written to output parameters *pnLog and *pnCkpt are undefined. If 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6568
** an SQLITE_BUSY error is encountered when processing one or more of the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6569
** attached WAL databases, the operation is still attempted on any remaining 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6570
** attached databases and SQLITE_BUSY is returned to the caller. If any other 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6571
** error occurs while processing an attached database, processing is abandoned 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6572
** and the error code returned to the caller immediately. If no error 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6573
** (SQLITE_BUSY or otherwise) is encountered while processing the attached 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6574
** databases, SQLITE_OK is returned.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6575
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6576
** If database zDb is the name of an attached database that is not in WAL
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6577
** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6578
** zDb is not NULL (or a zero length string) and is not the name of any
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6579
** attached database, SQLITE_ERROR is returned to the caller.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6580
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6581
SQLITE_API int sqlite3_wal_checkpoint_v2(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6582
  sqlite3 *db,                    /* Database handle */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6583
  const char *zDb,                /* Name of attached database (or NULL) */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6584
  int eMode,                      /* SQLITE_CHECKPOINT_* value */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6585
  int *pnLog,                     /* OUT: Size of WAL log in frames */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6586
  int *pnCkpt                     /* OUT: Total number of frames checkpointed */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6587
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6588
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6589
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6590
** CAPI3REF: Checkpoint operation parameters
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6591
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6592
** These constants can be used as the 3rd parameter to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6593
** [sqlite3_wal_checkpoint_v2()].  See the [sqlite3_wal_checkpoint_v2()]
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6594
** documentation for additional information about the meaning and use of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6595
** each of these values.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6596
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6597
#define SQLITE_CHECKPOINT_PASSIVE 0
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6598
#define SQLITE_CHECKPOINT_FULL    1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6599
#define SQLITE_CHECKPOINT_RESTART 2
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6600
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6601
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6602
** CAPI3REF: Virtual Table Interface Configuration
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6603
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6604
** This function may be called by either the [xConnect] or [xCreate] method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6605
** of a [virtual table] implementation to configure
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6606
** various facets of the virtual table interface.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6607
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6608
** If this interface is invoked outside the context of an xConnect or
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6609
** xCreate virtual table method then the behavior is undefined.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6610
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6611
** At present, there is only one option that may be configured using
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6612
** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].)  Further options
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6613
** may be added in the future.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6614
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6615
SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6616
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6617
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6618
** CAPI3REF: Virtual Table Configuration Options
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6619
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6620
** These macros define the various options to the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6621
** [sqlite3_vtab_config()] interface that [virtual table] implementations
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6622
** can use to customize and optimize their behavior.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6623
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6624
** <dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6625
** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6626
** <dd>Calls of the form
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6627
** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6628
** where X is an integer.  If X is zero, then the [virtual table] whose
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6629
** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6630
** support constraints.  In this configuration (which is the default) if
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6631
** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6632
** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6633
** specified as part of the users SQL statement, regardless of the actual
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6634
** ON CONFLICT mode specified.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6635
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6636
** If X is non-zero, then the virtual table implementation guarantees
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6637
** that if [xUpdate] returns [SQLITE_CONSTRAINT], it will do so before
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6638
** any modifications to internal or persistent data structures have been made.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6639
** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6640
** is able to roll back a statement or database transaction, and abandon
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6641
** or continue processing the current SQL statement as appropriate. 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6642
** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6643
** [SQLITE_CONSTRAINT], SQLite handles this as if the ON CONFLICT mode
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6644
** had been ABORT.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6645
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6646
** Virtual table implementations that are required to handle OR REPLACE
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6647
** must do so within the [xUpdate] method. If a call to the 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6648
** [sqlite3_vtab_on_conflict()] function indicates that the current ON 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6649
** CONFLICT policy is REPLACE, the virtual table implementation should 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6650
** silently replace the appropriate rows within the xUpdate callback and
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6651
** return SQLITE_OK. Or, if this is not possible, it may return
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6652
** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT 
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6653
** constraint handling.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6654
** </dl>
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6655
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6656
#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6657
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6658
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6659
** CAPI3REF: Determine The Virtual Table Conflict Policy
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6660
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6661
** This function may only be called from within a call to the [xUpdate] method
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6662
** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6663
** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6664
** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6665
** of the SQL statement that triggered the call to the [xUpdate] method of the
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6666
** [virtual table].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6667
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6668
SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6669
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6670
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6671
** CAPI3REF: Conflict resolution modes
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6672
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6673
** These constants are returned by [sqlite3_vtab_on_conflict()] to
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6674
** inform a [virtual table] implementation what the [ON CONFLICT] mode
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6675
** is for the SQL statement being evaluated.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6676
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6677
** Note that the [SQLITE_IGNORE] constant is also used as a potential
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6678
** return value from the [sqlite3_set_authorizer()] callback and that
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6679
** [SQLITE_ABORT] is also a [result code].
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6680
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6681
#define SQLITE_ROLLBACK 1
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6682
/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6683
#define SQLITE_FAIL     3
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6684
/* #define SQLITE_ABORT 4  // Also an error code */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6685
#define SQLITE_REPLACE  5
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6686
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6687
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6688
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6689
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6690
** Undo the hack that converts floating point types to integer for
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6691
** builds on processors without floating point support.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6692
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6693
#ifdef SQLITE_OMIT_FLOATING_POINT
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6694
# undef double
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6695
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6696
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6697
#ifdef __cplusplus
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6698
}  /* End of the 'extern "C"' block */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6699
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6700
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6701
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6702
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6703
** 2010 August 30
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6704
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6705
** The author disclaims copyright to this source code.  In place of
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6706
** a legal notice, here is a blessing:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6707
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6708
**    May you do good and not evil.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6709
**    May you find forgiveness for yourself and forgive others.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6710
**    May you share freely, never taking more than you give.
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6711
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6712
*************************************************************************
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6713
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6714
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6715
#ifndef _SQLITE3RTREE_H_
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6716
#define _SQLITE3RTREE_H_
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6717
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6718
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6719
#ifdef __cplusplus
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6720
extern "C" {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6721
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6722
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6723
typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6724
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6725
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6726
** Register a geometry callback named zGeom that can be used as part of an
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6727
** R-Tree geometry query as follows:
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6728
**
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6729
**   SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6730
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6731
SQLITE_API int sqlite3_rtree_geometry_callback(
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6732
  sqlite3 *db,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6733
  const char *zGeom,
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6734
  int (*xGeom)(sqlite3_rtree_geometry *, int nCoord, double *aCoord, int *pRes),
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6735
  void *pContext
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6736
);
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6737
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6738
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6739
/*
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6740
** A pointer to a structure of the following type is passed as the first
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6741
** argument to callbacks registered using rtree_geometry_callback().
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6742
*/
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6743
struct sqlite3_rtree_geometry {
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6744
  void *pContext;                 /* Copy of pContext passed to s_r_g_c() */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6745
  int nParam;                     /* Size of array aParam[] */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6746
  double *aParam;                 /* Parameters passed to SQL geom function */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6747
  void *pUser;                    /* Callback implementation user data */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6748
  void (*xDelUser)(void *);       /* Called by SQLite to clean up pUser */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6749
};
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6750
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6751
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6752
#ifdef __cplusplus
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6753
}  /* end of the 'extern "C"' block */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6754
#endif
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6755
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6756
#endif  /* ifndef _SQLITE3RTREE_H_ */
9aa5114326e8 Carry the amalgamated sqlite3 around with volta, rather than requiring
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
  6757